Skip to content

docs: build a static docs site (MkDocs) from the existing docs/ tree #13

Open

Description

@root3315

Observation

v1.4.1 reorganised the flat docs/ root into five thematic subdirectories (guides/, design/, budgets/, reference/, project/) plus a freshly-written docs/README.md index. Every markdown link resolves; structure is clean.

What we don't have: a rendered static site. GitHub renders Markdown one file at a time — navigation between docs/guides/OPERATIONS_GUIDE.md, docs/ops/cansat_standard.md, and docs/design/architecture.md requires clicking back and forward, and there's no search.

Why it matters

A handful of per-profile ops guides + 8 ADRs + 5 budget docs is the right size to start justifying a site. Competition judges and external reviewers expect a "Documentation" link that opens a searchable site, not a GitHub tree view.

Proposal — MkDocs + Material theme

Minimal setup:

mkdocs.yml            # nav derived from existing docs/ tree
docs/                 # already organised; no reorg needed
.github/workflows/    # publish to gh-pages on every push to master (see #5)

Nav structure (mirroring the index in docs/README.md):

  • Home → docs/README.md
  • Guides → docs/guides/*
  • Ops (per profile) → docs/ops/*
  • Design → docs/design/*
  • Budgets → docs/budgets/*
  • Reference → docs/reference/*
  • ADR → docs/adr/*
  • Project status → docs/project/*
  • Hardware / reliability / quality / security (separate sections)

Definition of done

  • mkdocs.yml at repo root.
  • mkdocs serve renders every existing file without broken links.
  • mkdocs build produces site/ cleanly.
  • .github/workflows/docs.yml publishes to gh-pages branch on every master push (depends on CI: add GitHub Actions workflow (no .github/workflows/ currently exists) #5).
  • README.md "Documentation" section adds a link to the live site (e.g. https://root3315.github.io/unisat/).
  • Search works; ADR index links still resolve; docs/diagrams/*.svg embed correctly.

Depends on #5 (GitHub Actions). Does not change any existing markdown.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions