Migrate from Material for MkDocs to Zensical + uv

[josecsotomorales]

Summary

Migrates the User Guide from Material for MkDocs (now in maintenance mode) to Zensical — its official successor — on the modern theme, and from pip/requirements.txt to uv/pyproject.toml. Also modernizes the design and fixes all pre-existing build warnings.

Build output was verified byte-identical between the old mkdocs.yml and the new zensical.toml before mkdocs.yml was removed, and the final build reports 0 issues.

Tooling: pip → uv

• pyproject.toml + .python-version (3.12) + committed uv.lock; removed requirements.txt
• Local workflow is now uv run zensical serve / uv run zensical build

Config: mkdocs.yml → native zensical.toml

• Full TOML config incl. the 685-line nav, theme/palette/fonts, extra (GA + feedback), and markdown extensions
• Emoji refs point at zensical.extensions.* (no YAML compat shim)

Engineering around unsupported MkDocs plugins

Zensical reimplements MkDocs plugins as modules; these aren't shipped yet, so:

• include-markdown → main.py macros module ({{ general_props('all-props') }}, etc.); components/ moved to repo root (124 directives across 54 files migrated)
• redirects → redirects.yml + scripts/generate-redirects.py (349 meta-refresh stubs, preserving query/hash, with canonical tags)
• print-site → docs/stylesheets/print.css + browser Print → Save as PDF
• Literal {{token}} docs (notification variables, API examples) get render_macros: false

Modern design

• Redesigned homepage: hero + filterable destination cards (reuses card-filter.js)
• Design-token system (tokens.css), reusable components (components.css), homepage styles (home.css), improved dark-mode contrast
• Branded 404, nav/search polish

CI & dev tooling

• ci.yml: astral-sh/setup-uv → uv run zensical build → redirect stubs → peaceiris/actions-gh-pages (same gh-pages model, cname preserved)
• Pre-commit hooks, helper scripts, and .vscode rewired to uv/zensical

Cleanups

• Fixed 67 pre-existing build warnings (type-annotation bracket false-positives → backticks/escapes; broken internal links → correct targets)
• Removed legacy files: requirements.txt, includes/, archived/use-cases/, the old check-mkdocs-warnings.sh, and a stray empty dir

Verification

• ✅ uv run zensical build — No issues found
• ✅ zensical.toml vs mkdocs.yml builds were byte-identical
• ✅ 349 redirect stubs generated
• ✅ uv run pre-commit run --all-files — all hooks pass
• ✅ Modern theme, GA, feedback widget, macros, homepage hero all present in output

Notes for reviewers

• Repo Pages settings unchanged (still deploys to gh-pages)
• Pre-existing stale source file docs/settings/integrations/ticketing/jira.md shadows its own redirect — flagged for separate cleanup, not touched here

🤖 Generated with Claude Code