文档风格指南¶

本指南介绍如何编写和编辑 docs/content/ 下的页面，面向贡献者以及他们使用的 AI 助手。新增页面和修改任何行时都应遵循本指南。现有页面可能尚未符合所有规则。如果相邻页面中的写法与本指南冲突，不要照搬；也不要在同一个拉取请求中顺手修改无关内容。

如果遵循某条规则会降低准确性或清晰度，应优先保证准确，并在拉取请求中说明原因。

清楚地写作¶

语气¶

• 使用主动语态和一般现在时。
• 步骤使用祈使句：写“将 address 设置为 :80”，不要写“你应该将 address 设置为 :80”。
• 以“你”称呼读者。在带领读者共同完成操作时，指南可以使用“我们”（例如“我们将创建一个集群”）。
• 让读者成为主语，而不是页面或产品。描述读者可以做什么、必须做什么，不要描述页面在做什么。
  • 避免：“本页让你可以将中间件附加到路由器上。”
  • 推荐：“你可以将中间件附加到路由器上，在请求到达服务前修改请求。”
• 省略“请”，将“应该”改为直接陈述。
• 英文写作中使用“click Save”，不要使用“click on Save”。
• 使用简单词语。只有在技术领域已通用（TLS、mTLS、CIDR），或 Traefik 配置、参考文档中存在的技术术语才直接使用。其他缩写首次出现时要解释。
• 不要赋予软件人的特征，例如“Traefik 想要”“路由器决定”。
• 不要包含客户名称或客户专属细节。将使用场景一般化，或省略它。
• 除非第三方服务的文档或源码明确说明，否则不要描述该服务会接受什么、拒绝什么或要求什么。源码只能证明 Traefik 发送了什么，不能证明外部服务会如何响应。应链接到第三方文档。
• 当源码确实支持某个供应商特有行为时，先说明通用条件，再以该供应商为例：“如果身份提供者不返回任何组，例如 ExampleIdP 的行为，……”

数字¶

• 英文正文中的一到十使用单词拼写，11 及以上使用数字。
• 数值、版本、端口以及带单位的数字始终使用阿拉伯数字：maxBodySize: 5、HTTP/2、端口 80、5 MB。
• 不要声明页面中某个列表或表格包含多少项，例如“以下三个选项”。列表变化后这个数量就会过时。产品本身定义的限制，例如“最多 100 个路由器”，可以保留。

应避免的词语和短语¶

替换成简单词语：

直接删除，保留句子其他部分。 去掉以下词语，句子仍然成立： cutting-edge、innovative、In conclusion、To summarize、As mentioned above。

改成具体事实。 以下词语没有描述具体内容，应重写句子并补充实际细节：

• 避免：“与 Consul 稳健、无缝地集成。” 推荐：“Traefik 从 Consul Catalog 读取服务，并在服务变化时更新路由。”
• 避免：“强大的中间件让你简化身份验证。” 推荐：“forwardAuth 中间件在请求到达后端前，将每个请求发送给身份验证服务。”
• 避免：“这赋予你控制流量的能力。” 推荐：“你可以使用 rateLimit 中间件限制每个客户端的请求。”

这条规则适用于：streamline、robust、comprehensive、powerful、seamless、seamlessly、empower、delve into。

同时避免以下句式：

• 用破折号连接句子。 拆成两个句子，或用“因此”“并且”“但是”连接。不要简单地将破折号替换为分号或冒号。
• 反问句，例如“但如果你需要 X 呢？”应改为陈述句。
• 夸张描述，例如“这改变了一切”。直接陈述事实。
• 对比式包装，例如“它不只是代理，更是平台”。直接陈述正面事实。如果否定用于指出读者可能选错的值，则可以使用，例如“超时单位设为秒，不是毫秒”。
• 绝对化表述，例如“即使 Y 也绝不 X”。说明规则并保留源码给出的条件。本条不适用于安全警告和 !!! danger 内容，它们应保留明确措辞，例如“绝不要在没有身份验证的情况下暴露仪表盘”。

清晰表达规则¶

