chore: migrate docs build from MkDocs to Zensical#330
Conversation
MkDocs has been unmaintained since August 2024 and Material for MkDocs entered maintenance mode. Zensical is the designated successor by the same team (squidfunk), reads mkdocs.yml natively, and is a drop-in replacement. - Replace mkdocs-material==9.7.5 with zensical==0.0.26 - Update CI workflows to use `zensical build` (no --strict until zensical/backlog#72) - Update all documentation references across 11 files - mkdocstrings + griffe-pydantic unchanged (separate plugin ecosystem) Closes #329
Pre-reviewed by 2 agents, 2 findings addressed: - Remove stale "MkDocs" from custom_dir reference - Add "(Zensical reads this natively)" to mkdocs.yml config line
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.OpenSSF Scorecard
Scanned Files
|
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request executes a strategic migration of the project's documentation build system from the currently unmaintained MkDocs to its designated successor, Zensical. This transition is crucial for ensuring the long-term stability and support of the documentation infrastructure. The changes primarily involve updating dependencies, build commands, and internal references, all while preserving the existing documentation content and structure. Highlights
Changelog
Ignored Files
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Caution Review failedPull request was closed or merged during review No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (11)
📜 Recent review details⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
🧰 Additional context used📓 Path-based instructions (4)**/*.py📄 CodeRabbit inference engine (CLAUDE.md)
Files:
scripts/**/*.py📄 CodeRabbit inference engine (CLAUDE.md)
Files:
pyproject.toml📄 CodeRabbit inference engine (CLAUDE.md)
Files:
.dockerignore📄 CodeRabbit inference engine (CLAUDE.md)
Files:
🧠 Learnings (9)📓 Common learnings📚 Learning: 2026-03-12T21:59:28.508ZApplied to files:
📚 Learning: 2026-03-12T21:59:28.508ZApplied to files:
📚 Learning: 2026-03-12T21:59:28.508ZApplied to files:
📚 Learning: 2026-03-12T21:59:28.508ZApplied to files:
📚 Learning: 2026-03-12T21:59:28.508ZApplied to files:
📚 Learning: 2026-03-12T21:59:28.508ZApplied to files:
📚 Learning: 2026-03-12T21:59:28.508ZApplied to files:
📚 Learning: 2026-03-12T21:59:28.508ZApplied to files:
🪛 LanguageToolCLAUDE.md[uncategorized] ~59-~59: The official name of this software platform is spelled with a capital “H”. (GITHUB) 🔇 Additional comments (14)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThis pull request migrates the documentation build system from MkDocs to Zensical across the entire codebase. It updates CI workflows, dependency declarations, configuration files, and documentation references to replace MkDocs commands with Zensical equivalents, while keeping existing mkdocs.yml configuration compatible. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
✨ Simplify code
📝 Coding Plan
Comment |
There was a problem hiding this comment.
Code Review
This pull request correctly migrates the documentation build from MkDocs to Zensical. All dependency updates in pyproject.toml and uv.lock, along with the corresponding changes in documentation and scripts, are consistent with this goal. However, there appears to be a critical omission. The pull request description states that CI workflows (.github/workflows/pages.yml and .github/workflows/pages-preview.yml) are updated, but these files are not included in the diff. Without these changes, the CI build for documentation will likely fail as it would still be attempting to use the now-removed MkDocs. Please add the updated workflow files to this pull request to ensure the migration is complete and the CI pipeline remains functional.
There was a problem hiding this comment.
Pull request overview
Migrates the repository’s documentation build from MkDocs Material to Zensical while keeping the existing mkdocs.yml configuration and _site/docs output layout used by the Pages deployment pipeline.
Changes:
- Swapped docs dependency from
mkdocs-material==9.7.5tozensical==0.0.26(lockfile updated accordingly). - Updated GitHub Pages and PR preview workflows to run
uv run zensical build(temporarily without--strict). - Updated internal docs/references (README/CLAUDE/decision log/skill docs, ignore-file comments) to reflect Zensical.
Reviewed changes
Copilot reviewed 10 out of 12 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
uv.lock |
Removes mkdocs-material and related deps; adds zensical and deepmerge; updates dependency groups. |
pyproject.toml |
Replaces mkdocs-material with zensical in the docs dependency group. |
.github/workflows/pages.yml |
Switches docs build step from mkdocs build --strict to zensical build for Pages deploy. |
.github/workflows/pages-preview.yml |
Switches PR preview docs build step from mkdocs build --strict to zensical build. |
mkdocs.yml |
(No change) Remains the single source of docs config; still sets site_dir: _site/docs. |
scripts/export_openapi.py |
Updates docstring references from MkDocs build to Zensical build. |
docs/architecture/decisions.md |
Updates decision log entry to reflect Zensical adoption and rationale. |
README.md |
Updates local docs toolchain reference to Zensical. |
CLAUDE.md |
Updates quick commands and documentation section to reference Zensical and new CI behavior. |
site/astro.config.mjs |
Updates comment describing docs build output source (Zensical). |
.gitignore |
Updates comment labeling _site/ as Zensical build output. |
.dockerignore |
Updates comment labeling _site/ as Zensical build output. |
.claude/skills/review-dep-pr/SKILL.md |
Updates docs dependency review workflow instructions to use zensical build. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Greptile SummaryThis PR migrates the docs build toolchain from Key changes:
Confidence Score: 4/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Push to main / PR opened] --> B[Checkout repo]
B --> C[Set up Python 3.14]
C --> D[Install uv]
D --> E[uv sync --group docs --no-dev]
E --> F[export_openapi.py\nGenerate openapi.json + Scalar HTML]
F --> G[zensical build\nReads mkdocs.yml natively\nOutputs to _site/docs/]
G --> H[Set up Node.js 22]
H --> I[npm ci]
I --> J[npm run build\nAstro → site/dist/]
J --> K{site/dist/docs\nexists?}
K -- Yes --> L[::error:: collision — exit 1]
K -- No --> M[cp -r site/dist/. _site/\nMerge Astro root + Zensical /docs]
M --> N{pages.yml\nor preview?}
N -- pages.yml --> O[Upload GitHub Pages artifact\nDeploy to synthorg.io]
N -- pages-preview.yml --> P[Inject preview banner\ninto all _site/*.html]
P --> Q[Upload artifact\nDeploy to Cloudflare Pages\npr-N.synthorg-pr-preview.pages.dev]
Prompt To Fix All With AIThis is a comment left during a code review.
Path: pyproject.toml
Line: 52
Comment:
**Pre-1.0 version — expect frequent breaking changes**
`zensical==0.0.26` is a `0.0.x` pre-release package, which signals that its public API is not yet stable. Even minor patch bumps can carry breaking changes before a project reaches `1.0`.
This is not a blocker — the pin is exact, the build is verified, and the migration rationale is sound. But it does mean Dependabot/Renovate bumps for this dep will need closer scrutiny than a typical mature package (the `review-dep-pr` skill helps here). Consider adding a comment inline or in the decision log noting the stability expectation so future reviewers know why extra care is warranted on updates.
How can I resolve this? If you propose a fix, please make it concise.Last reviewed commit: baa9f94 |
| ] | ||
| docs = [ | ||
| "mkdocs-material==9.7.5", | ||
| "zensical==0.0.26", |
There was a problem hiding this comment.
Pre-1.0 version — expect frequent breaking changes
zensical==0.0.26 is a 0.0.x pre-release package, which signals that its public API is not yet stable. Even minor patch bumps can carry breaking changes before a project reaches 1.0.
This is not a blocker — the pin is exact, the build is verified, and the migration rationale is sound. But it does mean Dependabot/Renovate bumps for this dep will need closer scrutiny than a typical mature package (the review-dep-pr skill helps here). Consider adding a comment inline or in the decision log noting the stability expectation so future reviewers know why extra care is warranted on updates.
Prompt To Fix With AI
This is a comment left during a code review.
Path: pyproject.toml
Line: 52
Comment:
**Pre-1.0 version — expect frequent breaking changes**
`zensical==0.0.26` is a `0.0.x` pre-release package, which signals that its public API is not yet stable. Even minor patch bumps can carry breaking changes before a project reaches `1.0`.
This is not a blocker — the pin is exact, the build is verified, and the migration rationale is sound. But it does mean Dependabot/Renovate bumps for this dep will need closer scrutiny than a typical mature package (the `review-dep-pr` skill helps here). Consider adding a comment inline or in the decision log noting the stability expectation so future reviewers know why extra care is warranted on updates.
How can I resolve this? If you propose a fix, please make it concise.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #330 +/- ##
=======================================
Coverage 93.75% 93.75%
=======================================
Files 433 433
Lines 19831 19831
Branches 1911 1911
=======================================
Hits 18592 18592
Misses 957 957
Partials 282 282 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
🤖 I have created a release *beep* *boop* --- ## [0.1.3](v0.1.2...v0.1.3) (2026-03-13) ### Features * add Mem0 memory backend adapter ([#345](#345)) ([2788db8](2788db8)), closes [#206](#206) * centralized single-writer TaskEngine with full CRUD API ([#328](#328)) ([9c1a3e1](9c1a3e1)) * incremental AgentEngine → TaskEngine status sync ([#331](#331)) ([7a68d34](7a68d34)), closes [#323](#323) * web dashboard pages — views, components, tests, and review fixes ([#354](#354)) ([b165ec4](b165ec4)) * web dashboard with Vue 3 + PrimeVue + Tailwind CSS ([#347](#347)) ([06416b1](06416b1)) ### Bug Fixes * harden coordination pipeline with validators, logging, and fail-fast ([#333](#333)) ([2f10d49](2f10d49)), closes [#205](#205) * repo-wide security hardening from ZAP, Scorecard, and CodeQL audit ([#357](#357)) ([27eb288](27eb288)) ### CI/CD * add pip-audit, hadolint, OSSF Scorecard, ZAP DAST, and pre-push hooks ([#350](#350)) ([2802d20](2802d20)) * add workflow_dispatch trigger to PR Preview for Dependabot PRs ([#326](#326)) ([4c7b6d9](4c7b6d9)) * bump astral-sh/setup-uv from 7.4.0 to 7.5.0 in the minor-and-patch group ([#335](#335)) ([98dd8ca](98dd8ca)) ### Maintenance * bump the minor-and-patch group across 1 directory with 3 updates ([#352](#352)) ([031b1c9](031b1c9)) * **deps:** bump devalue from 5.6.3 to 5.6.4 in /site in the npm_and_yarn group across 1 directory ([#324](#324)) ([9a9c600](9a9c600)) * migrate docs build from MkDocs to Zensical ([#330](#330)) ([fa8bf1d](fa8bf1d)), closes [#329](#329) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).
Summary
mkdocs-material==9.7.5withzensical==0.0.26— MkDocs is unmaintained since Aug 2024, Material entered maintenance mode; Zensical is the designated successor by the same team (squidfunk)pages.yml,pages-preview.yml) to usezensical build—--strictdeferred until zensical/backlog#72 shipsmkdocs.yml(Zensical reads it natively), no content/markdown changes, no theme changesTest plan
uv sync --group docsresolves cleanly (zensical installed, mkdocs-material removed)uv run python scripts/export_openapi.pysucceedsuv run zensical buildcompletes (12.86s, all pages generated)_site/docs/index.htmlexists_site/docs/api/core/index.htmlexists (mkdocstrings + griffe-pydantic output)Review coverage
Pre-reviewed by 2 agents (comment-analyzer, docs-consistency). 5 findings total, 2 valid and implemented, 3 correctly dismissed.
Closes #329