Throng Docs

Documentation site for the Throng platform, built with MkDocs and the Material theme. Dependencies are managed with uv.

throng_docs/
├── docs/             # Markdown source for every page
│   └── index.md      # Home page
├── mkdocs.yml        # Site config (theme, nav, extensions)
├── pyproject.toml    # Python deps (managed by uv)
├── uv.lock           # Locked dep versions — commit this
└── site/             # Built HTML output (gitignored)

brew install uv          # if you don't already have it
uv sync                  # creates .venv/ and installs locked deps

uv sync reads pyproject.toml + uv.lock and produces a .venv/ with the exact versions everyone else is using. Run it after pulling changes that touch dependencies.

All commands assume you're in the repo root. uv run <cmd> runs <cmd> inside the project's virtualenv without needing to activate it.

mkdocs serve watches docs/ and mkdocs.yml and auto-reloads the browser on every save — leave it running while you write.

• New page → create docs/some-page.md. It appears in the sidebar automatically. The first # Heading becomes the page title.
• Subsection → create docs/guides/intro.md. The folder becomes a nav group; an optional docs/guides/index.md becomes that group's landing page.
• Custom nav order → uncomment and populate the nav: block in mkdocs.yml. Without it, files are listed alphabetically.
• Images / assets → put them in docs/ (e.g. docs/img/foo.png) and reference with relative paths: ![alt](img/foo.png).

Commit pyproject.toml and uv.lock after any of these. Never commit .venv/.

Run uv run mkdocs gh-deploy to build and publish to the gh-pages branch. The live site updates within a minute or two.

• MkDocs: https://www.mkdocs.org/
• Material theme reference: https://squidfunk.github.io/mkdocs-material/reference/
• Material setup guide: https://squidfunk.github.io/mkdocs-material/setup/
• uv docs: https://docs.astral.sh/uv/