QUA-2034: 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

[ets]

Approving. No greptile score here, so I reviewed manually and validated the migration both statically and with a full end-to-end build in an isolated worktree:

• uv sync --frozen + uv run zensical build → No issues found (5147 files generated); scripts/generate-redirects.py → 348 stubs with correct canonical/refresh targets.
• All 585 nav .md references in zensical.toml resolve; all markdown extensions from the old mkdocs.yml are carried over (emoji generator correctly switched to zensical.extensions.*); extra_css/extra_javascript assets exist.
• Macro conversion is complete: all 9 component files present under top-level components/, every macro arg maps to an existing marker pair, and zero leftover {% include-markdown %} directives remain.
• All 349 redirects.yml targets exist; the one still-live path (jira.md) is correctly skipped. ci.yml is correctly rewritten for uv/zensical and preserves the userguide.qualytics.io CNAME. Removed files are unreferenced.

One cosmetic, non-blocking note: zensical.toml nav lists 4 pages twice (glossary.md and three settings/security/users/managing/*.md). The build accepts it without warning, so not a blocker — worth a quick dedupe if you're touching the nav again.

---

Generated by Claude Code