Orchard Core 文档仓库结构指南：基于 MkDocs 的官方文档编写与维护规范

• CMS
• 后端
• Web框架

本文以 Orchard Core 仓库中.agents/skills/orchardcore-docs-writer/references/docs-structure.md为骨架，系统讲解该开源项目官方文档站点（src/docs/）的构建工具链、目录组织、导航配置、Markdown 扩展语法、模块文档规范与重定向机制。读完本文，你将掌握在 Orchard Core 仓库中定位、编写、注册并验证文档页面的完整流程，能够独立为某个模块新增一篇符合项目规范的参考文档，并正确使用 Admonition、Tabbed、Tasklist 等 Material for MkDocs 语法。

一、文档构建工具链：MkDocs + Material for MkDocs

Orchard Core 的官方文档站点基于MkDocs与Material for MkDocs主题构建，这是整个文档体系的根基。

1. 核心配置文件

文档构建的入口配置位于仓库根目录的 mkdocs.yml，其中包含：

• site_name：站点名称，当前为Orchard Core Documentation；
• theme：使用material主题，并通过custom_dir: src/docs/theme挂载自定义主题覆盖；同时配置了logo、favicon、palette（亮/暗双配色，主色 teal、强调色 green）以及多项导航体验特性（如navigation.instant、navigation.top、header.autohide、content.code.copy、content.tabs.link）；
• docs_dir：src/docs，即所有 Markdown 源文档的根目录（注意：不是仓库根目录下的docs/）；
• markdown_extensions：启用 Admonition、CodeHilite、定义列表、脚注、Meta、SuperFences、Tabbed、Tasklist、TOC（带锚点）等扩展；
• plugins：search、git-authors、git-revision-date-localized、exclude、redirects；
• validation：对omitted_files、absolute_links、unrecognized_links、anchors四项输出告警，帮助维护者尽早发现坏链；
• not_in_nav：声明有意不进入导航的文件（如samples/、development/、releases/3.0.0.md、releases/4.0.0.md、llms.txt），避免omitted_files误报；
• nav：显式的页面树（详见后文"导航结构"）。

2. Python 依赖清单

依赖声明在 src/docs/requirements.txt 中，当前仓库实际内容为：

mkdocs>=1.6.1 mkdocs-material>=9.7.7 mkdocs-git-authors-plugin>=0.10.0 mkdocs-git-revision-date-localized-plugin>=1.6.0 pymdown-extensions>=12.1.0 mkdocs-exclude>=1.0.2 mkdocs-redirects>=1.2.1 mdx_truly_sane_lists>=1.2 # Pinning click because higher versions break file watching and auto-reload, see https://github.com/mkdocs/mkdocs/issues/4032. When removing this, also remove the disabling config from the root renovate.json5. click<8.3

两个值得注意的细节：

• mdx_truly_sane_lists用于修正嵌套列表的缩进解析（对应的启用配置在mkdocs.yml中以注释形式保留，可随时开启）；
• click<8.3是刻意固定的版本上限——更高版本的 click 会破坏 MkDocs 的文件监听与自动重载（该说明同时写在了文件注释中，并在根目录 renovate.json5 里做了配套禁用处理）。如果你使用依赖自动更新工具（如 Renovate），务必保留这条 pin。

3. 常用命令

文档参考标注要求 Python 3.11+，安装与预览命令如下：

pip install -r src/docs/requirements.txt python -m mkdocs serve # 本地预览，默认地址 http://127.0.0.1:8000 python -m mkdocs build # 输出静态站点

• mkdocs serve会启动本地开发服务器，实时监听src/docs/下文件变化并自动重载，适合边写边看；
• mkdocs build生成静态站点输出目录，用于发布前检查。

此外，仓库还提供了 src/docs/OrchardCore.Docs.csproj，可将文档工程作为独立项目打开（位于解决方案 OrchardCore.slnx 中），在 IDE 中获得完整的工程化支持。

二、文档目录结构（src/docs/）

src/docs/是全部文档源文件的根目录，各子目录承担明确职责。下表来自项目维护者整理的目录映射，并与当前仓库实际布局一致：

这套布局在 mkdocs.yml 的nav:中逐条映射，例如Key Topics下的topics/content-management/README.md、Reference下的reference/modules/Title/README.md等，均可直接对应到上述目录。另有一个细节：仓库根目录下额外生成了一份 src/docs/llms.txt，被列入not_in_nav，用于为 LLM/Agent 提供可抓取的文档索引，不影响导航展示。

三、导航结构（nav anatomy）：如何让新页面进入菜单

mkdocs.yml中的nav:是一棵显式声明的树，每个叶子节点形如标题: 路径。摘录如下：

nav: - About Orchard Core: README.md - Getting started: - Development Tools: getting-started/development-tools.md - Create a CMS Web application: getting-started/README.md - Guides: - Follow the Guides: guides/README.md - Key Topics: - Manage your Content: topics/content-management/README.md - Reference: - Modules: - Overview: reference/README.md - CMS Modules: - Content Types: reference/modules/ContentTypes/README.md - Content Parts: - Title: reference/modules/Title/README.md - Core Modules: - Display Management: reference/modules/DisplayManagement/README.md

新增页面时，只需在正确的父节点下插入一行- 页面标题: 相对路径.md即可。需要注意：

