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

@@ -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: |

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 <http://localhost:8000>. 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.

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);

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
 

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

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 \

requirements-docs.txt

@@ -1 +1 @@
-mkdocs-material>=9.5,<10
+zensical>=0.0.45,<0.1