Docs migrate to Zensical

.github/workflows/alienmark-docs-deploy.yml

@@ -43,8 +43,11 @@ jobs:
       - name: Install docs dependencies
         run: uv sync --project ../.. --locked --package alienmark-docs
 
-      - name: Build MkDocs site
-        run: uv run --project ../.. --package alienmark-docs mkdocs build --strict
+      - name: Build English Zensical site
+        run: uv run --project ../.. --package alienmark-docs zensical build --strict
+
+      - name: Build Chinese Zensical site
+        run: uv run --project ../.. --package alienmark-docs zensical build --strict --config-file zensical.zh.toml
 
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@v6

.github/workflows/ci.yml

@@ -242,8 +242,11 @@ jobs:
       - name: Install documentation dependencies
         run: uv sync --project ../.. --locked --package aliencommons-contributor-docs
 
-      - name: Build and validate MkDocs site
-        run: uv run --project ../.. --package aliencommons-contributor-docs mkdocs build --strict
+      - name: Build and validate English Zensical site
+        run: uv run --project ../.. --package aliencommons-contributor-docs zensical build --strict
+
+      - name: Build and validate Chinese Zensical site
+        run: uv run --project ../.. --package aliencommons-contributor-docs zensical build --strict --config-file zensical.zh.toml
 
   docs-alienmark:
     runs-on: ubuntu-latest
@@ -274,8 +277,11 @@ jobs:
       - name: Install documentation dependencies
         run: uv sync --project ../.. --locked --package alienmark-docs
 
-      - name: Build and validate MkDocs site
-        run: uv run --project ../.. --package alienmark-docs mkdocs build --strict
+      - name: Build and validate English Zensical site
+        run: uv run --project ../.. --package alienmark-docs zensical build --strict
+
+      - name: Build and validate Chinese Zensical site
+        run: uv run --project ../.. --package alienmark-docs zensical build --strict --config-file zensical.zh.toml
 
   docs-users:
     runs-on: ubuntu-latest
@@ -306,5 +312,8 @@ jobs:
       - name: Install documentation dependencies
         run: uv sync --project ../.. --locked --package aliencommons-user-guide
 
-      - name: Build and validate MkDocs site
-        run: uv run --project ../.. --package aliencommons-user-guide mkdocs build --strict
+      - name: Build and validate English Zensical site
+        run: uv run --project ../.. --package aliencommons-user-guide zensical build --strict
+
+      - name: Build and validate Chinese Zensical site
+        run: uv run --project ../.. --package aliencommons-user-guide zensical build --strict --config-file zensical.zh.toml

.github/workflows/contributors-docs-deploy.yml

@@ -51,8 +51,11 @@ jobs:
       - name: Install documentation dependencies
         run: uv sync --project ../.. --locked --package aliencommons-contributor-docs
 
-      - name: Build MkDocs site
-        run: uv run --project ../.. --package aliencommons-contributor-docs mkdocs build --strict
+      - name: Build English Zensical site
+        run: uv run --project ../.. --package aliencommons-contributor-docs zensical build --strict
+
+      - name: Build Chinese Zensical site
+        run: uv run --project ../.. --package aliencommons-contributor-docs zensical build --strict --config-file zensical.zh.toml
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v5

AGENTS.md

@@ -5,7 +5,7 @@
 
 ## What this is
 
-AlienCommons is a community platform for Technical Minecraft players. It is a polyglot monorepo: a Django 6 backend, a Nuxt 4 frontend, an internal Fastify Markdown-rendering service, a TypeScript Markdown parser library, a DRF envelope library, three MkDocs documentation sites, and the Docker/observability wiring to run all of it.
+AlienCommons is a community platform for Technical Minecraft players. It is a polyglot monorepo: a Django 6 backend, a Nuxt 4 frontend, an internal Fastify Markdown-rendering service, a TypeScript Markdown parser library, a DRF envelope library, three Zensical documentation sites, and the Docker/observability wiring to run all of it.
 
 ## Repository map
 
@@ -18,7 +18,7 @@ aliencommons/
 ├── packages/
 │   ├── alienmark/        TypeScript Markdown parser + HTML renderer (published to GitHub Packages).
 │   └── drf-std-response/ DRF response-envelope + exception-handler library used by the backend.
-├── docs/                Three MkDocs sites (users, contributors, alienmark). See docs/AGENTS.md.
+├── docs/                Three Zensical sites (users, contributors, alienmark). See docs/AGENTS.md.
 ├── infra/compose/       Docker Compose files for dev / stg / pro / proxy.
 ├── o11y/                Grafana, Loki, Grafana Alloy configs.
 ├── make/                docker.mk + node.mk, included by the root Makefile.
