★ FEATURED ARTICLE 后端数据库文档数据库【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址https://gitcode.com/gh_mirrors/fe/FerretDB点击查看免费下载本文基于 FerretDB 开源仓库中的 写作指南 编写面向所有想要为 FerretDB 贡献文档的开发者、技术写作者和社区成员。文章系统梳理了 Docusaurus 站点的 Front Matter 元数据、文件命名与 URL 规范、侧边栏排序、标题大小写、相对链接、图片资产管理以及由 CTS 工具驱动的 MongoDB shell 代码示例生成与格式化流程并结合 Taskfile.yml 中的docs-gen任务与 指南示例 等仓库证据深入讲解底层实现帮助你写出符合 FerretDB 文档标准、可被工具自动验证与格式化的高质量内容。文档工作流概览FerretDB 的文档站点基于 Docusaurus 构建见 docusaurus.config.js所有文档页面存放于website/docs/目录并通过 CONTRIBUTING.md 明确要求“文档必须按照写作指南编写”。整个文档工作流包含三个关键环节人工编写遵循本文所述的 Front Matter、命名、链接与图片规范编写 Markdown/MDX 页面。CTS 工具验证与生成MongoDB shell 命令示例以扩展 JSON 格式存放由 CTS 工具执行验证并生成格式化代码片段。自动格式化与构建通过task docs-gen、task docs等命令完成生成、格式化和站点构建。Front Matter 页面元数据Front Matter 是每个页面的元数据区位于页面最顶部必须用---包裹。例如--- sidebar_position: 1 description: How to write documentation ---关键字段说明字段作用注意事项sidebar_position控制页面在侧边栏中的显示顺序同一目录下每个页面的值必须唯一description页面摘要用于搜索引擎与文档目录建议一句话概括页面主题slug自定义 URL 路径默认与文件名一致仅在兼容旧链接等特殊场景下修改unlisted页面是否在站点中隐藏例如 写作指南 自身就设置了unlisted: true仅供 CONTRIBUTING.md 链接引用从仓库实际页面可以看到该规范的执行情况例如 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 工具生成见下文MongoDB shell 命令博客场景jsSQL 查询sqlpsql 输出、环境变量及其他textMongoDB shell 命令与结果CTS 工具驱动的工作流这是写作指南中最重要的技术内容——FerretDB 文档中的 MongoDB shell 代码示例不是手写的而是通过 CTSCommand Test Suite工具测试和验证生成的。文档场景扩展 JSON CTS 生成存放格式相关的 MongoDB shell 命令与响应以扩展 JSON 格式存放在与文档文件相同的目录下。仓库中的实际示例是 ttl-indexes.json位于website/docs/guides/目录与 ttl-indexes.mdx 同目录。编号前缀1-file-name.json形式的前缀按升序编号1-、2-、…用于强制文档中的顺序以及 CTS 工具中的执行顺序。例如 TTL 指南的代码文件为 1-create-ttl-index.request.js 和 2-insert-ttl-data.request.js分别对应createIndexes和insert命令。生成格式化片段CTS 工具负责生成可导入 MDX 文件的格式化代码片段。运行task docs-gen即可生成。产物位置生成的代码片段存放在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 --dirwebsite/docs/guides - bin/opendocdb-cts convert --dirwebsite/docs/guides website/docs/guides --dbdb - task: fmt-docs即先对指南目录中的扩展 JSON 执行格式化fmt再转换为代码片段convert最后运行fmt-docs统一格式化文档。配套的 cts 任务 可直接将指南示例跑在真实 FerretDB 实例上验证cts: desc: Run CTS tests against FerretDB cmds: - bin/opendocdb-cts run --dirwebsite/docs/guides --urimongodb://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 中提出由社区补充定义。写作检查清单提交文档贡献前请对照以下清单自检Front Matter是否包含sidebar_position且目录内唯一与合适的description命名与 URL文件名、目录名、slug 是否为kebab-case且与页面标题一致标题是否使用 sentence case链接是否全部使用相对.md路径引用仓库内文件时是否指向具体 release tag 而非main分支图片是否存放在static/img/对应目录是否添加了描述性 alt 文本文件名是否用两到三个kebab-case单词代码块是否始终指定语言MongoDB shell 命令是否遵循 CTS 生成或js语言规范mongosh输出是否原样赋值给response术语使用的术语是否与 术语表 一致遵循以上规范你的文档贡献将能通过 FerretDB 的自动化格式检查与 CTS 验证确保文档既专业规范、又始终与真实数据库行为保持一致。赞分享后端数据库文档数据库【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址https://gitcode.com/gh_mirrors/fe/FerretDB点击查看免费下载相关推荐Anime.js文档编写API文档与示例代码规范Anime.js文档编写API文档与示例代码规范 引言 还在为JavaScript动画库的文档质量参差不齐而烦恼吗Anime.js作为一款轻量级、高性能的J前端OctoBot文档编写Markdown规范与示例代码还在为编写技术文档而头疼OctoBot开源项目为你提供了完整的文档编写指南本文将带你掌握专业的Markdown文档编写技巧让你的项目文档既专业又易读。 ?金融科技后端CesiumJS文档编写规范API文档与示例代码标准终极指南CesiumJS文档编写规范API文档与示例代码标准终极指南 CesiumJS作为领先的开源3D地球和地图可视化库其 API文档编写规范 和 示例代码标准前端3D渲染图形学数据可视化上一篇微服务依赖管理实战Spinnaker环境隔离与版本控制指南下一篇Cangjie-TPC/matrix4cj强化学习应用状态转移矩阵构建方法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
