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

概览

最后更新 查看 MarkdownAgent 设置

概览是读者在产品区域中首先到达的落地页:用一段文字回答“这是什么,我该从哪里开始?”,然后再引导后续阅读。语气应易于理解、友好、对话式、直言不讳。

何时使用

将概览用作产品或主要产品区域的唯一落地页,也就是其侧边栏板块打开时的那一页。它不是:

  • 概念页。 把架构和权衡移到概念页并链接过去。概览用于定位,而不是深入解释。
  • 光秃的目录。 没有定位说明的链接列表只会重复侧边栏。
  • 营销页。 读者已经点进文档了。

完整对比请参阅内容类型。实例如 Argo Smart Routing 概览。

标题与描述

  • 标题:产品、产品组或内容区域的名称,使用名词。不要追加 “documentation”,不要使用动名词短语,也不要使用 “Introduction”。
  • 描述:用一句话点明 Cloudflare 产品及其服务对象,然后说明它适用于哪些计划。

搭建此页面

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

npx @cloudflare/nimbus-docs add content-overview

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

组件指南

  • Cards 是标志性组件:这是唯一把卡片当作正文的类型,因为引导本身就是正文。卡片文案只需名称加一行,因为会解释的卡片其实是装进盒子里的概念段落。在 Markdown 孪生页中,卡片会展平为“链接 + 描述”列表,因此这一行文案必须在两种形态下都成立。
  • 当网格会迫使您写出注水文案,或某组链接确实必须超过大约五个的上限时,链接列表 优于卡片,因为散文列表在数量较多时更易扫读。
  • 不适合放在这里的内容: 步骤(这里不执行任何操作)、代码块(这里不查阅任何内容,但定位句中的行内代码可以),以及折叠面板(把内容藏起来的概览等于藏起了自己的地图)。

Frontmatter

pcx_content_type: overview
products:
  - product-a
  - product-b
  - product-c

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

管理概览页面

每个产品或主要产品区域都必须有概览,因此弱概览的对策永远是加强它,而不是删除它。如果某页读起来像光秃的目录,请补上说明该区域是什么以及从哪里开始的定位文字。不要删除它,也不要让侧边栏取而代之。

您唯一会隐藏的页面是结构性分组节点:该文件夹纯粹为了在侧边栏中归组子页面,从来不是内容页。删除文件夹的 index.mdx 会导致构建错误,因此请隐藏该占位页,并通过将 group.hideIndex 设为 true 把读者重定向到后面:

---
title: Placeholder
sidebar:
  group:
    hideIndex: true
---

面向 AI 与智能体撰写

  • 自包含的定位说明。 开篇段落即使单独抽出也必须准确,因为智能体被问到产品是什么时会引用它。不要依赖标题或后续章节来补全其含义。
  • 字面可用性。 用字面的计划、区域或发布阶段名称说明可用性,而不是转述。
  • 承重链接。 使用真实、现行的路由,因为这里过时的路由会把读者困在门口。

这篇文档对您有帮助吗?