Migrate from Material for MkDocs to Zensical + uv

.github/workflows/ci.yml

@@ -9,9 +9,23 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
         with:
-          python-version: 3.x
-      - run: pip install -r requirements.txt
-      - run: mkdocs gh-deploy --force
+          fetch-depth: 0
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Install dependencies
+        run: uv sync --frozen
+      - name: Build site
+        run: uv run zensical build
+      - name: Generate redirect stubs
+        run: uv run python scripts/generate-redirects.py
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          cname: userguide.qualytics.io

.gitignore

@@ -45,7 +45,7 @@ coverage.xml
 *,cover
 .hypothesis/
 venv/
-.python-version
+.venv/
 
 # Translations
 *.mo

.pre-commit-config.yaml

@@ -6,9 +6,9 @@ repos:
         args: ["--config", ".typos.toml"]
   - repo: local
     hooks:
-      - id: mkdocs-warnings
-        name: mkdocs build (check for warnings)
-        entry: bash scripts/check-mkdocs-warnings.sh
+      - id: build-warnings
+        name: zensical build (check for warnings)
+        entry: bash scripts/check-build-warnings.sh
         language: system
         pass_filenames: false
         always_run: true

.python-version

@@ -0,0 +1 @@
+3.12

.typos.toml

@@ -14,12 +14,14 @@ ALTERIN = "ALTERIN"
 [files]
 extend-exclude = [
   "docs/assets/*",
-  "docs/legacy/*",
   "scripts/ignore_this.sh",
   "venv/*",
+  ".venv/*",
   ".env.local",
   ".gitignore",
-  "mkdocs.yml",
-  "requirements.txt",
+  "zensical.toml",
+  "pyproject.toml",
+  "uv.lock",
+  "redirects.yml",
   "**/.*"
 ]

.vscode/settings.json

@@ -3,7 +3,7 @@
     "commands": [
       {
         "match": ".*",
-        "cmd": "venv/bin/pre-commit run --all-files"
+        "cmd": "uv run pre-commit run --all-files"
       }
     ]
   }

CLAUDE.md

