概览是读者在产品区域中首先到达的落地页:用一段文字回答“这是什么,我该从哪里开始?”,然后再引导后续阅读。语气应易于理解、友好、对话式、直言不讳。
将概览用作产品或主要产品区域的唯一落地页,也就是其侧边栏板块打开时的那一页。它不是:
- 概念页。 把架构和权衡移到概念页并链接过去。概览用于定位,而不是深入解释。
- 光秃的目录。 没有定位说明的链接列表只会重复侧边栏。
- 营销页。 读者已经点进文档了。
完整对比请参阅内容类型。实例如 Argo Smart Routing 概览。
- 标题:产品、产品组或内容区域的名称,使用名词。不要追加 “documentation”,不要使用动名词短语,也不要使用 “Introduction”。
- 描述:用一句话点明 Cloudflare 产品及其服务对象,然后说明它适用于哪些计划。
使用 Nimbus overview 模板生成此页面。你的编程代理会获取完整页面框架和自查清单,然后根据你的产品进行调整:
npx @cloudflare/nimbus-docs add content-overviewyarn @cloudflare/nimbus-docs add content-overviewpnpm @cloudflare/nimbus-docs add content-overview将模板生成的 frontmatter 调整为 Cloudflare 的 schema:设置 pcx_content_type 和 products,替代模板生成的 type 等通用字段。
- Cards 是标志性组件:这是唯一把卡片当作正文的类型,因为引导本身就是正文。卡片文案只需名称加一行,因为会解释的卡片其实是装进盒子里的概念段落。在 Markdown 孪生页中,卡片会展平为“链接 + 描述”列表,因此这一行文案必须在两种形态下都成立。
- 当网格会迫使您写出注水文案,或某组链接确实必须超过大约五个的上限时,链接列表 优于卡片,因为散文列表在数量较多时更易扫读。
- 不适合放在这里的内容: 步骤(这里不执行任何操作)、代码块(这里不查阅任何内容,但定位句中的行内代码可以),以及折叠面板(把内容藏起来的概览等于藏起了自己的地图)。
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
---- 自包含的定位说明。 开篇段落即使单独抽出也必须准确,因为智能体被问到产品是什么时会引用它。不要依赖标题或后续章节来补全其含义。
- 字面可用性。 用字面的计划、区域或发布阶段名称说明可用性,而不是转述。
- 承重链接。 使用真实、现行的路由,因为这里过时的路由会把读者困在门口。