documentation-site · diff
git:20261002.4d31436 to git:20261003.b080339
24 added, 30 removed. Audit A to A.
---
name: documentation-site
- description: "Build and migrate Zensical documentation sites, navigation, search, and course pages."
+ description: "Build Zensical documentation and course websites, the default docs generator: navigation, search, API reference, GitHub Pages, and MkDocs or Hugo migration."
license: MIT
metadata:
kind: task
author: Médéric HURIER (Fmind)
source: github.com/fmind/dot/tree/main/skills/documentation-site
created: "2026-09-16"
- updated: "2026-10-02"
+ updated: "2026-10-03"
---
# Documentation Sites
- Use Zensical as the default static publisher for documentation and courses; [course-development](../course-development/SKILL.md) owns learning design, executable labs, and acceptance.
-
- [Repository docs](../repository-docs/SKILL.md) owns README and AGENTS consistency.
+ 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](../course-development/SKILL.md) owns learning design and executable labs; [repository-docs](../repository-docs/SKILL.md) owns README and AGENTS consistency.
## Workflow
- 1. **Inspect the project**: keep existing content, URLs, and publication rules; use [migration and authoring](references/authoring.md) when replacing Hugo or MkDocs.
- 1. **Bootstrap a new docs project** with a locked development dependency. In an existing Python project, skip `uv init`; in an existing docs tree, scaffold in a scratch directory and merge deliberately.
+ 1. **Inspect the project**: keep existing content, URLs, and publication rules. For an MkDocs or Hugo site, follow [migration](references/migration.md) instead of scaffolding over it.
+ 1. **Bootstrap with a locked dependency**: check the [latest release](https://github.com/zensical/zensical/releases), 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.
```bash
- uv init --bare <slug>
- cd <slug>
+ uv init --bare <slug> && cd <slug>
uv add --dev zensical
uv run zensical new .
- uv run zensical --version
```
- 1. **Configure `zensical.toml`**: set `project.site_name`, the real `site_url` including any repository prefix, explicit `nav`, and language. Keep generated Markdown extensions needed by the content; prefer small configuration changes over theme overrides.
- 1. **Write under `docs/`**: make `index.md` the entry point, use relative `.md` links, stable headings, fenced code with languages, and useful image descriptions. Use the [lesson template](templates/lesson.md) for a new course page and the authoring reference for richer Markdown.
- 1. **Wire the repository tasks**: adapt [mise.toml](templates/mise.toml) into the existing task graph. Use [dprint](../dprint/SKILL.md) for markup and [python-stack](../python-stack/references/foundation/GUIDE.md) for executable examples.
- 1. **Preview and validate**:
- ```bash
- uv run zensical serve
- # In a separate terminal, or after stopping the preview:
- uv run zensical build --clean --strict
- ```
- Verify the rendered navigation, search, mobile layout, keyboard use, and code copying. Strict builds catch internal link and anchor warnings; run lesson examples and external link checks separately.
- 1. **Prepare publishing**: `site/` is the default output. Review the generated `.github/workflows/docs.yml`, route its build through the same locked mise tasks, and use [github-actions](../github-actions/references/ci-cd/GUIDE.md) for action pins and permissions. Enable deployment only within the project's publication authority.
+ 1. **Apply the starter**: replace the generated files with the [zensical.toml](templates/zensical.toml), [index.md](templates/index.md) as `docs/index.md`, [extra.css](templates/extra.css) as `docs/stylesheets/extra.css`, and [abbreviations.md](templates/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](references/configuration.md) explains each feature and the optional ones (blog, tags, redirects, API reference, versions, offline).
+ 1. **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](references/authoring.md) for page types and syntax, and the [lesson template](templates/lesson.md) for courses.
+ 1. **Wire tasks and ignores**: merge [mise.toml](templates/mise.toml) into the task graph and add `site/` and `.cache/` to `.gitignore`. Use [dprint](../dprint/SKILL.md) for Markdown and [python-stack](../python-stack/references/foundation/GUIDE.md) for executable examples.
+ 1. **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](../playwright/SKILL.md) for screenshots. Run lesson code and external links separately.
+ 1. **Publish**: replace the generated `.github/workflows/docs.yml` with the pinned [docs.yml](templates/docs.yml), which builds every pull request strictly and deploys `main` to GitHub Pages; [github-actions](../github-actions/references/ci-cd/GUIDE.md) owns pins and audits. Enabling Pages or deploying needs publication authority.
## Gotchas
- - **Generated CI publishes**: `zensical new` creates a Pages workflow; inspect its triggers before including it in an existing repository.
- - **Build output is disposable**: ignore `site/`, `.cache/`, and `.venv/`; retain `pyproject.toml`, `uv.lock`, configuration, and source content.
- - **Plugin compatibility is explicit**: Zensical reimplements selected MkDocs plugins; check the supported list for the locked version before adding a plugin package.
- - **Theme**: preserve the site's established design tokens and use documented palette/CSS customization. For a new Fmind publication, follow the published brand in [fmind-visuals](../fmind-visuals/SKILL.md); the workstation's terminal palette has a separate scope and does not redefine the site's identity.
- - **Reproducibility**: use `uv sync --locked` in CI and clean builds; verify the current stable release before upgrading. The local bootstrap and strict build were exercised with Zensical 0.0.67.
+ - **Diagnostics come first**: a strict failure prints the file, line, and column, then a Python traceback; read the head of the output.
+ - **Strict mode has gaps**: it catches missing pages, anchors, snippets (`check_paths`), and unresolved autorefs, but unclosed fences and unknown icon shortcodes build silently. Review the rendered pages.
+ - **`site_url` is load-bearing**: `llmstxt` aborts without it; instant navigation, previews, and the sitemap degrade; a wrong prefix breaks social card and `llms.txt` links.
+ - **Unsupported plugins are silently ignored**: Zensical never runs MkDocs plugin code. Check the [plugin list](https://zensical.org/docs/compatibility/mkdocs/plugins/) for the locked version before relying on one. `gen-files`, `hooks`, `exclude_docs`, `draft_docs`, and `not_in_nav` are unsupported.
+ - **Feature conflicts**: `navigation.indexes` excludes `toc.integrate`; `navigation.prune` excludes `navigation.expand`; offline builds must drop instant navigation, analytics, repository facts, and comments.
+ - **Third-party requests**: Google Fonts and Mermaid (unpkg) load externally; use `font = false` or self-hosted assets when privacy rules require it, and add the [cookie consent](https://zensical.org/docs/setup/data-privacy/) before analytics.
+ - **Layout limits**: `docs_dir` cannot be `.`; uv's symlink link mode is unsupported; `serve` has no strict mode, and a busy port fails with `Address already in use` (pass `-a 127.0.0.1:<port>`).
+ - **Version churn**: Zensical is pre-1.0 (0.0.x) and releases often; keep `uv.lock` committed, upgrade with `uv lock --upgrade-package zensical`, and rebuild `--clean`. The CI template stays cache-free as upstream advises. Tested on 0.0.67.
+ - **Brand**: the starter applies [fmind/theme](https://github.com/fmind/theme) tokens to the light scheme and Google Sans fonts. Preserve an existing site's identity; follow [fmind-visuals](../fmind-visuals/SKILL.md) for Fmind logos and assets.
## Official Skills
- No upstream authoring `SKILL.md` was found in `zensical/zensical` on 2026-09-08. This is the personal workflow; use the official documentation below for current capabilities.
+ No upstream authoring `SKILL.md` was found in `zensical/zensical` or `zensical/docs` on 2026-10-03. [Zensical Studio](https://zensical.org/studio) (VS Code) adds a preview, formatter, linter, and link refactoring for Zensical and MkDocs projects.
## Documentation
- - [Zensical](https://github.com/zensical/zensical) · [Create a site](https://zensical.org/docs/create-your-site/) · [Authoring](https://zensical.org/docs/authoring/markdown/)
- - [Validation](https://zensical.org/docs/setup/validation/) · [Plugin compatibility](https://zensical.org/docs/compatibility/mkdocs/plugins/) · [Publishing](https://zensical.org/docs/publish-your-site/)
- - Releases: [Zensical](https://github.com/zensical/zensical/releases)
+ - [Get started](https://zensical.org/docs/get-started/) · [Create a site](https://zensical.org/docs/create-your-site/) · [Configuration](https://zensical.org/docs/setup/basics/) · [Authoring](https://zensical.org/docs/authoring/markdown/)
+ - [Validation](https://zensical.org/docs/setup/validation/) · [Plugins](https://zensical.org/docs/compatibility/mkdocs/plugins/) · [Customization](https://zensical.org/docs/customization/) · [Publishing](https://zensical.org/docs/publish-your-site/)
+ - Source: [zensical/zensical](https://github.com/zensical/zensical) · [zensical/docs](https://github.com/zensical/docs) · Releases: [Zensical](https://github.com/zensical/zensical/releases)