@@ -4,116 +4,131 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is the Qualytics User Guide documentation repository, built with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). It documents the Qualytics data quality platform.
+This is the Qualytics User Guide documentation repository, built with
+[Zensical](https://zensical.org/) (the modern successor to Material for MkDocs)
+and managed with [uv](https://docs.astral.sh/uv/). It documents the Qualytics
+data quality platform. Configuration lives in the native `zensical.toml`, with
+the `modern` theme variant.
 
 ## Common Commands
 
 ```bash
-# Activate virtual environment first
-source venv/bin/activate
+# Install / sync dependencies (creates .venv, downloads Python 3.12 if needed)
+uv sync
 
 # Serve documentation locally (default: http://localhost:8000)
-mkdocs serve
+uv run zensical serve
 
-# Serve on custom port
-mkdocs serve -a localhost:8080
+# Serve on a custom address/port
+uv run zensical serve -a localhost:8080
 
-# Build static site
-mkdocs build
+# Build static site (output in site/)
+uv run zensical build
 
-# Run spell check
-pre-commit run --all-files
+# Build + generate legacy redirect stubs (as CI does)
+uv run zensical build && uv run python scripts/generate-redirects.py
+
+# Run all pre-commit checks (typos, build warnings, images, anchors)
+uv run pre-commit run --all-files
 ```
 
-## Setup (if venv doesn't exist)
+## Setup (fresh clone)
 
 ```bash
-python3 -m venv venv
-source venv/bin/activate
-pip install -r requirements.txt
-pre-commit install
+uv sync
+uv run pre-commit install
 ```
 
 ## Repository Structure
 
-- `docs/` - All documentation markdown files
-- `mkdocs.yml` - Site configuration, navigation tree, and plugins
-- `docs/components/` - Reusable markdown snippets (anomaly-support, comparators, general-props)
-- `overrides/` - MkDocs theme customizations
-- `docs/assets/` - Images and static files
+- `docs/` - All documentation markdown files and assets
+- `zensical.toml` - Site configuration and navigation tree (native Zensical config)
+- `components/` - Reusable markdown snippets (anomaly-support, comparators, general-props), injected via macros
+- `main.py` - Macros module (`define_env`) exposing the snippet functions
+- `redirects.yml` - Legacy URL → new URL map (consumed by `scripts/generate-redirects.py`)
+- `scripts/` - Pre-commit checks and the redirect generator
+- `overrides/` - Theme template overrides (`main.html`, `404.html`)
+- `docs/stylesheets/` - `tokens.css`, `extra.css`, `components.css`, `home.css`, `print.css`
+- `pyproject.toml` / `uv.lock` - Dependencies (managed by uv)
 - `contributing/check-content-template-guide.md` - Template for writing quality check rule documentation
 
 ## Documentation Conventions
 
-### Reusable Components
+### Reusable Components (Macros)
+
+Zensical has no `include-markdown` plugin, so shared content is pulled in with
+macros defined in `main.py`. Snippets live in the top-level `components/`
+directory:
+
+```markdown
+{{ general_props('all-props') }}
+{{ anomaly_support('all-types') }}
+{{ comparators('numeric') }}
+```
 
-Quality check documentation uses include-markdown to pull in shared content:
+When a macro call is indented (e.g. inside an admonition or content tab), pipe it
+through Jinja's `indent` filter so multi-line output keeps the indentation:
 
 ```markdown
-{%
-    include-markdown "components/general-props/index.md"
-    start='<!-- all-props--start -->'
-    end='<!-- all-props--end -->'
-%}
+!!! note "Details"
+    {{ comparators('index') | indent(4) }}
 ```
 
-Available component arguments:
-- General props: `all-props`, `filter-only`, `coverage-only`, `none-props`
-- Anomaly support: `all-types`, `record-only`, `shape-only`
+Available macro arguments:
+- `general_props`: `all-props`, `filter-only`, `coverage-only`, `none-props`
+- `anomaly_support`: `all-types`, `record-only`, `shape-only`
+- `comparators`: `index`, `numeric`, `duration`, `string`
+- `fuzzy_search()`, `spacing_warning()`, `filter_guide()` (no arguments)
+
+### Literal `{{ }}` Tokens
+
+Pages that document literal `{{token}}` syntax (notification variables, API/CI
+examples) must not have those processed as macros. Either add
+`render_macros: false` to the page front matter, or wrap the snippet in a
+`{% raw %} ... {% endraw %}` block.
 
 ### Quality Check Documentation Structure
 
 When documenting a quality check rule, follow `contributing/check-content-template-guide.md`:
 1. Definition
 2. In-Depth Overview (optional)
 3. Field Scope (Single/Multiple/Calculated) with Accepted Types table
-4. General Properties (via include-markdown)
+4. General Properties (via the `general_props` macro)
 5. Specific Properties
-6. Anomaly Types (via include-markdown)
+6. Anomaly Types (via the `anomaly_support` macro)
 7. Example with: Objective, Sample Data table, Anomaly Explanation, Flowchart (mermaid), SQL query, Potential Violation Messages
 
 ### Spell Checking
 
-The repository uses `typos` via pre-commit for spell checking. Custom word allowances are in `.typos.toml`. Files in `docs/assets/`, `venv/`, and dotfiles are excluded.
+The repository uses `typos` via pre-commit for spell checking. Custom word
+allowances are in `.typos.toml`. Files in `docs/assets/`, `.venv/`, `uv.lock`,
+and dotfiles are excluded.
 
 ## Pre-Commit Hooks
 
-The repository uses two pre-commit hooks (configured in `.pre-commit-config.yaml`):
+Configured in `.pre-commit-config.yaml`:
 
 1. **typos** - Spell checking across all docs (custom words in `.typos.toml`)
-2. **mkdocs-warnings** - Runs `mkdocs build` and surfaces any `WARNING` lines (broken links, missing nav entries, etc.)
+2. **build-warnings** - Runs `zensical build` and surfaces warnings (broken links, etc.); non-blocking
+3. **broken-images** - Verifies referenced images exist on disk
+4. **anchor-changes** - Detects heading/URL changes and writes `.anchor-changes.md`
 
 Run all hooks manually:
 
 ```bash
-pre-commit run --all-files
+uv run pre-commit run --all-files
 ```
 
-### MkDocs Validation
-
-The `mkdocs.yml` has a `validation` section that controls which link/reference issues produce warnings during build. The current pre-commit hook runs `mkdocs build` in non-strict mode and reports warnings without failing the build — this is intentional to avoid blocking commits on acceptable warnings.
-
-If stricter validation is needed in the future:
-
-- **Granular control:** Expand the `validation` section in `mkdocs.yml` to enable/disable specific checks (anchors, absolute links, unrecognized links, omitted nav files)
-- **Strict mode:** Change the hook to use `mkdocs build --strict` to turn all warnings into errors (only do this after resolving or filtering out all existing warnings)
-- **Filtered strict mode:** Keep non-strict but update the hook's grep to exclude known acceptable warning patterns and fail on the rest
-
-```yaml
-# Example: expanded validation config in mkdocs.yml
-validation:
-  nav:
-    omitted_files: info
-    absolute_links: warn
-  links:
-    anchors: warn
-    absolute_links: warn
-    unrecognized_links: warn
-```
+### Link Validation
 
-### Adding New Pre-Commit Checks
+Zensical validates internal links, anchors, and references by default. The
+`build-warnings` hook runs `zensical build` and reports warnings without failing
+the commit (intentional, to avoid blocking on acceptable warnings). To fail on
+warnings instead, use `uv run zensical build --strict`.
 
-Additional tools that can be added to `.pre-commit-config.yaml` for catching more issues:
+## Deployment
 
-- **markdownlint-cli2** - Catches malformed tables, inconsistent list formatting, missing blank lines around fences
-- **lychee** - Validates all links including images, anchors, and external URLs
+`.github/workflows/ci.yml` runs on push to `main`: `uv sync` → `uv run zensical
+build` → `uv run python scripts/generate-redirects.py` → deploy `site/` to the
+`gh-pages` branch via `peaceiris/actions-gh-pages` (custom domain
+`userguide.qualytics.io` set via the action's `cname` input).