NextPDF 文档组织结构

重点摘要

NextPDF 手册遵循一份固定契约演进。每个页面只涵盖一个主题、对应一种 Diataxis 模式，并且只属于一种页面类型。每种页面类型都有一组必备的第二层标题。少数几份 manifest（清单文件）与 gate 会在手册扩展过程中维持结构一致。

本页说明这套系统的整体结构，帮助你的贡献落在正确位置。完整且具有规范性的契约，包括确切的标题清单、引用规则，以及逐步的 gate 接入流程，记载于内部治理文档 docs/style/expansion-standard.md。先读本页；动笔撰写时再查阅那份文档。

选择页面类型

按下列顺序应用这些规则，判断应新增页面还是扩充既有页面：

1. 如果这份内容是一个独立主题，读者不会预期它出现在既有页面中，就新增一个页面。
2. 如果这份内容是在补充既有页面已经涵盖的主题，就扩充那个页面。
3. 如果这份内容属于深入细节，会让安装、quickstart（快速上手）或 task（任务）页面变得臃肿，就把它移到独立页面并链接过去。
4. 其余情况，扩充既有页面。

确定页面需要存在后，就设置它的 Diataxis 模式；该模式会确定页面类型：

• Tutorial（教程）面向学习者，因此采用 task guide（任务指南），并写成 recipe（范例）形式。
• How-to（操作指引）帮助有经验的读者完成一项任务，因此采用 task guide、server API 指南或 SDK 指南。
• Reference（参考）陈述确切事实，因此采用 API reference（API 参考）或 Index（索引）页面。
• Explanation（说明）用于建立理解，因此采用 developer guide（开发者指南）或 premium 功能指南。

浅显直白的用语是每一种模式的基准，并非独立的一种模式。

页面类型总览

手册契约认可下列几种类型。只要你的页面带有 API 表格，就沿用既有类型；只有在页面完全没有 API 表格时，才为它引入一个仅有标签（label-only）的新类型。

• Index 类型：section-index、api-index、extension-index。
• Reference 类型：api-reference。任何带有标准 API 表格的页面都沿用这个类型，包含 server 与 Python SDK 参考。
• Explanation 类型：developer-guide。架构、生命周期与扩展点的说明文字都沿用这个类型，包含 server 与 Python SDK 指南。
• 仅有标签的新类型：premium-feature-guide 与 task-guide，两者皆用于没有 API 表格的页面。

每个页面都以 ## At a glance 开头。每个 api-reference 页面都带有共用的 API 表格与 Development notes 标题。必备标题必须恰好是第二层，并各自独占一行；你可以在它们下方继续添加更多标题。

撰写检查清单

撰写页面时，请同时满足这两份检查清单。内部标准以规范性语气陈述每一项，并链接其所依据的标准。

开发者友好度：

• 从 examples/ 或 tests/Cookbook 取用可执行的范例，并为每个围栏代码块加上 title= 信息字符串。
• 在 front-matter（前置数据）与开头处说明先决条件。
• 任何会产生输出的范例，都应显示其预期输出。
• 让代码块保持可直接复制粘贴：每个块只使用一种语言、首次使用时写出完整名称、末尾不留下提示符。
• 展示默认安全的代码：生产环境的范例使用 try/catch，搭配最具体的 NextPDF 异常，且绝不写空的 catch。
• 以可继续阅读的延伸链接收尾，并设定 front-matter 的 related:。

翻译就绪度：

• 每句话只表达一个概念，避免机器翻译产出过长且难以断句的句子。
• 标题与标签保持简短，因为多数目标语言在翻译后会变长。
• 避免使用习惯用语。
• 符号名称、config 键、CLI 标志与异常名称维持代码格式；像 PDF/A-4、PAdES 与 eIDAS 这类标准名称绝不翻译。
• 如实设定 i18n_ready 与 xliff_segments，并以 Unicode NFC 撰写。

关于语气、代码范例、术语与引用样式，请遵循内部标准所引用、已通过审定的样式覆盖表。

接入各个 gate

新页面按一套有先后顺序的流程接入：

1. 建立页面骨架，让它的 front-matter 符合站点 schema（架构）。
2. 按照该页面类型的必备标题撰写正文。
3. 向 docs/manual-contract.json 加入一条 { path, owner, kind, headings[] } 项目。路径相对于 src/content/docs，使用正斜线，且不带开头斜线、不含 ..。
4. 若是 API 参考，请把该页面的符号加入 docs/api-coverage-manifest.json；每个符号都必须出现在页面中，并且确实存在于源代码里。
5. 只有在页面来自一个新的来源仓库时，才更新 docs/source-manifest.json。
6. 将该页面作为一条明确项目加入 astro.config.mjs 中正确的侧边栏分组。
7. 为仅英文页面新增一行语言区域覆盖率，并把全部十七个语言区域单元格都设为 missing。
8. 执行文档 gate、构建和性能预算检查。

站点自有页面放在 src/content/docs 底下，把 owner 设为 nextpdf-docs，且绝不带 aggregate（聚合）标记。聚合而来的页面源自某个来源仓库，它们的发布标志位于来源端的 front-matter，因此应在那里编辑，而不是在这里。

另请参阅

• Integrations：跨多个软件包展示手册结构的最完整范例。
• 内部治理文档 docs/style/expansion-standard.md 保存完整契约：每种页面类型的确切标题清单、引用规则，以及完整的 gate 接入流程。