• 写出具体名词。 如果所指名词不在同一句中，将“这”“它”“相同内容”“两者”“这些”替换成具体对象。每一行表格都应能独立理解。
• 指代选项时使用确切选项名。 指代配置项时写 entryPoints，解释概念时写“入口点”。英文正文写“identifier”，不要写“ID”。只有字面字段使用 id；标准名称或界面名称保持原样，例如“Client ID”“Trace ID”。
• 给出具体建议。 将“使用较小的超时”改为“将 idleTimeout 设置为较小值，例如 3s”。只使用源码或参考文档中出现的选项和值。
• 步骤中的每个句子都应影响读者的操作。 每句都应给出动作、使用的值或动作结果。本条不适用于选项说明、警告、概念和参考页面、简介及提示块。
• 不要只声称有某种能力，却不说明使用方式。 写“你可以验证每个条目”时，同一节中要提供步骤或链接。
• 行为因状态或其他选项值而异时，分别说明每种情况。 明确列出每个子选项的名称和值。
• 以取舍解释存在权衡的选项。 说明它做什么、何时使用，以及保持开启的风险。
• 限制条件紧跟其限定的选项、步骤或示例。 前置条件放在依赖它的操作之前。
• 例外先写动作。 先写“为 y 设置 x。 如果不设置，……”，再解释原因。
• 不要依赖相对位置。 避免“上面”“下面”“如前所示”等说法，改为指明章节或选项。读者经常从搜索结果直接进入页面中部。
• 不要复述代码。 解释步骤为什么重要，不要描述一个易读代码块已经展示的操作。
• 明确演示场景只是示例。 例如写“以支付 API 为例”，避免读者把该场景误认为功能限制。
• 概念简介中不要混入部署细节。 选项名称和值应放在前置条件或参考页面中。
• 仅为已核实的版本描述特定行为。 如果整页都要求 vX，就省略“从 vX 开始”。某个选项在更晚版本加入时，仍保留其说明。本条不适用于 migrate、deprecation 页面或安全公告，因为它们的内容本身就是版本差异。

术语¶

• 使用安装配置（install configuration）和路由配置（routing configuration）。新增英文内容不要再写“static configuration”或“dynamic configuration”。旧页面可能同时使用这两套术语；如果术语属于引用的选项名称或 URL，则保持不变。
• 每页首次提及时使用 Traefik Proxy，后续使用 Traefik。
• 跨页面对同一个概念使用同一个名称。引入新名称前，先搜索相邻页面和所链接页面已有的术语，并在每页第一次出现时定义它。
• 使用提供者自己的名称，例如 Docker、Consul Catalog、Kubernetes Gateway API、IngressRoute。不要在正文中缩写这些名称。

页面类型¶

新增内容应归入现有章节，不要添加顶级章节。

参考页面¶

参考页面正文不使用 H1，直接从描述性句子开始。适用时，按以下顺序组织章节：

1. 配置示例。 每个受支持格式提供一个示例。
2. 配置选项。 使用选项表格。

指南页面¶

指南以描述任务的正文 H1 开头，按以下顺序组织：

1. 简短介绍读者将完成什么，以及何时需要这样做。
2. 前置条件。 如果缺少某项前置条件会造成可见故障，说明读者将看到什么。
3. 每个步骤或任务使用一个 H2，以动词命名，例如“创建集群”。
4. 结尾段落陈述结果，并链接相关页面，不要重复全部步骤。

在每个主要步骤结束时说明预期结果。如果某一步对应的示例有自己的标识符（例如 Kubernetes 的 metadata.name），该标识符应包含步骤编号，后续引用该步骤时也保持一致。

页面标题与章节标题¶

• 每个英文标题和页面标题都使用标题式大小写（Title Case），即使为某个其他标题大小写不一致的页面添加标题，也应如此。首尾单词和实义词首字母大写；冠词、连词和短介词（a、an、the、and、but、or、for、in、of、on、to、with）小写，除非位于标题开头或结尾。
• 代码、选项名称、缩写和错误信息保持原样：entryPoints、HTTP、connection refused。
• 任务用动词命名，例如“配置粘性会话”；参考章节使用产品自己的术语，例如“证书解析器”。
• 不要将标题写成问题，也不要写成读者的探索过程，例如“找出哪里出错了”。改用“排查失败请求”。
• 故障排查条目以症状或确切错误信息命名。
• 参考页面 frontmatter 中的英文标题遵循既有形式：Traefik <Name> Documentation。
• 每节都应在不依赖前后章节的情况下独立理解。

格式¶

Frontmatter¶

只使用 title 和 description。描述使用一个句子概括页面内容，用于搜索结果。

代码块与标签页¶

