Skip to content

Review mirror of GeiserX/OwnGenome branch docs/zensical - #29

Closed
geiresx wants to merge 6 commits into
mainfrom
docs/zensical
Closed

geiresx wants to merge 6 commits into
mainfrom
docs/zensical

Conversation

@geiresx

@geiresx geiresx commented Nov 6, 2026 •

Copy link
Copy Markdown
Owner

Review-only mirror of a GeiserX/OwnGenome pull request, so CodeRabbit can review it here. Findings are fixed on the real pull request; this one is closed afterwards.

Summary by CodeRabbit

  • Documentation
    • Migrated the documentation site to Zensical, preserving its navigation, theme, and search experience.
    • Updated contributor guidance and maintenance documentation to reflect the new site configuration.
  • Bug Fixes
    • Added checks for built-site links, images, navigation, and configuration errors.
  • Chores
    • Updated documentation build and deployment workflows to use the new site builder and validate generated pages.

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 builds
the same 93 pages from the same Markdown, adds instant navigation, a Copy as
Markdown button and an llms.txt index, but silently drops the nav and
absolute-link validation MkDocs enforced; the new site-check.py step after the
strict build puts those checks back.
The old check found href and src values with a regex that only matched
double quotes, so a missing image or link written as raw HTML with single
quotes or no quotes passed. The shared check now parses the HTML, so those
fail too, and it also checks #fragments, full URLs into the site and the
plugin keys the way Zensical reads them. The Docs workflow comment about
the concurrency group now says what GitHub actually promises.
The shared site check compared same-site links by exact host and port, read
raw tags with a regex outside the HTML parser, and traced back on malformed
URLs, so it could pass a broken site or fail a good one. This takes the
centrally fixed version unchanged; the strict build and the check both pass
on this site (93 pages, 0 errors), and a planted dead fragment still fails it.
@coderabbitai

coderabbitai Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Explain Change →

Caution

Review failed

The pull request is closed.

Walkthrough

The documentation site moves from MkDocs to Zensical. A new checker validates the built site and its configuration. The docs workflow runs the checker and limits upload and deployment to non-PR pushes to main.

Changes: Documentation site migration

Layer / File(s) Summary
Zensical site configuration
mkdocs.yml, zensical.toml, docs/requirements-docs.txt, docs/stylesheets/theme.css
The MkDocs configuration is replaced by Zensical settings for site metadata, navigation, theme, plugins, and Markdown extensions. The dependency and theme styling are updated.
Built-site validation
.github/scripts/site-check.py
The new checker parses built HTML and validates URLs, fragments, navigation, copy targets, redirect stubs, configuration options, and other site conditions. It prints errors and exits with a status based on the results.
Build, validation, and deployment workflow
.github/workflows/docs.yml, .github/workflows/nextflow.yml
The docs workflow builds with Zensical and runs the checker. Artifact upload and deployment require a non-PR push to main. The Nextflow docs-only check recognizes zensical.toml.
Documentation and repository references
.github/PULL_REQUEST_TEMPLATE.md, .gitignore, CLAUDE.md, CONTRIBUTING.md, docs/updating.md
Contributor and maintenance references now name Zensical and zensical.toml. The PR template and build-output heading are also updated.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Other

Possibly related PRs

  • geiresx/OwnGenome#10: Adds a documentation page to MkDocs navigation; the Zensical configuration contains that page.
  • geiresx/OwnGenome#5: Adds a documentation page to MkDocs navigation, which this change replaces with Zensical navigation.
  • geiresx/OwnGenome#27: Adds a disk preflight gated by the docs-scope check; this change updates that check to recognize zensical.toml.
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants