You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Review mirror of GeiserX/akou branch docs/zensical - #1
Review-only mirror of a GeiserX/akou pull request, so CodeRabbit can review it here. Findings are fixed on the real pull request; this one is closed afterwards.
Summary by CodeRabbit
New Features
The documentation site now uses an updated publishing platform, with refreshed navigation, theme settings, and page features.
Documentation builds now check for issues such as broken links, missing pages, and invalid site settings.
Bug Fixes
Improved header text and logo styling across visual themes.
Chores
Documentation publishing and deployment are limited to builds from the main branch.
Material for MkDocs reaches end of life on 2027-05-05 and its maintainers now build Zensical, so the
docs site moves there before that date. Zensical reads the same Markdown and builds the same pages,
with instant navigation, a Copy as Markdown button and an llms.txt index. It silently drops the
nav and absolute-link validation MkDocs ran, so the Docs workflow now runs site-check.py on the
built site to keep those checks.
…n the site check
The shared post-build check read href/src with a double-quote regex, so a
single-quoted or unquoted raw HTML link to a missing file passed, and text in
inline code or scripts was read as links. It now parses the HTML. It also
checks full URLs into the site itself, every #fragment against the target
page's ids, a copy button pointing outside the site, and it fails when there
is no site_url or canonical link to take the path prefix from.
Zensical gives table-of-contents anchors the md-nav__link class, so a page's
own #heading links counted it as reachable from the navigation and a stray
page passed. #top and text fragments are valid without a matching id. Pages
are read as UTF-8 whatever the runner's locale.
No actionable comments were generated in the recent review.
Walkthrough
The documentation site moves from MkDocs to Zensical. The workflow builds the site, runs a new post-build checker, and limits artifact upload and deployment to non-PR runs on main. The Zensical configuration, documentation dependency, theme styles, and Dependabot settings are updated.
Changes: Documentation site migration
Layer / File(s)
Summary
Zensical configuration and site settings mkdocs.yml, zensical.toml, docs/requirements-docs.txt, .github/dependabot.yml, docs/CI-CD.md, .gitignore, docs/stylesheets/theme.css
The MkDocs configuration is removed and replaced with Zensical project, theme, plugin, and Markdown settings. The docs dependency pin and monthly Dependabot entry are updated. Theme styles and related documentation comments are adjusted.
Site checker parsing and URL resolution .github/scripts/site-check.py
The new checker parses generated HTML and TOML configuration. It derives the site prefix and resolves local URLs using directory-URL and offline-plugin settings.
Site checker validation rules .github/scripts/site-check.py
The checker validates published files, pages, links, navigation, configuration, redirects, and generated artifacts. It prints sorted errors and returns a status code.
Build and deployment workflow .github/workflows/docs.yml
The workflow builds with Zensical and runs the checker. Artifact upload and deployment are restricted to non-PR runs on main; workflow triggers and comments are also updated.
No actionable merge-blocking risk is established. Manual deployment on main remains possible, as it was before this change.
Security architecture risk: Low · up to 71353
The publication boundary becomes stricter: pull requests cannot publish, and other runs must target main. The new checker only reads local build output. Remaining uncertainty concerns the replacement build dependency, generated-site behavior, and recovery after an external deployment failure.
Retained concerns
No architecture-level concerns identified.
Security review details
Security Blast Radius
inferred — The directly affected security boundary is the repository's documentation build runner and public Pages output. Pull-request-controlled repository content already reached dependency installation and documentation build execution at the base; the new validator adds local reads without gaining deployment privileges.
Security Findings and Attack Paths
inferred — No introduced escalation path was established through the inspected checker-to-publication flow. Generated HTML can influence validation results and filesystem lookups, but the checker contains no network-fetch or process-execution sink, and PR publication remains excluded.
Trust Boundaries and Controls
observed — Both artifact upload and deployment require a non-pull-request event on refs/heads/main. Deployment additionally depends on successful build completion. This narrows the previous publication policy without increasing build-job permissions.
Resilience and Maintainability Implications
inferred — The added validation gate contains detected output failures before publication. Repeated and concurrent runs retain the existing per-ref scheduling behavior; the repository does not establish external Pages rollback, retention, or atomicity guarantees.
Pre-merge checks: 5
Check name
Status
Explanation
Description Check
Check skipped - CodeRabbit’s high-level summary is enabled.
Title check
The title identifies the review mirror and its Zensical documentation branch. It does not state the migration or site check, but it relates to the changes.
Docstring Coverage
Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage
Explanation
Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 9 functions across 1 files. (7 skipped: 7 unsupported.)
Finishing Touches
Generate docstrings
Commit to this branch
Create a new PR
Generate unit tests (beta)
Commit to this branch
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Warning
Some tools did not complete. Review the errors below.
Biome (2.5.15)
docs/stylesheets/theme.css
Biome could not lint this file: configuration resulted in errors. Check the repository's Biome configuration and plugins.
Reviewing files that changed from the base of the PR and between 3481506 and 71353f0.
Files selected for processing: 9
.github/dependabot.yml
.github/scripts/site-check.py
.github/workflows/docs.yml
.gitignore
docs/CI-CD.md
docs/requirements-docs.txt
docs/stylesheets/theme.css
mkdocs.yml
zensical.toml
Files with no reviewable changes: 1
mkdocs.yml
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review.
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
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.
Review-only mirror of a GeiserX/akou pull request, so CodeRabbit can review it here. Findings are fixed on the real pull request; this one is closed afterwards.
Summary by CodeRabbit