From aad6d2da102c9eac5e254a4f3759f9f64ef4253c Mon Sep 17 00:00:00 2001 From: gabrielmoro Date: Fri, 3 Jul 2026 20:38:21 -0300 Subject: [PATCH 1/2] docs: migrate from mkdocs-material to Zensical MkDocs is being deprecated. Zensical is the recommended replacement by the Material for MkDocs team, with drop-in mkdocs.yml compatibility. - Migrate CI from mkdocs-material to Zensical (pinned v0.0.46) - Replace mkdocs gh-deploy with zensical build + peaceiris/actions-gh-pages - Update AGENTS.md references from mkdocs to zensical - Add ADR-0001 documenting the decision --- .github/workflows/documentation.yml | 12 ++++++---- AGENTS.md | 8 +++---- docs/adr/0001-migrate-to-zensical.md | 33 ++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 8 deletions(-) create mode 100644 docs/adr/0001-migrate-to-zensical.md diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 31497b7b..5d56bc66 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -25,9 +25,13 @@ jobs: - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV - uses: actions/cache@v4 with: - key: mkdocs-material-${{ env.cache_id }} + key: zensical-${{ env.cache_id }} path: .cache restore-keys: | - mkdocs-material- - - run: pip install mkdocs-material - - run: mkdocs gh-deploy --force + zensical- + - run: pip install zensical==0.0.46 + - run: zensical build + - uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./site diff --git a/AGENTS.md b/AGENTS.md index 21cf84a8..8b2148ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,7 +39,7 @@ jujubaSVG/ │ │ ├── lib/{core,model,util}/ │ │ └── test/ │ └── sample/ # Flutter sample application -├── docs/ # MkDocs documentation source +├── docs/ # Zensical documentation source ├── scripts/ ├── mkdocs.yml ├── README.md @@ -57,7 +57,7 @@ Load the appropriate instruction file based on what you are modifying: | **Kotlin Multiplatform** | `ai/instructions/kotlin.md` | | **Flutter / Dart** | `ai/instructions/flutter.md` | | **Both / cross-platform** | Read both `ai/instructions/kotlin.md` and `ai/instructions/flutter.md` | -| **Documentation** | `docs/` — MkDocs source | +| **Documentation** | `docs/` — Zensical source | --- @@ -87,7 +87,7 @@ Before starting any task, list directories in `ai/skills/`, identify which cover | Flutter (deps) | `flutter pub get` | `flutter/jujuba_svg/` | | Flutter (test) | `flutter test` | `flutter/jujuba_svg/` | | Flutter (analyze) | `dart analyze` | `flutter/` | -| Documentation | `mkdocs serve` | root | +| Documentation | `zensical serve` | root | ### When to Mark Done @@ -116,7 +116,7 @@ Before starting any task, list directories in `ai/skills/`, identify which cover |----------|---------|--------------| | `android-build.yml` | PR to `main` touching `kotlin/` | Runs `jujubasvg:testAndroidHostTest` | | `flutter-build.yml` | PR to `main` touching `flutter/` | Runs `flutter test` + `dart analyze` | -| `documentation.yml` | PR to `main` touching `docs/` or `mkdocs.yml` | Builds & deploys MkDocs to GitHub Pages | +| `documentation.yml` | PR to `main` touching `docs/` or `mkdocs.yml` | Builds & deploys docs with Zensical to GitHub Pages | | `megalinter.yml` | (all PRs) | MegaLinter static analysis | | `js-validator.yml` | (as configured) | JavaScript validation | | `publish-android.yml` | `workflow_dispatch` | Publishes to Maven Central | diff --git a/docs/adr/0001-migrate-to-zensical.md b/docs/adr/0001-migrate-to-zensical.md new file mode 100644 index 00000000..56b41866 --- /dev/null +++ b/docs/adr/0001-migrate-to-zensical.md @@ -0,0 +1,33 @@ +# ADR-0001: Migrate documentation from MkDocs/Material for MkDocs to Zensical + +## Status + +Accepted + +## Context + +MkDocs, the underlying static site generator that Material for MkDocs builds on, is being deprecated. The Material for MkDocs team (who also created Zensical) recommends migrating to Zensical — a modern static site generator that consolidates both MkDocs and Material for MkDocs into one coherent stack. Zensical is open source (MIT), reads existing `mkdocs.yml` as-is, and is designed for seamless compatibility with existing MkDocs projects. As of the decision date, Zensical is in alpha (v0.0.46) with 44 releases over 13 months, showing active development. + +## Decision + +Migrate the project's documentation toolchain from MkDocs + Material for MkDocs to Zensical. + +Specifically: +- Replace `pip install mkdocs-material` with a pinned `pip install zensical==` in CI +- Replace `mkdocs gh-deploy --force` with `zensical build` followed by `peaceiris/actions-gh-pages` for GitHub Pages deployment +- Keep `mkdocs.yml` unchanged — Zensical reads it directly +- Pin the Zensical version and bump manually + +## Considered Options + +- **Stay on MkDocs/Material for MkDocs**: viable short-term but the upstream project (MkDocs) is being deprecated, creating a maintenance dead end. +- **Switch to a different static site generator** (e.g., Docusaurus, Hugo): would require a full content and configuration rewrite. +- **Zensical**: minimal migration cost (drop-in compatibility), same team, same ecosystem, same configuration format. + +## Consequences + +- Zensical is alpha software — there is risk of breaking changes between versions, which is why we pin and bump manually +- No built-in `gh-deploy` command — must use `peaceiris/actions-gh-pages` action instead +- `mkdocs serve` workflow becomes `zensical serve` for local development +- Configuration (`mkdocs.yml`) and content (`docs/`) require no changes +- MkDocs can remain installed locally as a fallback during the transition From 91a174081bc309ec5328d6da20ebacca96cad3e5 Mon Sep 17 00:00:00 2001 From: Gabriel Bronzatti Moro Date: Fri, 3 Jul 2026 21:01:27 -0300 Subject: [PATCH 2/2] Delete docs/adr/0001-migrate-to-zensical.md --- docs/adr/0001-migrate-to-zensical.md | 33 ---------------------------- 1 file changed, 33 deletions(-) delete mode 100644 docs/adr/0001-migrate-to-zensical.md diff --git a/docs/adr/0001-migrate-to-zensical.md b/docs/adr/0001-migrate-to-zensical.md deleted file mode 100644 index 56b41866..00000000 --- a/docs/adr/0001-migrate-to-zensical.md +++ /dev/null @@ -1,33 +0,0 @@ -# ADR-0001: Migrate documentation from MkDocs/Material for MkDocs to Zensical - -## Status - -Accepted - -## Context - -MkDocs, the underlying static site generator that Material for MkDocs builds on, is being deprecated. The Material for MkDocs team (who also created Zensical) recommends migrating to Zensical — a modern static site generator that consolidates both MkDocs and Material for MkDocs into one coherent stack. Zensical is open source (MIT), reads existing `mkdocs.yml` as-is, and is designed for seamless compatibility with existing MkDocs projects. As of the decision date, Zensical is in alpha (v0.0.46) with 44 releases over 13 months, showing active development. - -## Decision - -Migrate the project's documentation toolchain from MkDocs + Material for MkDocs to Zensical. - -Specifically: -- Replace `pip install mkdocs-material` with a pinned `pip install zensical==` in CI -- Replace `mkdocs gh-deploy --force` with `zensical build` followed by `peaceiris/actions-gh-pages` for GitHub Pages deployment -- Keep `mkdocs.yml` unchanged — Zensical reads it directly -- Pin the Zensical version and bump manually - -## Considered Options - -- **Stay on MkDocs/Material for MkDocs**: viable short-term but the upstream project (MkDocs) is being deprecated, creating a maintenance dead end. -- **Switch to a different static site generator** (e.g., Docusaurus, Hugo): would require a full content and configuration rewrite. -- **Zensical**: minimal migration cost (drop-in compatibility), same team, same ecosystem, same configuration format. - -## Consequences - -- Zensical is alpha software — there is risk of breaking changes between versions, which is why we pin and bump manually -- No built-in `gh-deploy` command — must use `peaceiris/actions-gh-pages` action instead -- `mkdocs serve` workflow becomes `zensical serve` for local development -- Configuration (`mkdocs.yml`) and content (`docs/`) require no changes -- MkDocs can remain installed locally as a fallback during the transition