企业官网建设流程全解析

• 后端
• 数据库
• 文档数据库

本文基于 FerretDB 开源仓库中的 写作指南 编写，面向所有想要为 FerretDB 贡献文档的开发者、技术写作者和社区成员。文章系统梳理了 Docusaurus 站点的 Front Matter 元数据、文件命名与 URL 规范、侧边栏排序、标题大小写、相对链接、图片资产管理，以及由 CTS 工具驱动的 MongoDB shell 代码示例生成与格式化流程，并结合 Taskfile.yml 中的docs-gen任务与 指南示例 等仓库证据深入讲解底层实现，帮助你写出符合 FerretDB 文档标准、可被工具自动验证与格式化的高质量内容。

文档工作流概览

FerretDB 的文档站点基于 Docusaurus 构建（见 docusaurus.config.js），所有文档页面存放于website/docs/目录，并通过 CONTRIBUTING.md 明确要求“文档必须按照写作指南编写”。

整个文档工作流包含三个关键环节：

1. 人工编写：遵循本文所述的 Front Matter、命名、链接与图片规范，编写 Markdown/MDX 页面。
2. CTS 工具验证与生成：MongoDB shell 命令示例以扩展 JSON 格式存放，由 CTS 工具执行验证并生成格式化代码片段。
3. 自动格式化与构建：通过task docs-gen、task docs等命令完成生成、格式化和站点构建。

Front Matter 页面元数据

Front Matter 是每个页面的元数据区，位于页面最顶部，必须用---包裹。例如：

--- sidebar_position: 1 description: How to write documentation ---

关键字段说明：

从仓库实际页面可以看到该规范的执行情况：例如 TTL 索引指南 的 Front Matter 为sidebar_position: 4与description: Learn about TTL indexes in FerretDB.，而 写作指南 使用sidebar_position: 99并将自身标记为unlisted，说明它是一个内部约定文档而非面向读者的公开页面。

文件命名与 URL 规范

• 文件、目录和 slug 一律使用kebab-case-with-dashes（连字符命名），禁止使用下划线（snake_case）或空格，因为 URL 路径通常使用连字符。
• 文件名/URL 路径必须与页面标题保持一致。例如页面标题为 “Getting Started”，文件名和路径也应为getting-started。
• slug字段应等于文件名；只有为了保持旧链接向后兼容等特殊场景才使用不同的slug。

仓库示例：指南页面 full-text-search.mdx、vector-search.mdx、ttl-indexes.mdx 均遵循连字符命名；配套的代码示例目录也使用1-create-ttl-index.request.js这种前缀加连字符的命名模式。

侧边栏排序

通过 Front Matter 中的sidebar_position设置页面在侧边栏中的顺序。同一目录下的页面该值必须唯一，按 “1, 2, 3, 4, …” 递增，避免重复。

以 guides 目录 为例，各指南的sidebar_position依次递增，确保文档目录按预期顺序展示。

标题大小写

标题使用 sentence case（句子式大小写）：### Some header with URL，而不是### Some Header With URL。即仅首字母与专有名词大写，其余小写。

链接规范

链接必须使用相对.md文件路径，这是 Docusaurus 文档版本化 的要求。版本化机制会按文件路径关联不同版本的文档，使用绝对 URL 或.mdx后缀可能导致版本切换时链接失效。

