Skip to content

Docs Site - 2026-10-19

Context

After the first PyPI release (1.1.1) the docs were only readable as markdown on GitHub, in the generated wiki, or in Obsidian. None of them is searchable or has a page a new user can start from, and the README's quickstart stopped at testo run without saying how to see a regression or add CI.

Decision

  • A Getting Started note walks a new user from pip install testo-core to the GitHub Action. Every command in it was run against the PyPI release. examples/getting-started/ is the same project, and the getting_started job in ci.yml runs it through ./integrations/github-action on every pull request, so the guide fails CI when it stops working.
  • MkDocs Material renders docs/ as a site (mkdocs.yml), published under /docs/ of the existing Pages demo by pages-demo.yml: https://taltal-beep.github.io/testosterone/docs/. One Pages deployment keeps one URL to share and no second workflow writing to Pages.
  • The notes don't change for the site. scripts/mkdocs_hooks.py bridges the gaps at build time: Index.md becomes the home page, URLs are lowercase and hyphenated, the vault's status key is dropped (Material would show it as a badge on every page), and links that leave docs/ point at GitHub, the same rewrite the wiki export does. Anchors use GitHub's slug rules, so links written for GitHub resolve on the site.
  • Broken links fail CI. The docs_site job runs mkdocs build --strict. Archive/ is built but kept out of the navigation.

Consequences

  • The vault now has three readers (GitHub, the wiki, the site) and one source. A new note needs a nav entry in mkdocs.yml to show in the site's menu; without one it is still built and searchable.
  • pip install -e ".[docs]" then mkdocs serve previews the site locally.
  • Material 9.x pins MkDocs below 2.0, which drops plugins and themes. The docs extra pins mkdocs-material<10 until that settles.
  • Mermaid diagrams render in the browser from a CDN script Material loads.