Skip to content

chore: migrate docs build from MkDocs to Zensical #330

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Aureliolo merged 2 commits into from
Mar 12, 2026
Merged

chore: migrate docs build from MkDocs to Zensical #330

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
911d7ac
chore: migrate docs build from MkDocs to Zensical
Aureliolo Mar 12, 2026
baa9f94
docs: address review findings in CLAUDE.md
Aureliolo Mar 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .claude/skills/review-dep-pr/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ For each non-IRRELEVANT changelog item, check our actual usage:

## Phase 4: Build Docs Site (for docs dependencies only)

**Skip this phase** if the dependency is NOT related to documentation (MkDocs, mkdocstrings, griffe, etc.).
**Skip this phase** if the dependency is NOT related to documentation (Zensical, mkdocstrings, griffe, etc.).

For docs-related dependencies, actually build the docs to verify nothing breaks.

Expand All @@ -179,7 +179,7 @@ else

# 4. Install deps and build
uv sync --group docs
uv run mkdocs build --strict 2>&1
uv run zensical build 2>&1

# 5. Return to original branch (trap handles this even on failure)
trap - EXIT
Expand Down
2 changes: 1 addition & 1 deletion .dockerignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ tests/
docs/
*.md

# Documentation build output (MkDocs)
# Documentation build output (Zensical)
_site/

# Astro / Node.js (landing page)
Expand Down
14 changes: 8 additions & 6 deletions .github/workflows/pages-preview.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ jobs:
persist-credentials: false
ref: ${{ steps.pr.outputs.head_sha }}

# --- MkDocs (documentation at /docs) ---
# --- Zensical (documentation at /docs) ---
- name: Set up Python
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
with:
Expand All @@ -112,8 +112,10 @@ jobs:
- name: Export OpenAPI schema
run: uv run python scripts/export_openapi.py

- name: Build MkDocs
run: uv run mkdocs build --strict
- name: Build docs
# TODO: Restore --strict once zensical supports it
# https://github.com/zensical/backlog/issues/72
run: uv run zensical build

# --- Astro (landing page at /) ---
- name: Set up Node.js
Expand All @@ -130,16 +132,16 @@ jobs:
run: npm run build

# --- Merge outputs ---
- name: Merge Astro + MkDocs into final output
- name: Merge Astro + Zensical into final output
run: |
# Guard against Astro accidentally producing a docs/ route
if [ -d "site/dist/docs" ]; then
echo "::error::Astro output contains 'docs/' directory which would overwrite MkDocs output"
echo "::error::Astro output contains 'docs/' directory which would overwrite Zensical output"
exit 1
fi
# Astro output goes to root (use /. to avoid glob edge cases)
cp -r site/dist/. _site/
# MkDocs output is already at _site/docs/ from the build step
# Zensical output is already at _site/docs/ from the build step

# --- Inject preview banner ---
- name: Inject preview banner
Expand Down
14 changes: 8 additions & 6 deletions .github/workflows/pages.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ jobs:
with:
persist-credentials: false

# --- MkDocs (documentation at /docs) ---
# --- Zensical (documentation at /docs) ---
- name: Set up Python
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
with:
Expand All @@ -48,8 +48,10 @@ jobs:
- name: Export OpenAPI schema
run: uv run python scripts/export_openapi.py

- name: Build MkDocs
run: uv run mkdocs build --strict
- name: Build docs
# TODO: Restore --strict once zensical supports it
# https://github.com/zensical/backlog/issues/72
run: uv run zensical build

# --- Astro (landing page at /) ---
- name: Set up Node.js
Expand All @@ -66,16 +68,16 @@ jobs:
run: npm run build

# --- Merge outputs ---
- name: Merge Astro + MkDocs into final output
- name: Merge Astro + Zensical into final output
run: |
# Guard against Astro accidentally producing a docs/ route
if [ -d "site/dist/docs" ]; then
echo "::error::Astro output contains 'docs/' directory which would overwrite MkDocs output"
echo "::error::Astro output contains 'docs/' directory which would overwrite Zensical output"
exit 1
fi
# Astro output goes to root (use /. to avoid glob edge cases)
cp -r site/dist/. _site/
# MkDocs output is already at _site/docs/ from the build step
# Zensical output is already at _site/docs/ from the build step

- name: Upload Pages artifact
uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
Expand Down
2 changes: 1 addition & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Thumbs.db
web/node_modules/
web/dist/

# Documentation build output (MkDocs)
# Documentation build output (Zensical)
_site/

# Generated OpenAPI schema (built by scripts/export_openapi.py)
Expand Down
20 changes: 10 additions & 10 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@