• 链接同目录文件：直接写文件名

  [file in the same directory](https://link.gitcode.com/i/f3f55746727544c37c0d2d311e89988e)

• 链接不同目录文件：写相对路径

  [file in a different directory](https://link.gitcode.com/i/7e90408137b079858bbba04616fa8c04)

在仓库中的具体体现：写作指南通过相对路径引用 TTL 索引示例 与 术语表。

引用仓库文件时固定版本标签

当引用 GitHub 上的配置文件、规范或内部定义时，链接必须指向具体 release tag 而非main分支，因为main分支变动频繁，链接容易失效。例如引用 FerretDB Data API 的 OpenAPI 3.0 规范时，应使用类似以下格式（此处以 v2.8.0 标签为例，实际版本请以仓库当前发布为准）：

[FerretDB Data API OpenAPI 3.0 specification](https://raw.githubusercontent.com/FerretDB/FerretDB/refs/tags/v2.8.0/internal/dataapi/api/openapi.json)

当前仓库中该规范的源文件位于 internal/dataapi/api/openapi.json，引用时务必替换为对应发布版本标签。

图片资产管理

所有图片存放于website/static/img/目录下的blog或docs子目录中。

• 单篇博客文章：可将相关图片收集在同一文件夹，例如/img/blog/partner-name/image.png。

• 日期命名：默认使用YYYY-MM-DD格式命名文件夹，典型路径如/img/blog/2023-01-01/ferretdb-image.jpg。

• Alt 文本：必须为图片添加替代文本，描述图片内容；横幅图片的 alt 文本应使用文章标题。

• 图片命名：使用两到三个描述性单词，采用kebab-case-with-dashes，例如ferretdb-queries.jpg。

• 图片引用语法：所有与 FerretDB 文档和博客相关的资源（图片、gif、视频等）都在static/img/文件夹中。推荐直接使用 Markdown 语法并写绝对资源路径（从/img/开始），因为内容引擎会直接从img文件夹渲染图片：

  FerretDB logo

仓库中该路径确实存在：static/img/logo-dark.png。

列表与代码块规范

列表

列表用于描述一组有序的项目序列，例如步骤、特性或相关条目分组。不应用列表来强调或突出单个项目——单个重点内容应使用代码块或加粗文本。格式工具会自动重新格式化列表。

代码块通用要求

• 代码块用于代码片段，包括 shell 命令、SQL 查询和 JSON 文档；也可用于突出显示 URL、文件名等重要信息。
• 必须始终指定代码块语言。

MongoDB shell 命令与结果：CTS 工具驱动的工作流

这是写作指南中最重要的技术内容——FerretDB 文档中的 MongoDB shell 代码示例不是手写的，而是通过 CTS（Command Test Suite）工具测试和验证生成的。

文档场景：扩展 JSON + CTS 生成

1. 存放格式：相关的 MongoDB shell 命令与响应以扩展 JSON 格式存放在与文档文件相同的目录下。仓库中的实际示例是 ttl-indexes.json，位于website/docs/guides/目录，与 ttl-indexes.mdx 同目录。
2. 编号前缀：1-<file-name>.json形式的前缀按升序编号（1-、2-、…），用于强制文档中的顺序以及 CTS 工具中的执行顺序。例如 TTL 指南的代码文件为 1-create-ttl-index.request.js 和 2-insert-ttl-data.request.js，分别对应createIndexes和insert命令。
3. 生成格式化片段：CTS 工具负责生成可导入 MDX 文件的格式化代码片段。运行task docs-gen即可生成。
4. 产物位置：生成的代码片段存放在website/docs/guides/<extended-json-file-name>/目录下的.js文件中。

从 Taskfile.yml 的源码可以看到docs-gen任务的完整实现：

docs-gen: desc: "Generate documentation examples using CTS tool" cmds: - bin/opendocdb-cts fmt --dir=website/docs/guides - bin/opendocdb-cts convert --dir=website/docs/guides website/docs/guides --db=db - task: fmt-docs

即：先对指南目录中的扩展 JSON 执行格式化（fmt），再转换为代码片段（convert），最后运行fmt-docs统一格式化文档。配套的 cts 任务 可直接将指南示例跑在真实 FerretDB 实例上验证：

cts: desc: "Run CTS tests against FerretDB" cmds: - bin/opendocdb-cts run --dir=website/docs/guides --uri=mongodb://127.0.0.1:27017/cts

从 JSON 到 MDX 的实际效果

ttl-indexes.json 中的第一个命令用于创建 TTL 索引（在reservation.date字段上设置expireAfterSeconds: 60），第二个命令向books集合插入一条文档。经 CTS 生成后，MDX 文件通过 raw-loader 导入这些片段：

import CreateTTLIndexRequest from '!!raw-loader!./ttl-indexes/1-create-ttl-index.request.js' import InsertTTLDataRequest from '!!raw-loader!./ttl-indexes/2-insert-ttl-data.request.js'

并渲染为代码块展示，读者看到的正是经过验证的可执行命令。

博客场景：手动编写 js 代码块

博客文章中 MongoDB shell 命令直接使用js语言编写，格式工具会自动重新格式化这些代码块：

db.league.find({ club: 'PSG' })

MongoDB shell结果同样使用js语言，要求将mongosh输出原样赋值给response变量并粘贴（字段名不加引号、字符串用单引号、末尾不加逗号等）。工具不会重新格式化这类代码块，因此必须保持 mongosh 的真实输出格式：

//Assign the output to response response = [ { _id: ObjectId('63109e9251bcc5e0155db0c2'), club: 'PSG', points: 30, average_age: 30, discipline: { red: 5, yellow: 30 }, qualified: false } ]

其他代码块语言选择

SQL 查询使用sql语言：

SELECT _jsonb FROM "test"."_ferretdb_database_metadata" WHERE ((_jsonb->'_id')::jsonb = '"customers"');

psql输出、环境变量及其他所有场景使用text语言：

_jsonb ---------------------------------------------------------------------------------------------------------------------------------------------- {"$s": {"p": {"_id": {"t": "string"}, "table": {"t": "string"}}, "$k": ["_id", "table"]}, "_id": "customers", "table": "customers_c09344de"}

ferretdb=# \d test._ferretdb_settings Table "test._ferretdb_settings" Column | Type | Collation | Nullable | Default ----------+-------+-----------+----------+--------- settings | jsonb | | | ferretdb=# SELECT settings FROM test._ferretdb_settings; settings -------------------------------------------------------------------------------------------------- {"$k": ["collections"], "collections": {"$k": ["groceries"], "groceries": "groceries_6a5f9564"}} (1 row)

术语使用

写作时应使用准确的描述性术语，可查阅 术语表 确认 FerretDB 相关术语的定义与用法。若术语表中没有所需词汇，可在 Slack 或博客文章 issue 中提出，由社区补充定义。

写作检查清单

提交文档贡献前，请对照以下清单自检：

1. Front Matter：是否包含sidebar_position（且目录内唯一）与合适的description？
2. 命名与 URL：文件名、目录名、slug 是否为kebab-case，且与页面标题一致？
3. 标题：是否使用 sentence case？
4. 链接：是否全部使用相对.md路径？引用仓库内文件时是否指向具体 release tag 而非main分支？
5. 图片：是否存放在static/img/对应目录？是否添加了描述性 alt 文本？文件名是否用两到三个kebab-case单词？
6. 代码块：是否始终指定语言？MongoDB shell 命令是否遵循 CTS 生成或js语言规范？mongosh输出是否原样赋值给response？
7. 术语：使用的术语是否与 术语表 一致？

遵循以上规范，你的文档贡献将能通过 FerretDB 的自动化格式检查与 CTS 验证，确保文档既专业规范、又始终与真实数据库行为保持一致。

• 后端
• 数据库
• 文档数据库