• 路径是相对于docs_dir（即src/docs/）的；
• 未出现在nav:中的页面会在构建时触发omitted_files告警（当前配置为 warn 级别），并且无法通过站内菜单访问到；
• 因此，写完 Markdown 后务必同步登记导航条目，否则页面"存在但不可达"。

四、Markdown 扩展语法：文档页可用的增强能力

文档站点启用了多组 Markdown 扩展（见mkdocs.yml的markdown_extensions），写作时可放心使用以下语法：

Admonition 示例（提示框）：

!!! info Looking for code contribution info? See contributing-code.md.

Tabbed 示例（注意：标记行后必须空一行，内容使用 4 空格缩进）：

=== "App.razor.css" ```css html, body { font-family: Helvetica, Arial, sans-serif; } ```

这类语法广泛用于参考文档中"配置项说明""常见问题""注意事项"等场景，例如 src/docs/reference/modules/ContentFields/README.md、src/docs/reference/modules/Data/README.md 等页面中都能看到 Admonition 的实际应用。

五、模块文档标题约定（Module header convention）

每个模块参考文档的第一行标题遵循统一格式：

# <显示名称> (`OrchardCore.<Id>`)

项目中的实际例子：

• # Title (OrchardCore.Title)— 对应 src/docs/reference/modules/Title/README.md；
• # Content Types (OrchardCore.ContentTypes)— 对应 src/docs/reference/modules/ContentTypes/README.md；
• # Audit Trail (OrchardCore.AuditTrail)— 对应 src/docs/reference/modules/AuditTrail/README.md。

这种"显示名称 + 模块 ID"的双重标注，使读者能快速把文档与代码项目（src/OrchardCore.Modules/或src/OrchardCore/下的程序集）对应起来。

六、新增一个模块文档的完整流程

当为一个新模块编写参考文档时，按以下四步操作：

1. 创建页面：在src/docs/reference/modules/<Name>/README.md新建文档，内容至少包含：
   • 标题（遵循第五节约定）；
   • 功能特性（features）概述；
   • 配置项说明（configuration）；
   • 配方步骤（recipe steps）；
   • 放置规则（placement）；
   • 数据迁移（migrations）；
   • 如相关，附演示视频链接。
2. 建立入口链接：在 src/docs/reference/modules/README.md 中补充指向新页面的链接；
3. 登记导航：在 mkdocs.yml 的nav:中找到合适的分类（CMS Modules / Core Modules 等），插入- 页面标题: reference/modules/<Name>/README.md；
4. 内容部件（Content Part）特例：如果新模块包含内容部件，还需要同时在 src/docs/reference/modules/ContentParts/README.md 中添加链接。

需要特别说明的是：文档与模块 Manifest 之间不存在自动关联——所有引用都是人工维护的。因此漏掉上面任何一步，新页面要么无法从菜单访问，要么无法被其他文档链接到。

七、页面移动/重命名时的重定向机制

当某个文档页面被移动或重命名时，必须保留旧的入站链接（尤其是已发布并被外部引用过的 URL），否则会产生 404。项目通过mkdocs.yml中的redirects插件实现：

plugins: - redirects: redirect_maps: 'old/path/README.md': 'new/path/README.md'

当前仓库已配置了一批真实的重定向映射，例如：

• 'topics/docs-contributions/README.md'→'contributing/contributing-documentation.md'
• 'glossary/README.md'→'reference/glossary/README.md'
• 'resources/tutorials/README.md'→'getting-started/external-resources.md'
• 'reference/core/DisplayManagement/README.md'→'reference/modules/DisplayManagement/README.md'
• 'guides/contributing/contributing-code.md'→'contributing/contributing-code.md'

从这些映射可以看出 2024–2025 年间文档体系的重组轨迹：resources/、guides/contributing/、reference/core/等旧路径被统一收编到getting-started/、contributing/、reference/modules/等新结构中。撰写文档时若涉及移动，照此格式追加一行映射即可。

八、文档贡献注意事项

针对文档维护者的补充约定（详见 src/docs/contributing/contributing-documentation.md）：

• 开发流程：克隆main分支后，直接编辑src/docs/目录；在 OrchardCore.slnx 中打开OrchardCore.Docs工程可获得 IDE 级支持；
• 视频嵌入：统一使用youtube-nocookie.com域名嵌入视频，避免跟踪 Cookie；
• 评审流程：文档的 Pull Request 流程与代码贡献保持一致（可参考 src/docs/contributing/contributing-code.md 与 src/docs/contributing/reviewing-pull-requests.md）。

九、快速自查清单

完成一篇文档改动后，建议逐项核对：

1. 页面文件是否位于src/docs/下正确的目录；
2. 首行标题是否遵循<Display Name> (\OrchardCore. `)` 约定；
3. 是否在nav:中登记，且路径以src/docs/为基准；
4. 是否在reference/modules/README.md（及内容部件文档）中添加了入站链接；
5. 如发生移动/重命名，是否在redirects插件中保留了旧路径映射；
6. 是否使用了正确的扩展语法（Admonition、Tabbed、Tasklist 等）；
7. 运行python -m mkdocs serve或python -m mkdocs build检查告警——validation配置会把遗漏文件、坏链接等问题以 warn 形式暴露出来。

通过以上流程，任何贡献者都可以在 Orchard Core 文档体系中保持一致、可检索、低维护成本的内容产出节奏。

• CMS
• 后端
• Web框架