migrate docs workflow from MkDocs CLI to Zensical

- switch docs CI build step to `uv run zensical build`
- update README and docs commands to use `zensical serve/build`
- replace MkDocs-oriented dev deps with `zensical` and `mkdocstrings-python`
- regenerate `uv.lock` to reflect dependency graph changes
- ignore generated `site/` output

Author: emsi

.github/workflows/docs.yml

@@ -25,8 +25,8 @@ jobs:
       - name: Install dependencies
         run: uv sync --group dev
 
-      - name: Build docs (strict)
-        run: uv run mkdocs build --strict
+      - name: Build docs
+        run: uv run zensical build
 
       - name: Link check
         uses: lycheeverse/lychee-action@v2
@@ -68,8 +68,8 @@ jobs:
       - name: Install dependencies
         run: uv sync --group dev
 
-      - name: Build docs (strict)
-        run: uv run mkdocs build --strict
+      - name: Build docs
+        run: uv run zensical build
 
       - name: Configure Pages
         uses: actions/configure-pages@v5

.gitignore

@@ -10,6 +10,7 @@ __pycache__/
 .Python
 build/
 dist/
+site/
 downloads/
 eggs/
 .eggs/

README.md

@@ -22,19 +22,19 @@ uv sync
 
 ## Documentation
 
-Full docs are built with MkDocs (Material + mkdocstrings) from source code
+Full docs are built with Zensical (MkDocs-compatible) + mkdocstrings from source code
 docstrings, README guidance, and example workflows.
 
 - hosted site (GitHub Pages): `https://emsi.github.io/codex-app-server-client/`
 
 Local docs commands:
 
 ```bash
-uv run mkdocs serve
+uv run zensical serve
 ```
 
 ```bash
-uv run mkdocs build --strict
+uv run zensical build
 ```
 
 ## Quick start

docs/index.md

@@ -27,9 +27,9 @@ uv sync
 ## Local docs workflow
 
 ```bash
-uv run mkdocs serve
+uv run zensical serve
 ```
 
 ```bash
-uv run mkdocs build --strict
+uv run zensical build
 ```

pyproject.toml

@@ -41,12 +41,8 @@ build-backend = "hatchling.build"
 [project.optional-dependencies]
 dev = [
     "build>=1.2.2",
-    "mkdocs>=1.6.1",
-    "mkdocs-material>=9.6.0",
-    "mkdocstrings[python]>=0.28.0",
-    "mkdocs-gen-files>=0.5.0",
-    "mkdocs-literate-nav>=0.6.1",
-    "mkdocs-section-index>=0.3.10",
+    "zensical>=0.0.23",
+    "mkdocstrings-python>=1.18.2",
     "pytest>=8.2.0",
     "twine>=6.0.1",
 ]
@@ -56,12 +52,8 @@ dev = [
     "basedpyright>=1.38.1",
     "black>=26.1.0",
     "build>=1.2.2",
-    "mkdocs>=1.6.1",
-    "mkdocs-material>=9.6.0",
-    "mkdocstrings[python]>=0.28.0",
-    "mkdocs-gen-files>=0.5.0",
-    "mkdocs-literate-nav>=0.6.1",
-    "mkdocs-section-index>=0.3.10",
+    "zensical>=0.0.23",
+    "mkdocstrings-python>=1.18.2",
     "mypy>=1.19.1",
     "pytest>=9.0.2",
     "ruff>=0.15.2",