phylax-docs

User documentation for Phylax - the local-first, zero-knowledge living health profile PWA.

Live site: https://astrapi69.github.io/phylax-docs/

The Phylax PWA at astrapi69.github.io/phylax/ owns the /phylax/ path on GitHub Pages, including its service worker scope. Hosting documentation under a sibling subpath would conflict with the SW scope, so the docs live in their own GitHub Pages site at astrapi69.github.io/phylax-docs/.

See docs/MAINTENANCE.md in the main Phylax repo for the full rationale and cross-repo coordination notes.

Iteration 1 (in progress): scaffolding only. Tooling, navigation, and placeholder pages are live. Real content is filled in over subsequent iterations as Phylax features stabilize.

• MkDocs static site generator
• Material for MkDocs theme
• mkdocs-static-i18n for DE/EN parallel content (docs_structure: folder)
• mkdocs-git-revision-date-localized for last-modified dates
• Poetry for Python dependency management
• GitHub Actions deploy to GitHub Pages

No analytics, no trackers, no request to a third-party host on page load - same constraints as the Phylax app itself. Three things keep it that way:

• theme.font: false in mkdocs.yml: the system font stack. Without it, Material loads Roboto from Google Fonts in every visitor's browser.
• No repo_url (and no repo_name) in mkdocs.yml: with it, Material's header widget fetches repository facts from api.github.com in every visitor's browser. The GitHub links live in extra.social instead, plain links with inline icons.
• overrides/main.html (theme.custom_dir: overrides): a no-op ResizeObserver for browsers that have none (Safari before 13.1, Chrome before 64, Firefox before 69). Without it, Material loads a polyfill from unpkg.com in those browsers. With it, they keep the initial layout and miss only Material's live re-measuring of element sizes.

A Mermaid diagram would break this: on a page with a pre.mermaid block, Material loads Mermaid from unpkg.com unless the page has loaded Mermaid itself. Self-host Mermaid before adding the first diagram.

This note lives here and not as a comment in mkdocs.yml, because scripts/generate_mkdocs_nav.py rewrites that file and drops comments.

phylax-docs/
├── mkdocs.yml                  # MkDocs config (nav block is generated)
├── overrides/
│   └── main.html               # theme override: ResizeObserver stand-in
├── docs/
│   ├── pyproject.toml          # Poetry config for the docs build
│   └── help/                   # docs_dir
│       ├── _meta.yaml          # single source of truth for navigation
│       ├── de/                 # German content
│       └── en/                 # English content
├── scripts/
│   └── generate_mkdocs_nav.py  # generates nav block from _meta.yaml
└── .github/workflows/docs.yml  # CI build + deploy

Requires Python 3.11+ and Poetry.

cd docs
poetry install --no-interaction
cd ..
poetry --directory=docs run python scripts/generate_mkdocs_nav.py
poetry --directory=docs run mkdocs serve -f mkdocs.yml

Open http://127.0.0.1:8000 to preview.

1. Edit the DE and EN page in parallel (DE in docs/help/de/..., EN in docs/help/en/...).
2. To add a new page, register it in docs/help/_meta.yaml and create both DE and EN files.
3. Run python scripts/generate_mkdocs_nav.py so the regenerated nav block reflects the change.
4. The deploy workflow runs the same nav-generation step in CI; the committed mkdocs.yml is the canonical version.

The German content follows the umlaut and language conventions documented in the Phylax main repo (CLAUDE.md).

MIT - see LICENSE.