docs: replace MkDocs with Zensical for the documentation website#1340
Merged
Conversation
Zensical is the successor to Material for MkDocs from the same team, with much faster builds and native mkdocstrings support. Since Zensical does not yet support mkdocs-jupyter, notebooks are converted to Markdown pages with nbconvert at build time via scripts/convert_notebooks.py.
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThe docs pipeline now converts notebooks to Markdown, builds the site with Zensical, and deploys the generated output to GitHub Pages. The docs configuration, generated-file handling, and documentation dependencies were updated to match the new workflow. ChangesMkDocs to Zensical Migration
Estimated code review effort: 2 (Simple) | ~12 minutes Sequence Diagram(s)sequenceDiagram
participant GitHubActions
participant convert_notebooks.py
participant zensical build
participant GitHub Pages
GitHubActions->>convert_notebooks.py: run notebook conversion
convert_notebooks.py-->>GitHubActions: generated Markdown and assets
GitHubActions->>zensical build: build site
zensical build-->>GitHubActions: ./site output
GitHubActions->>GitHub Pages: deploy ./site
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Tick the box to add this pull request to the merge queue (same as
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR migrates the project’s documentation site from the MkDocs + Material stack to Zensical, updating configuration, dependencies, and CI/CD workflows to build and deploy the new site while preserving notebook-based content.
Changes:
- Replace
mkdocs.ymlwithzensical.toml, carrying over site metadata, navigation, theme settings, mkdocstrings config, analytics, and Markdown extensions. - Add a pre-build notebook conversion script (
scripts/convert_notebooks.py) to generate Markdown pages from.ipynbdocs content for Zensical. - Update docs dependencies and CI workflows to build with Zensical and deploy to GitHub Pages / Netlify previews.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
zensical.toml |
New Zensical site configuration mirroring prior MkDocs settings (nav/theme/plugins/extensions). |
scripts/convert_notebooks.py |
Converts docs notebooks to Markdown + extracted assets prior to Zensical build. |
requirements_docs.txt |
Removes MkDocs-related packages; adds zensical and keeps nbconvert/nbformat + mkdocstrings tooling. |
mkdocs.yml |
Removed MkDocs configuration after migration to Zensical. |
docs/overrides/main.html |
Removes MkDocs theme override that was specific to the prior stack. |
.gitignore |
Ignores generated Markdown pages and _files/ assets emitted by notebook conversion. |
.github/workflows/docs.yml |
Builds docs via notebook conversion + zensical build, then deploys via peaceiris/actions-gh-pages. |
.github/workflows/docs-build.yml |
Updates PR preview build to use notebook conversion + zensical build prior to Netlify deploy. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
tomli 2.2+ ships mypyc-compiled wheels that crash with "extension module 'tomli' is already cached" on Python 3.13 when imported by zensical (python/cpython#123880), breaking the docs build in CI. Also grant the docs deploy job contents:write explicitly so peaceiris/actions-gh-pages can push to gh-pages under least-privilege token settings.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/docs.yml:
- Around line 67-72: The GitHub Pages deploy step in the docs workflow uses a
mutable version tag for peaceiris/actions-gh-pages, which should be pinned to a
specific commit SHA. Update the uses reference in the Deploy to GitHub Pages
step to the resolved SHA for the intended v4 release, keeping the existing with
settings (github_token, publish_dir, force_orphan) unchanged. Use the action
identifier peaceiris/actions-gh-pages@v4 as the target to replace with the
pinned commit reference.
- Around line 67-72: The Deploy to GitHub Pages step in the docs workflow still
references peaceiris/actions-gh-pages@v4 instead of a fixed commit. Update the
uses value in the Deploy to GitHub Pages job to pin peaceiris/actions-gh-pages
to a specific commit SHA, keeping the existing github_token, publish_dir, and
force_orphan settings unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: ae5d98e7-a6e2-467a-bd32-929a11649151
📒 Files selected for processing (8)
.github/workflows/docs-build.yml.github/workflows/docs.yml.gitignoredocs/overrides/main.htmlmkdocs.ymlrequirements_docs.txtscripts/convert_notebooks.pyzensical.toml
💤 Files with no reviewable changes (2)
- mkdocs.yml
- docs/overrides/main.html
|
🚀 Deployed on https://6a4c17b89428150ccd85a6d9--opengeos.netlify.app |
- Pin peaceiris/actions-gh-pages to the v4.0.0 commit SHA to reduce supply-chain risk from mutable tags.
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/workflows/docs.yml (1)
20-20: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueStale
USE_MKDOCSenv var.Now that the build no longer uses MkDocs, this secret reference appears to be dead configuration left over from the old toolchain.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/docs.yml at line 20, The workflow still references the obsolete USE_MKDOCS secret in the docs job, which is dead configuration now that MkDocs is no longer used. Remove the USE_MKDOCS environment entry from the docs workflow and keep the remaining job configuration unchanged; use the docs build job in docs.yml to locate and clean up the stale variable.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/docs.yml:
- Around line 11-12: Add a brief explanatory comment next to the docs workflow
permissions block to justify why contents: write is required. Update the
permissions section in the docs workflow so the reason is clear to static
analysis, keeping the comment close to the existing permissions entry and
referencing the workflow’s publish or docs update step context if needed.
---
Outside diff comments:
In @.github/workflows/docs.yml:
- Line 20: The workflow still references the obsolete USE_MKDOCS secret in the
docs job, which is dead configuration now that MkDocs is no longer used. Remove
the USE_MKDOCS environment entry from the docs workflow and keep the remaining
job configuration unchanged; use the docs build job in docs.yml to locate and
clean up the stale variable.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 311b6016-5921-4d01-b8a5-83f0a86c23a8
📒 Files selected for processing (2)
.github/workflows/docs.ymlrequirements_docs.txt
- Document why the docs deploy job needs contents: write.
Zensical derives nav titles from a page's first H1 when present and the filename otherwise, producing a mixed navigation menu. Set explicit filename-based titles on all notebook-derived nav entries.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
mkdocs.ymlis replaced by a nativezensical.tomlcarrying over the site metadata, theme, navigation, mkdocstrings API reference, Google Analytics, and Markdown extensions.scripts/convert_notebooks.py, which converts all 243 documentation notebooks to Markdown with nbconvert before the build, since Zensical does not yet support the mkdocs-jupyter plugin. The original.ipynbfiles are still copied to the site and remain downloadable. Generated Markdown is gitignored.requirements_docs.txt(drop mkdocs packages, add zensical) and the docs workflows: the deploy workflow now publishes the Zensical build to GitHub Pages with peaceiris/actions-gh-pages, and the PR preview workflow builds with Zensical before deploying to Netlify.Test plan
python scripts/convert_notebooks.pyconverts 243/243 notebooks with language-tagged code fenceszensical buildcompletes with "No issues found" (about 1 second warm build)pre-commit run --all-filespassesSummary by CodeRabbit