documentation-site

Documentation Sites

Use Zensical as the default static site generator for project documentation, courses, and blogs; keep an existing generator only when the project depends on it or the user asks. course-development owns learning design and executable labs; repository-docs owns README and AGENTS consistency.

Workflow

1. Inspect the project: keep existing content, URLs, and publication rules. For an MkDocs or Hugo site, follow migration instead of scaffolding over it.
2. Bootstrap with a locked dependency: check the latest release, then add it as a dev dependency so uv run and uv sync --locked include it. Skip uv init in an existing Python project; run zensical new in a scratch directory when docs/ or zensical.toml already exists, because it never overwrites files.

   uv init --bare <slug> && cd <slug>
   uv add --dev zensical
   uv run zensical new .
   

3. Apply the starter: replace the generated files with the zensical.toml, index.md as docs/index.md, extra.css as docs/stylesheets/extra.css, and abbreviations.md as includes/abbreviations.md; delete docs/markdown.md. Fill every <placeholder>, set the real site_url with its hosting prefix, and drop unused sections. The starter enables instant navigation, Copy as Markdown, llms.txt, social cards, a glossary, checked snippets, and minified HTML; configuration explains each feature and the optional ones (blog, tags, redirects, API reference, versions, offline).
4. Write under docs/: one H1 per page, explicit nav, a section index.md for overviews, relative .md links, and a description in front matter for search and social cards. Use authoring for page types and syntax, and the lesson template for courses.
5. Wire tasks and ignores: merge mise.toml into the task graph and add site/ and .cache/ to .gitignore. Use dprint for Markdown and python-stack for executable examples.
6. Validate: uv run --locked zensical build --clean --strict must print No issues found and exit 0. Preview with uv run --locked zensical serve (default localhost:8000) and check navigation, search, both palettes, a 390 px viewport, keyboard use, and code copy; use playwright for screenshots. Run lesson code and external links separately.
7. Publish: replace the generated .github/workflows/docs.yml with the pinned docs.yml, which builds every pull request strictly and deploys main to GitHub Pages; github-actions owns pins and audits. Enabling Pages or deploying needs publication authority.