Maintaining this site

The public documentation site lives under docs/ and is built with MkDocs. The Markdown source is in docs/docs/, while the generated site is written to docs/site/. The site is intentionally independent from the Vite and Tauri application so documentation authors can work with a Python command only.

Preview and build

From the docs/ directory:

cd docs
mkdocs serve
mkdocs build --strict

From the repository root:

mkdocs serve -f docs/mkdocs.yml
mkdocs build --strict -f docs/mkdocs.yml

The generated site is written to docs/site/ and ignored by Git.

Information ownership

Use this split to avoid duplicate contracts:

Information Canonical owner
Architecture, invariants and platform behavior VOKTTY.md
Long-form contributor architecture guides docs/
Public user and developer navigation docs/docs/
Session continuity and agent handoff PROMPTS/
Release notes Repository release metadata

The web site should explain and link to source-of-truth documents. If a behavior is uncertain or only present in an unfinished branch, label it as experimental or omit it.

Writing guidelines

  • Lead with what the reader can do.
  • Put copyable commands near the beginning of a page.
  • Use short headings and tables for repeated mappings.
  • Explain security and platform limits next to the feature that has them.
  • Prefer concrete examples over abstract descriptions.
  • Do not write secrets, machine-specific paths or generated output into the site.
  • Avoid em dashes and emojis to match repository conventions.

Edit mkdocs.yml when adding or moving a page. Keep the navigation progressive: getting started first, user workflows next, then reference, architecture and development. Run the strict build after every navigation change.

Prefer links within the site for user flows. Link to GitHub or repository documents when the source of truth is outside docs/docs. Do not leave links to source paths that will not be published into the MkDocs site.