概念页面帮助读者建立对某一主题的心智模型:某事物是什么、为何如此运作,以及边界在哪里。它面向正在入门的读者,也面向已经在使用产品、需要补上“为什么”的读者。语气为指导性、描述性、平易近人、给予支持。
当读者在其他页面中途反复需要同一段解释时,请编写概念页面——这种反复绕路说明该模型值得拥有独立页面。它不是:
- 如何操作。 概念页面不包含程序性步骤或配置演练。用于展示想法的代码欢迎保留,供读者跟着操作的代码则不适合。
- 参考。 参考完整且中立,而概念有所取舍、带有观点,因此“我们建议”适合放在这里。
- 概览。 概览把读者导向别处,而概念负责解释。每页只讲一个概念。
完整比较请参阅内容类型。
- 标题:简洁的名词短语,点出该概念。高层产品概念页面使用 “About”。否则使用功能名称、能力或互联网概念,例如 Health checks 或 CDN。不要使用 “Overview”、“Introduction” 或 “How it works”,因为它们命名的是体裁而不是主题。自检方法是:在标题前加上 “About”,读起来仍然自然。
- 描述:说明该概念是什么,以及对读者代码或选择意味着什么。
使用 Nimbus concept 模板生成此页面。你的编程代理会获取完整页面框架和自查清单,然后根据你的产品进行调整:
npx @cloudflare/nimbus-docs add content-conceptyarn @cloudflare/nimbus-docs add content-conceptpnpm @cloudflare/nimbus-docs add content-concept将模板生成的 frontmatter 调整为 Cloudflare 的 schema:设置 pcx_content_type 和 products,替代模板生成的 type 等通用字段。
- 正文是主要组件。 短段落,每节一个想法:这类页面靠写作质量支撑。
- 图表和示例代码 适合用于展示模型,且图表必须附带等效文本。
- 存在真正的二选一时,适合使用比较表,并同时写出该概念常被混淆的边界。
- 不适合放入的内容: 步骤(概念没有程序性步骤或演练)、Tabs(概念不因平台而变;如果会变,那就是两个概念)以及 Cards。
pcx_content_type: concept
products:
- product-a
- product-b欲了解更多详情,请参考 pcx_content_type。
- 自成一体的定义。 用可核验的条款(例如 “at least once” 或 “not ordered”)而不是安抚性形容词来开篇,因为定义段落会被智能体检索和引用,必须能独立成立。
- 字面负载。 将示例代码和负载放在围栏代码块中,使用完整、贴近实际的值,而不是转述。
- 陈述式边界。 用扁平的陈述要点写出该概念不是什么,以便智能体无需重构正文即可提取。