参考

适用场景

当内容是关于某一个界面的事实枚举（一种文件格式、一条命令、一组类型或限制）时，写参考。它不是：

• 操作指南。 参考只描述，从不指导。如果条目里开始长出 “要做这件事，首先……” 的句子，抽出一篇操作指南并链接过去。
• 概念。 参考中立且完整；观点和理由住在概念页。开头最多允许一句带概念链接的定位句作为散文额度 —— 每个条目链接到概念和操作指南是预期做法（见 “链接与时效”）。
• 堆放场。 “杂项” 参考页是事实变得找不到的地方。每个参考页覆盖一个可命名的界面；其结构镜像产品结构，让读者能并行导航两者。

本类型的两条定律是完整性（缺失条目对参考的破坏，就像词典缺词）和一致性（每个条目以相同顺序回答相同问题）。

标题与描述

• 标题：界面的名称，按读者会搜索的写法。 “hookline.config.js” · “CLI 命令” · “事件类型” · “限制”。裸名词有歧义时加 “参考” 没问题（“重试策略参考”）。
• 描述公式：“该界面接受的每一种条目类型，以及列出的事实类别。” —— 例如 “hookline.config.js 接受的每个字段 —— 类型、默认值和约束。”

脚手架生成本页

安装配方 —— 你的编码智能体会读取完整骨架和清单，并根据你的产品做调整：

npx @cloudflare/nimbus-docs add content-reference
yarn nimbus-docs add content-reference
pnpm nimbus-docs add content-reference
bunx @cloudflare/nimbus-docs add content-reference

脚手架的定义行按界面调整：

组件建议

• 表格是标志性组件。强烈建议在条目前放一张速查表，让常见查询无需滚动。只用简单表格；合并单元格和 “用布局表达含义” 会同时破坏扫读和提取。
• 每个条目的定义行（类型 · 默认值 · 约束）按固定顺序排列 —— 用加粗或徽章保持一致。
• 不适合： Steps、卡片、提示框（需要警告框的事实通常属于条目内部的约束）、会藏起条目的标签页或折叠面板（折叠界面里的条目，对边搜边取的读者和提取都不可见）。

结尾

参考页没有结尾 —— 枚举完最后一个条目就停止（若该集合有样板尾巴，则附上）。不要 “下一步” 页脚：拿到值的读者已经走了，没拿到的读者需要的是顶部的概念链接，而不是底部。

阈值

• 完整或明确限定范围 —— 没有中间状态。 该界面接受的每个条目都在；如果某个子集有意放在别处，第一行说明在哪里。
• 条目描述散文 ≤ 3 句，中立 —— 并留出结构化出口：可枚举的更多事实（逐值语义、交互、警告）放进条目下的列表或子表，而不是更多散文。
• 一页一个界面，界面的接缝决定粒度（顶层配置分节或子命令被拆分后，本身就是一种界面）。约 30 个条目是考虑沿接缝拆分的信号，但带稳定锚点的单个长页面也是有效且对智能体友好的选择。绝不按字母拆分。

链接与时效

在存在时，把每个条目链接到解释它的概念和演练它的操作指南。保持条目锚点稳定：它们是文档站上被引用最多的 URL。

事实只有一个来源。如果条目复制了代码或 schema 里的值，就生成它们，因为手工维护的副本会漂移。没有机器来源的页面（如限制和配额）要带可见的 lastVerified 日期。

智能体说明

• 参考是智能体消费最多、在不完整时臆造最严重的类型 —— 缺失条目会被读成 “不存在”。完整性就是反臆造属性。
• 每个条目必须自成一体：标题承载完整点路径（retry.max_attempts，而不是 “Retry” 标题下的 “max_attempts”），让检索到的块自带身份。
• 范围和默认值要写成机器可核对的值，绝不要 “一个合理的数字”。
• .md 版本无需特殊处理，正因为本配方禁止把条目藏进标签页/折叠面板 —— 保持如此；生成的 Markdown 会包含完整参考页。

检查清单

建议性 —— 供作者或智能体自检，永不作为构建闸门：

• 条目上方有速查表（界面 ≥ 约 5 个条目时），生成或自觉维护
• 每个条目都存在，或在第一行说明范围排除项
• 每个条目遵循相同内部模板，标题层级相同
• 定义行包含 类型 · 默认值 · 是否必填 · 约束（按界面类型调整）
• 描述中立；溢出事实放进列表/子表，而不是散文
• 条目标题包含完整自识别名称（点路径）
• 排序已说明或自明；锚点在编辑间保持稳定
• 指明事实来源（或页面由它生成）；手工维护的事实页带 lastVerified
• 没有步骤、没有观点、没有藏在折叠组件里的内容