Docs/migrate to zensical

[igorbenav]

Documentation: migrate from MkDocs to Zensical

This branch moves the documentation toolchain from Material for MkDocs to Zensical, the successor static-site generator from the same authors. The site configuration is rewritten from mkdocs.yml into zensical.toml, the docs dependency set is swapped accordingly, a GitHub Pages deploy workflow is added (the project previously had none), and a few Markdown constructs that MkDocs silently tolerated are corrected so the new, stricter build passes cleanly. The documentation content, structure, theme, custom palette, and API reference all carry over unchanged in appearance.

---

Configuration moved from mkdocs.yml to zensical.toml

The docs were configured through a mkdocs.yml consumed by Material for MkDocs. Zensical can read mkdocs.yml for compatibility, but the project's configuration is now expressed natively in zensical.toml, which is where Zensical projects are meant to live. The translation is faithful: the same site metadata, the modern theme, the navigation tree, the Markdown extension set, and the mkdocstrings-driven API reference are all preserved. The custom brand color survives too — the palette keeps primary = "custom", which continues to read --md-primary-fg-color: #a47bea from the existing docs/stylesheets/extra.css, so the purple is identical to before.

Three MkDocs-era plugins did not carry over, each for a concrete reason. The search plugin is gone because Zensical ships search as a built-in rather than a plugin. The meta-descriptions plugin is gone because Zensical has no equivalent — the site-wide site_description still applies, but per-page auto-generated meta descriptions no longer are. And Google Analytics, which mkdocs.yml wired up by injecting GOOGLE_ANALYTICS_KEY through MkDocs' !ENV YAML tag, is not carried into zensical.toml: TOML has no !ENV mechanism and Zensical configures analytics through its own system, so re-enabling it is a deliberate follow-up rather than a mechanical translation.

Why: mkdocs.yml was kept only as a transition aid. Expressing the configuration in zensical.toml is the supported, forward-looking form and matches the sibling projects (fastcrud, fastroai-template, FastAPI-boilerplate) that have already migrated.

---

A GitHub Pages deploy pipeline

The repository had no documentation CI at all — docs were built and pushed by hand. This adds .github/workflows/docs.yml, which on every push to main installs the docs dependencies with uv sync --extra docs, builds the site with uv run zensical build, and publishes it to GitHub Pages via the official upload-pages-artifact / deploy-pages actions. The workflow declares least-privilege permissions (contents: read, plus pages: write and id-token: write for the Pages deployment) and a pages concurrency group so overlapping runs don't race.

Why: It uses uv run zensical against the project's docs environment rather than uvx zensical, because the mkdocstrings plugin lives in a separate package that an isolated uvx tool environment wouldn't include — the build needs Zensical and mkdocstrings installed together.

---

Markdown that MkDocs tolerated and Zensical flags

Zensical validates intra-site links and anchors more strictly than MkDocs did, which surfaced three latent issues in the existing content. A type annotation written as Set[str] in a table cell was being parsed as a Markdown link reference — it's now wrapped in backticks. A placeholder "+ Add [ModelName]" had the same problem and now escapes its brackets. And a "Quick setup example" link pointed at configuration.md#basic-example, an anchor that does not exist; it now targets #minimal-setup, the section it was always meant to reach.

These were pre-existing defects that MkDocs rendered without complaint, not regressions introduced by the migration. With them fixed, zensical build reports "No issues found."

---

Test Plan

Automated

• uv run zensical build — "No issues found" (clean build, zero warnings)
• uv sync --extra docs + uv run zensical build from a clean env — succeeds (CI parity with the new workflow)
• uv run pytest — 345 passed (the migration touches only docs/config, so the package is unaffected)

Migration fidelity

• API reference pages render via mkdocstrings (e.g. site/api/crud_admin/index.html is generated with content)
• Custom palette preserved — primary = "custom" + extra.css still applied; stylesheets/extra.css copied into the build
• Navigation, theme features, and Markdown extensions match the previous mkdocs.yml

Deploy

• docs.yml workflow added with Pages permissions and concurrency; runs zensical build and deploys ./site (exercised on merge to main)

---

Dependencies

• Removed from the docs extra: mkdocs, mkdocs-material, mkdocs-meta-descriptions-plugin.
• Added: zensical>=0.0.15, mkdocs-autorefs>=1.0,<2; mkdocstrings[python] bumped to >=1.0,<2.
• mkdocs still appears in uv.lock as a transitive dependency of Zensical/mkdocstrings, but is no longer a direct dependency of this project.

Breaking Changes

• The docs build command changed. mkdocs build / mkdocs serve / mkdocs gh-deploy no longer work — there's no mkdocs.yml and no mkdocs-material. Build and preview with uv run zensical build and uv run zensical serve (after uv sync --extra docs). Note uvx zensical will fail with "mkdocstrings is not installed" because the isolated tool env lacks the mkdocstrings package — use uv run, or uvx --with mkdocstrings-python zensical.
• Google Analytics is no longer configured. The GOOGLE_ANALYTICS_KEY env injection from mkdocs.yml was not ported. Until it's re-added through Zensical's analytics configuration, the docs site emits no analytics.
• Per-page auto meta descriptions are gone. The meta-descriptions plugin has no Zensical equivalent; only the site-wide site_description is emitted now.