文档工作流

Holon 网站是 docs/website/ 下的一个 mdorigin 内容根。源页面是 Markdown 文件，可以渲染为 HTML，也可以按 Markdown 获取。

编辑内容

在 docs/website/ 下新增或更新 Markdown 文件。用各目录的 README.md 作为分区落地页：

docs/website/
  README.md
  concepts/
    README.md
    runtime-model.md
  guides/
    README.md

面向公众的网站文案保持简洁。详细的运行时契约和设计记录仍放在仓库的 docs/ 目录下。

检查契约引用

文档 CI 会检查以下位置中仓库本地的 Markdown 链接和标题锚点：

README.md、docs/architecture-overview.md 和 docs/runtime-spec.md
docs/website/spec/ 和 docs/website/reference/
docs/rfcs/ 中的真实 Markdown 链接

专题规范还可以在 Last verified 引用块或 Implementation references 一节中声明实现路径。把仓库路径写成代码片段，例如：

> **Last verified:** against `src/runtime/scheduler.rs` and
> `src/runtime/waiting.rs`.

其他位置需要强制校验某个源码路径时，用真实的 Markdown 链接：

[`src/http/mod.rs`](../../../src/http/mod.rs)

围栏示例、占位符和普通代码片段不会被当作当前的实现契约。如果某条本应被检查的行上是历史或提议的引用，只有在该引用之后紧接一条非空原因说明时，才能把它排除：

`src/runtime/proposed.rs` <!-- contract-ref-ignore: proposed file from accepted RFC -->

在仓库根目录运行检查：

python3 docs/website/.tools/check-links.py
python3 docs/website/.tools/test-check-contract-refs.py
python3 docs/website/.tools/check-contract-refs.py

失败时用 file:line:target 格式给出诊断，方便编辑器和 CI 日志直接定位声明位置。

本地预览

cd docs/website
mdorigin dev --root .

刷新索引

文档目录页只用一份受管理的索引列出本节文章。正文可保留导读和跨分区链接，但不要复制目录，也不要把索引翻译成正文里的第二份列表。翻译各文章的 title 和 summary 后重新生成索引即可。在 docs/website 下运行 npm --prefix .tools run check:directories 检查重复链接。

目录页可以包含受管理的索引块：

<!-- INDEX:START -->
<!-- INDEX:END -->

用下面的命令重新生成：

mdorigin build index --root .

构建可部署产物

mdorigin build search --root . --out dist/search
mdorigin build cloudflare --root . --search dist/search

生成的 dist/ 目录已被忽略，不应提交。

生成页面与多语言

有些页面由生成器产出，而不是人工撰写。目前只有 reference/models.md，生成命令为：

cargo run --bin holon-docgen -- models > docs/website/reference/models.md

不要人工翻译生成页面：下一次重新生成会覆盖翻译。应把该页面登记到 .tools/generated-pages.json，然后同步各语言副本：

npm --prefix .tools run sync:generated

脚本会把生成的英文页面复制到各语言路径，替换清单中列出的 front matter 字段为本地化文案，并加上一条正文由生成器产出的说明。复制结果与原页面一起提交。文档 CI 会以 --check 运行同一脚本，一旦生成页面与其副本不一致就失败，因此重新生成后只需多跑一条命令，不需要重新翻译。

语言自动检测

站点包含两个语言：en（默认）与 zh-CN。mdorigin.config.json 启用了 localeDetection，因此访问 / 时会按访问者偏好语言重定向一次到对应语言根路径。深层链接不会被重定向，通过页头语言切换器做出的选择优先，爬虫始终停留在默认语言根路径。

刷新生成的契约快照

OpenAPI、HTTP 路由、CLI、运行时状态枚举和模型工具 schema 快照由主 CI 单独检查。发布契约变更前运行 make snapshots-check。如果变更是有意为之，运行 make snapshots-refresh，审阅生成的 diff，然后重新运行 make snapshots-check。

发布说明

siteUrl 配置为 https://holon.run，因此发布会为生产域名暴露规范的 sitemap 和 feed URL。