@@ -81,7 +81,8 @@ make dev-backend-check      # python manage.py check inside the backend-api cont
 #   uv run ruff check <app...> manage.py
 
 # Docs subproject (matches CI `docs-*` jobs); run inside docs/<name>/
-uv run mkdocs build --strict
+uv run zensical build --strict
+uv run zensical build --strict --config-file zensical.zh.toml
 
 # Single Node package via Turbo filter
 pnpm turbo run check --filter=frontend
@@ -100,7 +101,7 @@ Run the **smallest** check that covers your change. If a check cannot be run, sa
 | Any Node package (`apps/frontend`, `apps/alienmark`, `packages/alienmark`) | `pnpm run check` (full workspace) or `pnpm turbo run check --filter=<package>` (single package) |
 | Backend behavior | `uv run python manage.py test` from `apps/backend/`, or `make dev-backend-test` |
 | Backend lint | `uv run ruff check <apps> manage.py` from `apps/backend/` |
-| Docs site | `uv run mkdocs build --strict` from `docs/<name>/` |
+| Docs site | Run both strict Zensical builds from `docs/<name>/` (default English config, then `zensical.zh.toml`) |
 | Unused-code audit (advisory) | `pnpm run knip` |
 
 CI mirrors these in `.github/workflows/ci.yml`. If your change alters app names, settings modules, build commands, or verification steps, update the workflow too.

README.md

@@ -143,7 +143,7 @@ aliencommons/
 | Contributors | Architecture, setup, development workflow | [`docs/contributors/`](docs/contributors/) |
 | AlienMark    | Markdown syntax reference and API         | [`docs/alienmark/`](docs/alienmark/)       |
 
