From f9e2cae0be820bbfb7241942e2bca3128f8ed399 Mon Sep 17 00:00:00 2001 From: Qiusheng Wu Date: Wed, 17 Jun 2026 15:28:02 -0400 Subject: [PATCH] docs: migrate documentation build from MkDocs to Zensical (#442) * docs: migrate the documentation build from MkDocs to Zensical Mkdocs and Material for MkDocs are now in maintenance mode; the same team's successor is Zensical, which natively reads the existing mkdocs.yml. Switch the docs toolchain over: - Replace mkdocs-material with zensical in requirements-docs.txt - Build with `zensical build --strict` in the Pages workflow and the Netlify build (Zensical's default site_dir is already `site`) - Update contributing docs to use `zensical serve` / `zensical build` - Escape the `[::1]` IPv6 literal in plugins.md so Zensical's stricter link checker no longer treats it as an unresolved reference - Refresh the extra.css comment to note the selectors target Zensical's output Closes #441 * Address review feedback - Pin zensical to >=0.0.45,<0.1 in requirements-docs.txt so the docs build doesn't silently pull a future 0.0.x (or 0.1+) release that breaks the build. zensical is pre-1.0, so any minor/patch bump can be breaking; the lower bound matches the locally verified version and the upper bound caps within the tested 0.0.x series. Addresses the Claude and CodeRabbit comments on the unpinned dependency. * Address review feedback - Set site_dir: site explicitly in mkdocs.yml. zensical build has no --site-dir flag (only -f/-c/-s), but it honors the site_dir key from mkdocs.yml (verified: setting a temp value redirected the output). This pins the build target to site/, matching the hard-coded upload path in the Pages workflow and the netlify.toml publish dir, so a future 0.0.x default-dir shift can't silently upload an empty directory. Addresses the Claude comment about the implicit output directory. --- .github/workflows/pages.yml | 2 +- docs/contributing.md | 9 +++++---- docs/stylesheets/extra.css | 4 ++-- docs/user-guide/plugins.md | 2 +- mkdocs.yml | 4 ++++ netlify.toml | 2 +- requirements-docs.txt | 2 +- 7 files changed, 15 insertions(+), 10 deletions(-) diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 8322e0e0f..6f8547bac 100644 --- a/.github/workflows/pages.yml +++ b/.github/workflows/pages.yml @@ -63,7 +63,7 @@ jobs: VITE_GEOLIBRE_COLLAB_URL: wss://collab.geolibre.app - name: Build documentation - run: mkdocs build --strict --site-dir site + run: zensical build --strict - name: Add web demo to site run: | diff --git a/docs/contributing.md b/docs/contributing.md index fcd18cbb4..dbfe903e5 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -152,16 +152,17 @@ uploads its report as an artifact on failure. ## Documentation -The site is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/). -To preview your changes locally: +The site is built with [Zensical](https://zensical.org), the successor to +MkDocs Material from the same team. It reads the existing `mkdocs.yml` +configuration directly. To preview your changes locally: ```bash python -m pip install -r requirements-docs.txt -mkdocs serve +zensical serve ``` Open . When you add a new page, add it to the `nav` in -`mkdocs.yml`. The site is built with `mkdocs build --strict` in CI, so broken +`mkdocs.yml`. The site is built with `zensical build --strict` in CI, so broken links and pages left out of the navigation fail the build. Link to other docs pages with a relative path (for example `architecture.md`), and link to files outside `docs/` with a full GitHub URL. diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index c1c7a6004..ed42045cf 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -106,8 +106,8 @@ } /* Sidebar section headers (User Guide, Tutorials, Reference). - Targets internal Material for MkDocs nav classes; tested against - mkdocs-material 9.x. Re-verify these selectors after a major theme upgrade. */ + Targets the internal Material nav classes that Zensical emits; tested against + zensical 0.0.x. Re-verify these selectors after a major theme upgrade. */ .md-nav--primary .md-nav__item--section > .md-nav__link { border-top: 1px solid var(--md-default-fg-color--lightest); color: var(--md-primary-fg-color); diff --git a/docs/user-guide/plugins.md b/docs/user-guide/plugins.md index 7ffc308f7..f208a1175 100644 --- a/docs/user-guide/plugins.md +++ b/docs/user-guide/plugins.md @@ -22,7 +22,7 @@ Open **Settings → Manage Plugins** to browse the marketplace. The dialog is mo Compatibility is checked against each entry's `minGeoLibreVersion`, so incompatible plugins are flagged rather than installed. !!! note "Trust model" - The registry is a curated allowlist, manifests require HTTPS (or HTTP on localhost, 127.0.0.1, or [::1] for development), and every install requires explicit consent, because plugins run as trusted code. The curated registry and the install confirmation are the primary safeguards. + The registry is a curated allowlist, manifests require HTTPS (or HTTP on localhost, 127.0.0.1, or `[::1]` for development), and every install requires explicit consent, because plugins run as trusted code. The curated registry and the install confirmation are the primary safeguards. ## Where plugins come from diff --git a/mkdocs.yml b/mkdocs.yml index 9e6dcffc1..b8f80bda4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,6 +4,10 @@ site_url: https://geolibre.app repo_name: opengeos/GeoLibre repo_url: https://github.com/opengeos/GeoLibre edit_uri: edit/main/docs/ +# Output directory, set explicitly so the build target stays pinned to `site/` +# (matching the Pages/Netlify upload paths) rather than relying on the tool's +# default, which a Zensical 0.0.x patch could shift. +site_dir: site theme: name: material diff --git a/netlify.toml b/netlify.toml index 90e99883e..958b49422 100644 --- a/netlify.toml +++ b/netlify.toml @@ -22,7 +22,7 @@ && python -m pip install -r apps/geolibre-desktop/jupyterlite/requirements.txt \ && npm ci \ && npm run build -w geolibre-desktop \ - && mkdocs build --strict --site-dir site \ + && zensical build --strict \ && mkdir -p site/demo \ && cp -R apps/geolibre-desktop/dist/. site/demo/ \ && test -f site/demo/index.html \ diff --git a/requirements-docs.txt b/requirements-docs.txt index d14bca3f9..34f1a62dd 100644 --- a/requirements-docs.txt +++ b/requirements-docs.txt @@ -1 +1 @@ -mkdocs-material>=9.5,<10 +zensical>=0.0.45,<0.1