跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

参考

最后更新 查看 MarkdownAgent 设置

参考页完整、并以统一结构枚举某一可命名界面的事实,例如文件格式、命令或一组限制。语气为平实、直截了当。

何时使用

当读者需要查阅某一界面的精确事实时,使用参考页。该类型受两条法则约束:完整性,因为漏掉一条就会像词典漏掉一个词一样破坏参考;统一性,因为每条都以相同顺序回答相同问题。它不是:

  • 如何操作。 参考只描述,从不指导。如果某条目写成“要做这件事,先……”,请抽出如何操作页并链接过去。
  • 概念。 观点和原理解释放在概念页,因此页首只允许一句定位说明并链接到概念。
  • 杂物堆。 “杂项”会让事实变得无法找到。每页只对应一个界面,并镜像产品自身的结构。

完整对比请参阅内容类型。实例如常见 Cf-Polished 状态和 Logpush API 配置。

标题与描述

  • 标题:读者搜索该界面时使用的名称,例如 “CLI commands”、“Event types” 或 “Limits”。独立单页使用“参考”;带子页面的板块使用名词;仅当裸名称会产生歧义时才在名词后加 “reference”,例如 “Retry policy reference”。
  • 描述:点明该界面接受的条目种类,以及每个条目列出的事实类别。

搭建此页面

使用 Nimbus reference 模板生成此页面。你的编程代理会获取完整页面框架和自查清单,然后根据你的产品进行调整:

npx @cloudflare/nimbus-docs add content-reference

将模板生成的 frontmatter 调整为 Cloudflare 的 schema:设置 pcx_content_type 和 products,替代模板生成的 type 等通用字段。

组件指南

  • 表格 是标志性组件:在条目之前放一张速查表,让常见查阅无需滚动。保持表格简单,因为合并单元格和靠版式表达含义会同时破坏扫读和抽取。
  • 定义行 以固定顺序承载相同事实,例如类型、默认值、是否必需和约束,并在每条中以粗体或徽章保持一致。
  • 当参考是一个板块而不是单页时,DirectoryListing 用于链接子页面。
  • 不适合放在这里的内容: 步骤、Cards 和标注框(需要警告的事实通常应作为约束写进条目),以及会隐藏条目的选项卡或折叠面板(折叠起来的条目对“搜索即取”的读者和抽取都不可见)。

Frontmatter

pcx_content_type: reference
products:
  - product-a
  - product-b

有关更多详细信息,请参阅 pcx_content_type。

完整性与事实来源

参考要么完整,要么明确限定范围,不能介于两者之间;若子集在别处,第一行就要说明在哪里。每个事实只能有一个来源:存在于代码或 schema 中的值应生成;若尚无法生成,请点明来源,以便维护者知道要对照什么做 diff。手工维护的事实页(例如限制或配额)应带有可见的 reviewed 日期。当某个界面大约超过 30 条时,按它自身的缝隙拆分,例如文件布局或命令组,绝不要按字母顺序拆。

面向 AI 与智能体撰写

  • 条目可自识别。 给每个条目标题使用全名,例如点分路径 retry.max_attempts,而不是在 “Retry” 标题下只用 max_attempts,这样被检索到的片段仍带有自身身份。
  • 可机检的取值。 用字面值陈述范围、默认值和限制,而不是“一个合理的数字”;示例保持最小,放在围栏代码块中,并使用真实值。
  • 不要隐藏任何内容。 让每条都保持展开,因为折叠或放进选项卡的条目对抽取不可见。参考页的 Markdown 孪生页就是该页本身。

这篇文档对您有帮助吗?