Merge pull request #184 from pharmaverse/zensical

Migrate from mkdocs-material to zensical

Author: elong0527

.github/workflows/mkdocs.yml .github/workflows/docs.yml.github/workflows/mkdocs.yml renamed to .github/workflows/docs.yml

@@ -1,34 +1,27 @@
-name: mkdocs
+name: Documentation
 
 on:
   push:
     branches:
       - main
 
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
 
 jobs:
   deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
+      - uses: actions/configure-pages@v5
       - uses: actions/checkout@v6
-      - name: Configure Git Credentials
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-
       - uses: actions/setup-python@v6
         with:
           python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-
-      - uses: actions/cache@v4
-        with:
-          key: mkdocs-material-${{ env.cache_id }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
 
       - name: Install ttf-mscorefonts-installer
         run: |
@@ -40,23 +33,26 @@ jobs:
 
       - name: Install dependencies
         run: |
-          pip install mkdocs-material mkdocstrings-python markdown-exec[ansi] matplotlib
+          pip install zensical mkdocstrings-python markdown-exec[ansi]
           pip install pytest pytest-cov pytest-r-snapshot
-          pip install python-docx pypdf
+          pip install matplotlib python-docx pypdf
           pip install -e '.[all]'
-          pip install --force-reinstall "click<8.2.2" # Workaround for https://github.com/squidfunk/mkdocs-material/issues/8375
 
-      - name: Generate coverage report and deploy mkdocs site
+      - name: Generate coverage report and deploy site
         run: |
           pytest --cov=rtflite --cov-report=html:docs/coverage/
           # Build the site first to generate all artifacts
-          mkdocs build
+          zensical build --clean
           # Ensure generated artifacts are included
           if [ -d "docs/articles/rtf" ]; then
             cp -r docs/articles/rtf site/articles/
           fi
           if [ -d "docs/articles/pdf" ]; then
             cp -r docs/articles/pdf site/articles/
           fi
-          # Deploy the built site
-          mkdocs gh-deploy --force
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

AGENTS.md

@@ -11,7 +11,7 @@
 - **Composition logic**: Modules such as `encode.py`, `pagination/`, `row.py`, `attributes.py`, and `services/` transform structured data into final RTF output. They make heavy use of Pydantic validators, typed helper classes, and string-building utilities.
 - **Font and color utilities**: `fonts/`, `fonts_mapping.py`, `text_convert.py`, `text_conversion/`, and `services/color_service.py` manage font metrics, color lookup, and text normalization.
 - **Conversion helpers**: `convert.py` provides integration with LibreOffice for PDF conversion, while shell/python scripts in `scripts/` (e.g., `check_rtf.sh`, `verify_ascii.py`) support validation workflows.
-- **Documentation**: `docs/` hosts the MkDocs site. Markdown articles may execute Python snippets via `markdown-exec` during site builds.
+- **Documentation**: `docs/` hosts the Zensical site. Markdown articles may execute Python snippets via `markdown-exec` during site builds.
 
 ## Development workflow expectations
 - Use [uv](https://docs.astral.sh/uv/) for environment management. Run `uv sync` to create/refresh the local virtual environment before developing.
@@ -22,7 +22,7 @@
 
 ## Testing & quality gates
 - Execute `pytest` (or targeted subsets) before committing. Snapshot-style tests compare normalized RTF output; update fixtures thoughtfully and document rationale when expectations change.
-- If functionality affects documentation examples, rebuild the docs locally with `mkdocs build` (or preview via `mkdocs serve`) to confirm rendered outputs.
+- If functionality affects documentation examples, rebuild the docs locally with `zensical build --clean` (or preview via `zensical serve`) to confirm rendered outputs.
 - Keep dependency metadata (`uv.lock`) in sync when upgrading libraries; use `uv lock --upgrade` followed by `uv sync` if dependency changes are intentional.
 
 ## Additional tips

CHANGELOG.md

@@ -66,7 +66,7 @@
 ### Documentation
 
 - Updated the assembly article to use `concatenate_docx` in code examples and
-  added a reference page for assemble function to the mkdocs site (#160).
+  added a reference page for assemble function to the documentation site (#160).
 
 ## rtflite 2.2.0
 
@@ -190,7 +190,7 @@
 ### Testing
 
 - Added a developer script to compare current RTF outputs with snapshots
-  generated from mkdocs site articles (#102).
+  generated from documentation site articles (#102).
 
 ### Documentation
 

CONTRIBUTING.md

@@ -39,7 +39,7 @@ This will restore the exact versions of Python and dependency packages
 under the project's `.venv/` directory:
 
 ```bash
-uv sync
+uv sync --all-extras
 ```
 
 ### Development
@@ -72,25 +72,25 @@ pytest --cov=rtflite --cov-report=html:docs/coverage/
 
 ### Documentation
 
-To preview the mkdocs website locally:
+To preview the Zensical website locally:
 
 ```bash
-mkdocs serve
+zensical serve
 ```
 
-To build the mkdocs website locally into `site/`, run:
+To build the Zensical website locally into `site/`, run:
 
 ```bash
-mkdocs build
+zensical build --clean
 ```
 
 rtflite renders vignette-like articles under `docs/articles `using markdown-exec.
-This allows mkdocs to render Python code chunks and their outputs when building the site.
+This allows Zensical to render Python code chunks and their outputs when building the site.
 Check the [markdown-exec documentation](https://pawamoy.github.io/markdown-exec/usage/)
 for possible code chunk options.
 
 If you made changes to the `.md` files in the root directory,
-make sure to synchronize them to the mkdocs website:
+make sure to synchronize them to the Zensical website:
 
 ```bash
 sh docs/scripts/sync.sh
@@ -128,9 +128,8 @@ uv self update
 Update `uv.lock` file regularly:
 
 ```bash
-uv sync --quiet
 uv lock --upgrade
-uv sync
+uv sync --all-extras
 ```
 
 ### Python version

README.md

@@ -6,7 +6,7 @@
 [![CI tests](https://github.com/pharmaverse/rtflite/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/pharmaverse/rtflite/actions/workflows/ci-tests.yml)
 [![Mypy check](https://github.com/pharmaverse/rtflite/actions/workflows/mypy.yml/badge.svg)](https://github.com/pharmaverse/rtflite/actions/workflows/mypy.yml)
 [![Ruff check](https://github.com/pharmaverse/rtflite/actions/workflows/ruff-check.yml/badge.svg)](https://github.com/pharmaverse/rtflite/actions/workflows/ruff-check.yml)
-[![mkdocs](https://github.com/pharmaverse/rtflite/actions/workflows/mkdocs.yml/badge.svg)](https://pharmaverse.github.io/rtflite/)
+[![Documentation](https://github.com/pharmaverse/rtflite/actions/workflows/docs.yml/badge.svg)](https://pharmaverse.github.io/rtflite/)
 ![License](https://img.shields.io/pypi/l/rtflite)
 
 Lightweight RTF composer for Python.

docs/assets/SourceSans3-Variable-Italic.woff2

@@ -66,7 +66,7 @@
 ### Documentation
 
 - Updated the assembly article to use `concatenate_docx` in code examples and
-  added a reference page for assemble function to the mkdocs site (#160).
+  added a reference page for assemble function to the documentation site (#160).
 
 ## rtflite 2.2.0
 
@@ -190,7 +190,7 @@
 ### Testing
 
 - Added a developer script to compare current RTF outputs with snapshots
-  generated from mkdocs site articles (#102).
+  generated from documentation site articles (#102).
 
 ### Documentation
 

docs/assets/SourceSans3-Variable.woff2

@@ -39,7 +39,7 @@ This will restore the exact versions of Python and dependency packages
 under the project's `.venv/` directory:
 
 ```bash
-uv sync
+uv sync --all-extras
 ```
 
 ### Development
@@ -72,25 +72,25 @@ pytest --cov=rtflite --cov-report=html:docs/coverage/
 
 ### Documentation
 
-To preview the mkdocs website locally:
+To preview the Zensical website locally:
 
 ```bash
-mkdocs serve
+zensical serve
 ```
 
-To build the mkdocs website locally into `site/`, run:
+To build the Zensical website locally into `site/`, run:
 
 ```bash
-mkdocs build
+zensical build --clean
 ```
 
 rtflite renders vignette-like articles under `docs/articles `using markdown-exec.
-This allows mkdocs to render Python code chunks and their outputs when building the site.
+This allows Zensical to render Python code chunks and their outputs when building the site.
 Check the [markdown-exec documentation](https://pawamoy.github.io/markdown-exec/usage/)
 for possible code chunk options.
 
 If you made changes to the `.md` files in the root directory,
-make sure to synchronize them to the mkdocs website:
+make sure to synchronize them to the Zensical website:
 
 ```bash
 sh docs/scripts/sync.sh
@@ -128,9 +128,8 @@ uv self update
 Update `uv.lock` file regularly:
 
 ```bash
-uv sync --quiet
 uv lock --upgrade
-uv sync
+uv sync --all-extras
 ```
 
 ### Python version

docs/changelog.md

@@ -6,7 +6,7 @@
 [![CI tests](https://github.com/pharmaverse/rtflite/actions/workflows/ci-tests.yml/badge.svg)](https://github.com/pharmaverse/rtflite/actions/workflows/ci-tests.yml)
 [![Mypy check](https://github.com/pharmaverse/rtflite/actions/workflows/mypy.yml/badge.svg)](https://github.com/pharmaverse/rtflite/actions/workflows/mypy.yml)
 [![Ruff check](https://github.com/pharmaverse/rtflite/actions/workflows/ruff-check.yml/badge.svg)](https://github.com/pharmaverse/rtflite/actions/workflows/ruff-check.yml)
-[![mkdocs](https://github.com/pharmaverse/rtflite/actions/workflows/mkdocs.yml/badge.svg)](https://pharmaverse.github.io/rtflite/)
+[![Documentation](https://github.com/pharmaverse/rtflite/actions/workflows/docs.yml/badge.svg)](https://pharmaverse.github.io/rtflite/)
 ![License](https://img.shields.io/pypi/l/rtflite)
 
 Lightweight RTF composer for Python.