[GH-ISSUE #189] Modernize README as HTML docs site with sidebar navigation #114

New issue

Closed

opened 2026-05-06 12:37:36 +02:00 by BreizhHardware · 0 comments

BreizhHardware commented

2026-05-06 12:37:36 +02:00

Owner

Originally created by @patrickchugh on GitHub (Apr 14, 2026).
Original GitHub issue: https://github.com/patrickchugh/terravision/issues/189

Summary

The current README.md is a single long markdown file. We should publish a proper documentation site (hosted via GitHub Pages) with a sidebar of links, search, and a more attractive, professional layout — similar to what a Sphinx template or MkDocs Material theme produces.

Motivation

Easier navigation for new users (sidebar with sections: Install, Quickstart, CLI Reference, Examples, Troubleshooting, etc.)
More professional first impression on the project landing page
Better discoverability of features currently buried deep in the README
Room to add screenshots/diagrams without bloating a single file

Proposal

Split README.md into topic-scoped pages under docs/
Use a static site generator (candidates: MkDocs Material, Sphinx + Furo, or Docusaurus) to render HTML
Publish via GitHub Pages on push to main (GitHub Actions workflow)
Keep a short README.md at the repo root linking to the hosted docs

Acceptance Criteria

Docs site live on GitHub Pages
Sidebar navigation with logical section grouping
Search functionality
Existing README content fully migrated (nothing lost)
CI workflow rebuilds docs on merge to main
Root README.md slimmed down with link to hosted docs

Originally created by @patrickchugh on GitHub (Apr 14, 2026). Original GitHub issue: https://github.com/patrickchugh/terravision/issues/189 ## Summary The current `README.md` is a single long markdown file. We should publish a proper documentation site (hosted via GitHub Pages) with a sidebar of links, search, and a more attractive, professional layout — similar to what a Sphinx template or MkDocs Material theme produces. ## Motivation - Easier navigation for new users (sidebar with sections: Install, Quickstart, CLI Reference, Examples, Troubleshooting, etc.) - More professional first impression on the project landing page - Better discoverability of features currently buried deep in the README - Room to add screenshots/diagrams without bloating a single file ## Proposal - Split `README.md` into topic-scoped pages under `docs/` - Use a static site generator (candidates: **MkDocs Material**, **Sphinx + Furo**, or **Docusaurus**) to render HTML - Publish via GitHub Pages on push to `main` (GitHub Actions workflow) - Keep a short `README.md` at the repo root linking to the hosted docs ## Acceptance Criteria - [ ] Docs site live on GitHub Pages - [ ] Sidebar navigation with logical section grouping - [ ] Search functionality - [ ] Existing README content fully migrated (nothing lost) - [ ] CI workflow rebuilds docs on merge to `main` - [ ] Root `README.md` slimmed down with link to hosted docs