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

概念

最后更新 查看 MarkdownAgent 设置

概念页面帮助读者建立对某一主题的心智模型:某事物是什么、为何如此运作,以及边界在哪里。它面向正在入门的读者,也面向已经在使用产品、需要补上“为什么”的读者。语气为指导性、描述性、平易近人、给予支持。

何时使用

当读者在其他页面中途反复需要同一段解释时,请编写概念页面——这种反复绕路说明该模型值得拥有独立页面。它不是:

  • 如何操作。 概念页面不包含程序性步骤或配置演练。用于展示想法的代码欢迎保留,供读者跟着操作的代码则不适合。
  • 参考。 参考完整且中立,而概念有所取舍、带有观点,因此“我们建议”适合放在这里。
  • 概览。 概览把读者导向别处,而概念负责解释。每页只讲一个概念。

完整比较请参阅内容类型。

标题与描述

  • 标题:简洁的名词短语,点出该概念。高层产品概念页面使用 “About”。否则使用功能名称、能力或互联网概念,例如 Health checks 或 CDN。不要使用 “Overview”、“Introduction” 或 “How it works”,因为它们命名的是体裁而不是主题。自检方法是:在标题前加上 “About”,读起来仍然自然。
  • 描述:说明该概念是什么,以及对读者代码或选择意味着什么。

搭建此页面

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

npx @cloudflare/nimbus-docs add content-concept

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

组件指引

  • 正文是主要组件。 短段落,每节一个想法:这类页面靠写作质量支撑。
  • 图表和示例代码 适合用于展示模型,且图表必须附带等效文本。
  • 存在真正的二选一时,适合使用比较表,并同时写出该概念常被混淆的边界。
  • 不适合放入的内容: 步骤(概念没有程序性步骤或演练)、Tabs(概念不因平台而变;如果会变,那就是两个概念)以及 Cards。

Frontmatter

pcx_content_type: concept
products:
  - product-a
  - product-b

欲了解更多详情,请参考 pcx_content_type。

面向 AI 和智能体编写

  • 自成一体的定义。 用可核验的条款(例如 “at least once” 或 “not ordered”)而不是安抚性形容词来开篇,因为定义段落会被智能体检索和引用,必须能独立成立。
  • 字面负载。 将示例代码和负载放在围栏代码块中,使用完整、贴近实际的值,而不是转述。
  • 陈述式边界。 用扁平的陈述要点写出该概念不是什么,以便智能体无需重构正文即可提取。

这篇文档对您有帮助吗?