```bash
uv sync # install all deps (dev + test)
uv sync --group docs # install MkDocs docs toolchain
uv sync --group docs # install docs toolchain
uv run ruff check src/ tests/ # lint
uv run ruff check src/ tests/ --fix # lint + auto-fix
uv run ruff format src/ tests/ # format
Expand All @@ -38,27 +38,27 @@ uv run pytest tests/ -m integration -n auto # integration tests only
uv run pytest tests/ -m e2e -n auto # e2e tests only
uv run pytest tests/ -n auto --cov=ai_company --cov-fail-under=80 # full suite + coverage
uv run pre-commit run --all-files # all pre-commit hooks
uv run python scripts/export_openapi.py # export OpenAPI schema (needed before mkdocs build)
uv run mkdocs build --strict # build docs (output: _site/docs/)
uv run mkdocs serve # local docs preview (http://127.0.0.1:8000)
uv run python scripts/export_openapi.py # export OpenAPI schema (needed before docs build)
uv run zensical build # build docs (output: _site/docs/) — no --strict until zensical/backlog#72
uv run zensical serve # local docs preview (http://127.0.0.1:8000)
```

## Documentation

- **Docs source**: `docs/` (MkDocs markdown)
- **Docs source**: `docs/` (Markdown, built with Zensical)
- **Design spec**: `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations)
- **Architecture**: `docs/architecture/` (overview, tech-stack, decision log)
- **Roadmap**: `docs/roadmap/` (status, open questions, future vision)
- **Reference**: `docs/reference/` (research, standards)
- **REST API reference**: `docs/rest-api.md` — links to standalone Scalar UI page at `docs/_generated/api-reference.html` (both generated by `scripts/export_openapi.py` in CI)
- **Library reference**: `docs/api/` — auto-generated from docstrings via mkdocstrings + Griffe (AST-based, no imports)
- **Custom templates**: `docs/overrides/` (MkDocs `custom_dir` for optional theme/template overrides)
- **Custom templates**: `docs/overrides/` (`custom_dir` in `mkdocs.yml` for optional theme/template overrides)
- **Scripts**: `scripts/` — CI/build utility scripts (relaxed ruff rules: `print` and deferred imports allowed)
- **Landing page**: `site/` (Astro, Concept C hybrid design)
- **Config**: `mkdocs.yml` at repo root
- **CI**: `.github/workflows/pages.yml` — exports OpenAPI schema (`scripts/export_openapi.py`), builds Astro landing + MkDocs docs, merges, deploys to GitHub Pages
- **Config**: `mkdocs.yml` at repo root (Zensical reads this natively)
- **CI**: `.github/workflows/pages.yml` — exports OpenAPI schema (`scripts/export_openapi.py`), builds Astro landing + Zensical docs, merges, deploys to GitHub Pages
- **Architecture decisions**: `docs/architecture/decisions.md` (decision log)
- **Dependencies**: `docs` group in `pyproject.toml` (`mkdocs-material`, `mkdocstrings[python]`, `griffe-pydantic`)
- **Dependencies**: `docs` group in `pyproject.toml` (`zensical`, `mkdocstrings[python]`, `griffe-pydantic`)

## Docker

Expand Down Expand Up @@ -180,7 +180,7 @@ src/ai_company/
## CI

- **Jobs**: lint (ruff) + type-check (mypy src/ tests/) + test (pytest + coverage) run in parallel → ci-pass (gate)
- **Pages**: `.github/workflows/pages.yml` — exports OpenAPI schema (`scripts/export_openapi.py`), builds Astro landing + MkDocs docs, merges, deploys to GitHub Pages on push to main. Triggers on `docs/**`, `site/**`, `mkdocs.yml`, `pyproject.toml`, `uv.lock`, `src/ai_company/**`, `scripts/**`, workflow file changes, and `workflow_dispatch`.
- **Pages**: `.github/workflows/pages.yml` — exports OpenAPI schema (`scripts/export_openapi.py`), builds Astro landing + Zensical docs, merges, deploys to GitHub Pages on push to main. Triggers on `docs/**`, `site/**`, `mkdocs.yml`, `pyproject.toml`, `uv.lock`, `src/ai_company/**`, `scripts/**`, workflow file changes, and `workflow_dispatch`.
- **PR Preview**: `.github/workflows/pages-preview.yml`
- Builds site on PRs (same path triggers as Pages) and on `workflow_dispatch` (with `pr_number` input, for Dependabot PRs that can't trigger `pull_request` with secrets)
- Dispatch runs resolve PR metadata (head SHA, state, same-repo check) via `gh pr view`; PR-triggered runs use event context directly
Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ Built-in tools (file system, git, sandbox, code runner) plus MCP bridge for exte
git clone https://github.com/Aureliolo/synthorg.git
cd synthorg
uv sync # install dev + test deps
uv sync --group docs # install docs toolchain (mkdocs)
uv sync --group docs # install docs toolchain (zensical)
```

### Docker Compose
Expand Down
8 changes: 4 additions & 4 deletions docs/architecture/decisions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,13 +80,13 @@ All significant design and architecture decisions, organized by domain. Each ent
| D22 | Remove tools section from system prompt | API's `tools` parameter injects richer definitions (with JSON schemas). Eliminates 200-400+ token redundancy per call. Both Anthropic and OpenAI inject tool definitions internally | Keep as-is (wastes tokens, contradicts provider best practices), replace with behavioral guidance (requires per-tool-set crafting). Evidence: arXiv 2602.11988 shows redundant context increases cost 20%+ with minimal benefit |
| D23 | Pluggable `MemoryFilterStrategy`; initial: tag-based at write time | Zero retrieval cost. Uses existing `MemoryMetadata.tags`. Non-inferable tag convention enforced at `MemoryBackend.store()` boundary | LLM classification at retrieval (2K-10K extra tokens, adds latency, recursive problem), keyword heuristic (low accuracy), documentation only (no enforcement). Evidence: arXiv 2602.11988 confirms agents store inferable content without enforcement |

## Documentation (2026-03-11)
## Documentation (2026-03-12)

**Decision:** MkDocs + Material + mkdocstrings for docs; Astro for landing page; build output embedding for Vue dashboard; single domain with CI merge.
**Decision:** Zensical + mkdocstrings for docs; Astro for landing page; build output embedding for Vue dashboard; single domain with CI merge.

**Rationale:** Best-in-class tools for each job. MkDocs with Griffe AST extraction is PEP 649 safe (no runtime imports). Astro produces zero-JS landing pages. Build output embedding means the same docs HTML serves both the public site and the Vue dashboard.
**Rationale:** MkDocs has been unmaintained since August 2024. Material for MkDocs entered maintenance mode (v9.7.0 final, 12 months critical fixes only). Zensical is the designated successor by the same team (squidfunk), reads `mkdocs.yml` natively, and ships with the Material theme built-in. Griffe AST extraction for mkdocstrings remains PEP 649 safe. Zensical's `--strict` mode is not yet available ([zensical/backlog#72](https://github.com/zensical/backlog/issues/72)) — CI builds without strict validation until that ships.

**Alternatives:** Sphinx (poor landing pages), VitePress/Docusaurus (no Python API docs), shared markdown with dual renderers (breaks mkdocstrings directives), subdomain split (higher maintenance), iframe embedding (poor UX with double scrollbars).
**Alternatives:** Stay on MkDocs (unmaintained, accumulating CVEs and unresolved issues), Sphinx (poor landing pages, different ecosystem), VitePress/Docusaurus (no Python API docs).

## Overarching Pattern

Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ test = [
"respx==0.22.0",
]
docs = [
"mkdocs-material==9.7.5",
"zensical==0.0.26",

@greptile-apps greptile-apps Bot Mar 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pre-1.0 version — expect frequent breaking changes

zensical==0.0.26 is a 0.0.x pre-release package, which signals that its public API is not yet stable. Even minor patch bumps can carry breaking changes before a project reaches 1.0.

This is not a blocker — the pin is exact, the build is verified, and the migration rationale is sound. But it does mean Dependabot/Renovate bumps for this dep will need closer scrutiny than a typical mature package (the review-dep-pr skill helps here). Consider adding a comment inline or in the decision log noting the stability expectation so future reviewers know why extra care is warranted on updates.

Prompt To Fix With AI 
This is a comment left during a code review.
Path: pyproject.toml
Line: 52

Comment:
**Pre-1.0 version — expect frequent breaking changes**

`zensical==0.0.26` is a `0.0.x` pre-release package, which signals that its public API is not yet stable. Even minor patch bumps can carry breaking changes before a project reaches `1.0`. 

This is not a blocker — the pin is exact, the build is verified, and the migration rationale is sound. But it does mean Dependabot/Renovate bumps for this dep will need closer scrutiny than a typical mature package (the `review-dep-pr` skill helps here). Consider adding a comment inline or in the decision log noting the stability expectation so future reviewers know why extra care is warranted on updates.

How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

"mkdocstrings[python]==1.0.3",
"griffe-pydantic==1.3.1",
]
Expand Down
4 changes: 2 additions & 2 deletions scripts/export_openapi.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@
- ``docs/_generated/openapi.json`` — raw OpenAPI schema
- ``docs/_generated/api-reference.html`` — standalone Scalar UI page

Both are generated before the MkDocs build so the docs site can
Both are generated before the docs build so the docs site can
link to the interactive API reference.

Can also be run locally before ``mkdocs build`` to preview the
Can also be run locally before ``zensical build`` to preview the
API reference page (see Quick Commands in CLAUDE.md).
"""

Expand Down
2 changes: 1 addition & 1 deletion site/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ export default defineConfig({
plugins: [tailwindcss()],
},
site: "https://synthorg.io",
// Docs live at /docs (served by MkDocs build output merged in CI)
// Docs live at /docs (served by Zensical build output merged in CI)
// Landing page is everything else
build: {
assets: "_assets",
Expand Down
Loading
Loading