• 配置示例展示功能支持的所有格式，并确保不同格式产生相同配置。
• 按以下顺序使用这些标签名称：
  • 安装配置： File (YAML)、File (TOML)、CLI、Helm Chart Values。
  • 路由配置： Structured (YAML)、Structured (TOML)、Labels、Tags、Kubernetes。仅包含提供者支持的格式。
• 使用构建指南中的标签页语法，在代码围栏上添加 tab="Label" 属性。
• 在支持注释的格式中，将解释放入示例注释，每个示例解释一次。不要在示例周围的段落中复述示例。
• 代码围栏语言使用 yaml、toml、bash 或 text，不要留空。

选项表格¶

• 使用字段、说明、默认值和必需列。如果表格列出固定值，则用值替代默认值和必需。
• 每个字段名链接到自身锚点，便于读者引用单个选项。
• 每个选项说明包括作用、预期格式和示例值。
• 说明选项未设置时的行为。例如写“Traefik 不压缩响应”，不要只写“默认配置”。
• 如果某字段有条件限制，明确何时适用或必须设置。
• 长表按字母顺序排序。不要使用面向读者的表头，例如“告诉你什么”；使用“包含内容”“作用”等中性标签。
• 扩展表格时写出每一行，绝不要用“...”或“等”省略原有行。
• 不要在表格后再用列表换一种方式对相同行分组，应添加一列。
• 避免需要横向滚动的表格，将其拆分或改用列表。

提示块¶

• 默认使用正文。只有信息放在正文中容易被忽略时，才使用提示块。
• 额外细节或替代方案使用 !!! note，遗漏会导致错误的限制使用 !!! warning，快捷方法使用 !!! tip，背景信息使用 !!! info。如果仅凭类型不能充分表达内容，应添加标题。
• 如果提示块只是在解释某个指令为什么重要，将其合并进指令本身。
• 不要连续堆叠两个提示块。中间加入正文，或将其中一个改为正文。
• ??? example 是用于较长可选示例的折叠容器，不是强调注意事项的提示块，因此不受上述限制。

链接¶

• 链接文字写明目标，不要写“这里”或“此链接”。
• 使用指向 .md 文件的相对路径：[HTTP Routers](../routing/router.md)。
• 仅链接目标分支上实际存在的页面。如果页面尚不存在，使用纯文本，并在拉取请求中注明缺失链接。
• 移动或重命名页面后，在 mkdocs.yml 中添加重定向。

截图与媒体¶

• 用文字说明操作，截图用于辅助，不能取代文字。
• 每张截图都要有替代文字和配套说明句。
• 尽量少用截图。
• 写出控件名称，例如“点击设置”，不要描述位置，例如“左侧按钮”。

图示¶

尽量避免新增图示。只有图示能显著改善新功能的说明时才添加，并遵循以下要求：

• 将图片以 PNG 保存到 docs/content/assets/img/，如果工具能干净地导出 SVG，也可以使用 SVG。在拉取请求中说明可编辑源文件的位置，方便维护者更新。
• 使用相对路径和 Markdown 图片语法引用：![Request Flow Through Entry Points, Routers, and Services](../assets/img/request-flow.png)。
• 替代文字直接说明图片展示什么，不要写“……的图示”。
• 用一个句子引入图示，并使用与图示相同的标签名称。
• 图中承载的每个事实也必须写在正文里，因为使用屏幕阅读器或搜索的读者无法读取图片内容。
• 不要重画其他页面已有图示的流程。链接已有页面，或逐条对照源码核验每个箭头。

生成文件¶

不要手动编辑以下文件，构建步骤会覆盖它们：

• reference/install-configuration/configuration-options.md
• reference/dynamic-configuration/traefik.io_*.yaml 和 kubernetes-crd-definition-v1.yml

如需修改生成参考文档中的选项说明，应修改 Go 结构体字段注释，再运行 make generate。如果生成后存在未提交的变更，CI 检查会失败。

创建拉取请求之前¶

1. 对照源码或第三方文档验证每项陈述。不要添加未经确认的错误消息、默认值或数值，也不要发布未经验证的行为。
2. 检查每个链接和锚点都能解析。
3. 按贡献指南运行 mkdocs build --strict 和 Markdown 检查。
4. 选择正确分支：新功能指向 master，修复指向相应发布版本的维护分支。不要自行回移修改。
5. 如果使用了大量 AI 辅助，在提交尾注中添加 Assisted-by: 声明。