-All documentation is available in English and Chinese (中文) and built with [MkDocs](https://www.mkdocs.org/) using the [Material](https://squidfunk.github.io/mkdocs-material/) theme.
+All documentation is available in English and Chinese (中文) and built with [Zensical](https://zensical.org/).
 
 Please note that some materials may be not fully up-to-date in this stage.
 

README.zh.md

@@ -143,7 +143,7 @@ aliencommons/
 | 贡献者    | 架构、环境搭建、开发流程 | [`docs/contributors/`](docs/contributors/) |
 | AlienMark | Markdown 语法参考和 API  | [`docs/alienmark/`](docs/alienmark/)       |
 
-所有文档均提供英文和中文版本，使用 [MkDocs](https://www.mkdocs.org/) 和 [Material](https://squidfunk.github.io/mkdocs-material/) 主题构建。
+所有文档均提供英文和中文版本，使用 [Zensical](https://zensical.org/) 构建。
 
 请注意，在当前阶段，部分资料可能尚未完全保持最新。
 

docs/AGENTS.md

@@ -1,36 +1,38 @@
 # Documentation Agent Guide — `docs/`
 
-Three independent MkDocs sites. Each is its own uv workspace package and has its own `mkdocs.yml`, `pyproject.toml`, and `docs/` content tree.
+Three independent Zensical sites. Each is its own uv workspace package and has a default English `zensical.toml`, a Chinese `zensical.zh.toml`, a `pyproject.toml`, and a `docs/` content tree.
 
 ## Sites
 
 | Subproject | Package name | Site name | CI build job | CI deploy workflow |
 |---|---|---|---|---|
-| `docs/users/` | `aliencommons-users-docs` | AlienCommons User Guide | `docs-users` | (none) |
-| `docs/contributors/` | `aliencommons-contributors-docs` | AlienCommons Docs | `docs-contributors` | `.github/workflows/contributors-docs-deploy.yml` |
-| `docs/alienmark/` | `aliencommons-alienmark-docs` | AlienMark Docs | `docs-alienmark` | `.github/workflows/alienmark-docs-deploy.yml` |
+| `docs/users/` | `aliencommons-user-guide` | AlienCommons User Guide | `docs-users` | (none) |
+| `docs/contributors/` | `aliencommons-contributor-docs` | AlienCommons Docs | `docs-contributors` | `.github/workflows/contributors-docs-deploy.yml` |
+| `docs/alienmark/` | `alienmark-docs` | AlienMark Docs | `docs-alienmark` | `.github/workflows/alienmark-docs-deploy.yml` |
 
-## Stack (all three sites)
+## Stack and configuration (all three sites)
 
-- MkDocs `1.6.1`, Material for MkDocs `9.7.6`, `mkdocs-static-i18n` `1.3.1` (exact pins, Python `>=3.14`).
-- `mkdocs-static-i18n` configured with `docs_structure: suffix`, locales `en` (default, `build: true`) and `zh` (`build: true`).
-- Theme: Material, default language `en`. Each locale can supply `nav_translations`.
+- Zensical is exactly pinned in each site's `pyproject.toml` (Python `>=3.14`).
+- `zensical.toml` builds English from `docs/en/` into `site/`.
+- `zensical.zh.toml` builds Chinese from `docs/zh/` into `site/zh/`.
+- Each configuration sets its own theme language and navigation labels. Both expose the English/Chinese language selector.
+- Always build English first, then Chinese. The English build owns `site/`; the Chinese build adds the `site/zh/` subtree.
 
-## Filename convention (i18n suffix)
+## Bilingual content convention
 
-Because `docs_structure: suffix` is on, every translatable page exists as two files:
+Every translatable page exists at the same relative path below both language roots:
 
 ```
-docs/<site>/docs/<page>.en.md
-docs/<site>/docs/<page>.zh.md
+docs/<site>/docs/en/<page>.md
+docs/<site>/docs/zh/<page>.md
 ```
 
-`mkdocs.yml` nav entries use the bare stem (e.g. `index.md`, `syntax.md`, `product/roles.md`). The plugin resolves the per-locale file at build time.
+Links stay language-local because each build has its own `docs_dir`. Use ordinary relative Markdown links such as `syntax.md` or `product/roles.md`; do not add language suffixes or prefixes.
 
 ## Writing rules
 
-- **Update both `*.en.md` and `*.zh.md` together.** They must be equivalent in meaning; wording need not be literal.
-- **Keep nav in sync.** Adding, moving, or removing a page requires updating that site's `mkdocs.yml` `nav:` block, in both languages if `nav_translations` are present.
+- **Update matching files under `docs/en/` and `docs/zh/` together.** They must be equivalent in meaning; wording need not be literal.
+- **Keep nav in sync.** Adding, moving, or removing a page requires updating `nav` in both `zensical.toml` and `zensical.zh.toml`.
 - **Don't invent.** No features, commands, or deployment steps that don't exist in the project. Cross-check against source (`apps/`, `packages/`) when documenting behavior.
 - **Match the existing page style**: heading depth, tone, terminology.
 - **Don't commit generated `site/` output** unless the task is explicitly about it.
@@ -42,24 +44,29 @@ Run inside the relevant `docs/<site>/` directory.
 
 ```bash
 # Live preview
-uv run mkdocs serve
+uv run zensical serve
+
+# Preview Chinese on a separate port
+uv run zensical serve --config-file zensical.zh.toml --dev-addr localhost:8001
 
 # Strict build (matches CI; fails on warnings, missing pages, broken links)
-uv run mkdocs build --strict
+uv run zensical build --strict
+uv run zensical build --strict --config-file zensical.zh.toml
 ```
 
-CI runs each docs job from inside `docs/<name>/` via `uv sync --project ../.. --locked --package aliencommons-<name>-docs` then `mkdocs build --strict`. Run the same `--strict` build locally before pushing.
+CI runs each docs job from inside `docs/<name>/` via `uv sync --project ../.. --locked --package <package-name>`, then runs both strict Zensical builds in the order above. Run the same commands locally before pushing.
 
 ## Cross-references
 
-- AlienMark syntax docs (`docs/alienmark/docs/syntax.*.md`) must stay in sync with the parser's actual supported subset in [`packages/alienmark/`](../../packages/alienmark/AGENTS.md). When you change supported syntax, update the parser, its tests, and these docs together.
+- AlienMark syntax docs (`docs/alienmark/docs/{en,zh}/syntax.md`) must stay in sync with the parser's actual supported subset in [`packages/alienmark/`](../../packages/alienmark/AGENTS.md). When you change supported syntax, update the parser, its tests, and these docs together.
 - Contributor docs reference the backend/frontend/architecture — keep them consistent with the code in [`apps/backend/`](../../apps/backend/AGENTS.md) and [`apps/frontend/`](../../apps/frontend/AGENTS.md).
 
 ## Verification
 
 ```bash
 # From docs/<site>/ — strict build matches the CI docs-* jobs
-uv run mkdocs build --strict
+uv run zensical build --strict
+uv run zensical build --strict --config-file zensical.zh.toml
 ```
 
 If the build warns, treat it as a failure — CI runs with `--strict`.

docs/alienmark/docs/index.en.md → docs/alienmark/docs/en/index.md

@@ -33,4 +33,4 @@ Supported today:
 
 ## Read Next
 
-- [Syntax Reference](syntax.en.md)
+- [Syntax Reference](syntax.md)

docs/alienmark/docs/index.zh.md → docs/alienmark/docs/zh/index.md

@@ -33,4 +33,4 @@ AlienMark 当前提供：
 
 ## 继续阅读
 
-- [语法参考](syntax.zh.md)
+- [语法参考](syntax.md)

docs/alienmark/pyproject.toml

@@ -2,11 +2,7 @@
 name = "alienmark-docs"
 version = "0.1.0"
 requires-python = ">=3.14"
-dependencies = [
-  "mkdocs==1.6.1",
-  "mkdocs-material==9.7.6",
-  "mkdocs-static-i18n==1.3.1",
-]
+dependencies = ["zensical==0.0.50"]
 
 [tool.uv]
 add-bounds = "exact"

docs/alienmark/zensical.toml

@@ -0,0 +1,14 @@
+[project]
+site_name = "AlienMark Docs"
+docs_dir = "docs/en"
+site_dir = "site"
+nav = [{ Home = "index.md" }, { Syntax = "syntax.md" }]
+
+[project.theme]
+language = "en"
+
+[project.extra]
+alternate = [
+  { name = "English", link = "/", lang = "en" },
+  { name = "中文", link = "/zh/", lang = "zh" },
+]

docs/alienmark/zensical.zh.toml

@@ -0,0 +1,14 @@
+[project]
+site_name = "AlienMark 文档"
+docs_dir = "docs/zh"
+site_dir = "site/zh"
+nav = [{ "首页" = "index.md" }, { "语法" = "syntax.md" }]
+
+[project.theme]
+language = "zh"
+
+[project.extra]
+alternate = [
+  { name = "English", link = "/", lang = "en" },
+  { name = "中文", link = "/zh/", lang = "zh" },
+]

docs/contributors/docs/index.en.md → docs/contributors/docs/en/index.md

@@ -11,6 +11,6 @@ It provides a space for players to publish articles and participate in discussio
 
 If you are new to this project, start from the following links:
 
-- [Product Design](product/index.en.md)
-- [Development Setup](development/setup.en.md)
-- [Project Architecture](architecture.en.md)
+- [Product Design](product/index.md)
+- [Development Setup](development/setup.md)
+- [Project Architecture](architecture.md)

docs/contributors/docs/product/articles.en.md → docs/contributors/docs/en/product/articles.md

@@ -61,7 +61,7 @@ Confirmed rules:
 - The new version replaces the public version only after approval.
 - A work unpublished by an editor is not deleted.
 
-The state entered after unpublishing and whether an `Archived` state should be added are still undecided. See [Open Questions](open-questions.en.md).
+The state entered after unpublishing and whether an `Archived` state should be added are still undecided. See [Open Questions](open-questions.md).
 
 ## Collections
 

docs/contributors/docs/product/index.en.md → docs/contributors/docs/en/product/index.md

@@ -40,9 +40,9 @@ AlienCommons primarily serves two groups:
 
 ## Continue Reading
 
-- [User Roles](roles.en.md)
-- [Columns](articles.en.md)
-- [Content Discovery](discovery.en.md)
-- [Community Interaction](community.en.md)
-- [Reports and Administration](moderation.en.md)
-- [Open Questions](open-questions.en.md)
+- [User Roles](roles.md)
+- [Columns](articles.md)
+- [Content Discovery](discovery.md)
+- [Community Interaction](community.md)
+- [Reports and Administration](moderation.md)
+- [Open Questions](open-questions.md)

docs/contributors/docs/index.zh.md → docs/contributors/docs/zh/index.md

@@ -11,6 +11,6 @@
 
 如果你第一次接触这个项目，请从以下链接开始：
 
-- [产品设计](product/index.zh.md)
-- [开发设置](development/setup.zh.md)
-- [项目架构](architecture.zh.md)
+- [产品设计](product/index.md)
+- [开发设置](development/setup.md)
+- [项目架构](architecture.md)

docs/contributors/docs/product/articles.zh.md → docs/contributors/docs/zh/product/articles.md

@@ -61,7 +61,7 @@ stateDiagram-v2
 - 新版本审核通过后，才会替换线上公开版本。
 - 被编辑撤稿的作品不会被删除。
 
-撤稿后应进入何种状态，以及是否增加 `Archived` 状态，仍待确定。参见[开放问题](open-questions.zh.md)。
+撤稿后应进入何种状态，以及是否增加 `Archived` 状态，仍待确定。参见[开放问题](open-questions.md)。
 
 ## 文集
 

docs/contributors/docs/product/index.zh.md → docs/contributors/docs/zh/product/index.md

@@ -40,9 +40,9 @@ AlienCommons 主要服务于两类用户：
 
 ## 继续阅读
 
-- [用户角色](roles.zh.md)
-- [专栏作品](articles.zh.md)
-- [内容发现](discovery.zh.md)
-- [社区互动](community.zh.md)
-- [举报与管理](moderation.zh.md)
-- [开放问题](open-questions.zh.md)
+- [用户角色](roles.md)
+- [专栏作品](articles.md)
+- [内容发现](discovery.md)
+- [社区互动](community.md)
+- [举报与管理](moderation.md)
+- [开放问题](open-questions.md)