Migrate from mkdocs-material to zensical

[snopoke]

Summary

• Replace mkdocs-material with zensical for faster builds (~0.9s) and modern tooling
• Update CI workflow from mkdocs gh-deploy to GitHub Pages artifact deployment (upload-pages-artifact + deploy-pages)
• Inline Jinja macros in chat widget styling docs and remove mkdocs-macros-plugin dependency (not yet supported by zensical)
• Bump mkdocstrings[python] to >=1.0.0 for zensical compatibility
• Remove content max-width constraint for full-width layout
• Add site/ to .gitignore

Before merging

• Change GitHub Pages source in repo settings from "Deploy from a branch" to "GitHub Actions"

Test plan

• Verify uv run zensical build --clean succeeds locally
• Verify uv run zensical serve renders the site correctly
• Confirm chat widget styling page shows color swatches properly (no raw Jinja template syntax)
• Confirm full-width layout renders correctly on wide screens
• After merging, verify GitHub Actions deploys successfully to GitHub Pages

🤖 Generated with Claude Code

[claude]

Documentation Review

Overall this is a well-scoped migration PR. The changes are internally consistent and the test plan is clear. A few items worth confirming before merge:

---

Needs verification before merging

CSS class compatibility (docs/assets/extra.css)

.md-grid {
    max-width: 100%;
}

.md-grid is a mkdocs-material-specific layout wrapper — it's not a standard MkDocs class. If zensical uses different template markup, this rule will silently do nothing and the full-width layout won't apply. Please confirm via zensical serve that .md-grid matches an element in zensical's HTML output. Given that zensical 0.0.29 was uploaded to PyPI the day before this PR was opened, this is worth a quick check.

---

Suggestions

1. Pin zensical in pyproject.toml

The dependency is unpinned ("zensical"), while every other dependency in the file has a version constraint. For a pre-1.0 package at this release cadence, a lower-bound pin like zensical>=0.0.29 would prevent silent regressions when the lock file is regenerated.

2. Add a comment in docs/chat_widget/styling.md explaining the inlined HTML

The ~30 copies of inline <span> HTML replaced the color_swatch macro because mkdocs-macros-plugin isn't yet supported by zensical. This is documented in the PR description but not in the source file. A brief comment above the first table noting this constraint would help future contributors who wonder why macros weren't used.

3. Confirm README link covers contributor needs

The new link points to the Zensical docs at a very early release stage. The old MkDocs link was a well-established guide covering frontmatter, navigation, and admonitions. If the Zensical docs don't yet cover those contributor-relevant topics, consider keeping a secondary link to the MkDocs writing guide as a fallback.

---

Minor

• In ci.yml, actions/configure-pages@v5 runs before actions/checkout@v4. This is functionally fine but unconventional — standard practice puts checkout first.
• mkdocstrings[python]>=1.0.0 is a meaningful version bump from the previously unpinned 0.29.x. Worth a quick check if API docs generation fails post-merge, as 1.0 may have config format changes.

🤖 Generated with Claude Code