Cloudflare Docs 编辑规范与 Agent 写作指南基于仓库.agents/references/style-guide.md的权威参考手册【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本指南面向在 Cloudflare 官方文档仓库cloudflare-docs中撰写与评审技术内容的开发者与 AI Agent系统梳理 .agents/references/style-guide.md 这一精简编辑规范。它从完整版 style-guide 中提炼出可执行的强制规则涵盖 MDX 语法陷阱、frontmatter 字段校验、写作风格、文本格式、组件强制用法、代码块约定、无障碍与示例值等关键主题。阅读完本文你将掌握如何编写能通过构建校验、风格统一且利于搜索与 AI 消费的 Cloudflare 文档页面并理解这些规则背后的源码实现依据。规范定位与权威来源.agents/references/style-guide.md是仓库内面向 Agent以及人类协作者的精简规范文件。文件开头明确说明其内容从完整版 style-guide 蒸馏而来当两者存在分歧时以完整版源码页面为准。这意味着本参考手册不是孤立文档而是与以下目录共同构成文档写作的知识体系完整版风格指南存放于src/content/docs/style-guide/包含 frontmatter、组件、内容类型等完整章节。组件参考.agents/references/components.md提供全部 MDX 组件的 props、示例与边界情况。流程写作参考.agents/references/procedures.md规范 how-to 与 tutorial 页面的分步指令写法。从源码结构看src/content/docs/style-guide/下还有api-content-strategy/、documentation-content-strategy/、how-we-docs/含 AI 可消费性等子章节说明这套规范同时服务于面向人类的可读性与面向 AI 的可消费性两个目标。MDX 语法陷阱会静默破坏构建的字符在 MDX 中部分字符具有特殊含义若在正文、表格或标题中未加转义会导致构建失败字符问题修复方式{}被解释为 JS 表达式用反引号包裹或使用\{\}被解释为 JSX 元素使用lt;gt;或包裹在反引号中两条硬性规则组件导入必须位于 frontmatter 块之后。这是 Astro/MDX 的内容解析顺序要求。已使用但未导入的组件是静默构建失败。即页面不会报语法错误但运行时会渲染异常排查成本较高。因此写完 MDX 后务必检查每个用到的组件是否都已在import中声明。代码块的输出展示约定展示命令输出时将第二个代码块紧跟在命令块之后并在语言名后添加output后缀sh npx wrangler vectorize create tutorial-index --dimensions3 --metriccosine txt output ✅ Successfully created index tutorial-index 换行使用br/绝不使用两个尾随空格。Frontmatter必填字段与可选字段必填字段字段规则title必填纯文本pcx_content_type必填必须是下方枚举中的合法值之一description对带pcx_content_type的页面必填。1–2 句自包含描述长度 50–160 字符合法的pcx_content_type取值21 个changelog、concept、configuration、design-guide、example、faq、get-started、glossary、how-to、integration-guide、implementation-guide、learning-unit、navigation、overview、reference、reference-architecture、reference-architecture-diagram、release-notes、solution-guide、troubleshooting、tutorial、video。这些内容类型对应完整版规范中的 content-types 章节每种类型都有独立的写作指引例如how-to与tutorial在结构上的差异。可选字段字段类型说明sidebar.ordernumber左侧导航中的排序数字越小越靠前sidebar.labelstring覆盖导航标签默认取titlesidebar.hiddenboolean从导航隐藏但页面仍可访问productsarray按文件名关联src/content/directory/中的目录条目difficultystring仅用于教程Beginner、Intermediate、Advanced显示在教程列表中reviewedstring最近一次完整端到端评审日期格式YYYY-MM-DDsummarystring页面标题下方渲染的简短描述noindexboolean为页面添加noindex用于已废弃/遗留内容chatbot_deprioritizeboolean降低该页面在 Support AI 回复中的优先级与noindex配套使用canonicalstring覆盖link relcanonical的 URLhideChildrenboolean将该导航组折叠为指向索引页的单一链接遗留透传Nimbus 也读取sidebar.group.hideIndexfeedbackboolean显示/隐藏反馈提示框默认为true完整示例--- title: Create a Cloudflare Tunnel pcx_content_type: how-to description: Create a Cloudflare Tunnel to securely connect your private network to Cloudflare without exposing a public IP address. products: - cloudflare-tunnel sidebar: order: 2 difficulty: Beginner reviewed: 2025-01-15 ---源码层面的校验实现frontmatter 的合法性由 src/content.config.ts 与 src/schemas/base.ts 通过 Zod 模式在构建期校验。可以观察到几个印证点src/content.config.ts 中docscollection 使用strictFrontmatter: false并显式声明pcx_content_type、products、reviewed、order、difficulty、summary、canonical、hideChildren、feedback等字段注释明确指出这些字段仅需通过校验以便内容原样摄入导航/侧边栏语义由 Nimbus 自己的键sidebar.order、sidebar.hideChildren负责。src/schemas/base.ts 中baseSchema为这些字段提供了带描述信息的类型约束例如pcx_content_type被描述为页面用途由 Content strategy 中的具体页面定义。src/schemas/types/sidebar.ts 定义了sidebar对象的 Zod 模式ordernumber、labelstring、hidden默认false、badge字符串或{text, variant}对象、group.label覆盖索引页的默认 Overview 标签、group.hideIndex默认false从侧边栏隐藏索引页。pcx_content_type的取值之所以必须严格枚举是因为 ResourcesBySelector 与 ListTutorials 等组件会按该字段对页面进行过滤、聚合与自动列表渲染。写作风格语气、句式与用词核心规则主动语态、现在时。被动语态会模糊执行者并让内容快速过时。不使用缩略形式。写 do not、cannot、will not绝不写 dont、cant、wont。句长 8–12 词。一个句子只表达一个观点。操作步骤用祈使语气。以动词开头Select、Run、Go to。平实语言。避免晦涩词汇与行话缩写首次出现时给出全称。先目的、后动作。写 To create a tunnel, run...不写 Run this command to create a tunnel.。避免 LLM 套话。不用 Its important to note、leverage、seamless、dive into、straightforward 等措辞。用 for example 替代e.g.用 that is 替代i.e.绝不用etc.改写或显式列出条目。指令中不使用 please。不使用方向性语言above、below、on the right改为按名称引用元素。页面标题、标题与侧边栏标签中不使用 emoji。缩写与首字母缩略词首次出现时拼出全称之后保持一致Transport Layer Security (TLS)。基本无需拼出全称的缩写API、DVD、HTML、PDF、PC、RAM、REST、URL、USB以及计量单位MB、GB。缩写与首字母缩略词中不加句点写TLS、VPN不写T.L.S.、V.P.N.。不使用网络俚语不用tl;dr、IMO、FYI。需避免的行话不要用请使用whitelist / blacklistallowlist / blocklistmaster / slaveprimary / replica或语境相关术语man-in-the-middle attackon-path attacksanity checkvalidate / smoke testenable / disable (toggle)turn on / turn offout-of-the-boxdefaulton-premon-premises包容性语言不使用种族歧视、性别歧视或能力歧视术语。对假设主体使用性别中立代词they/them。避免涉及心理健康的隐喻crazy、insane。避免对硬件或软件使用性别化称呼she、he。术语与 UI 交互措辞使用不使用selectclickgo tonavigate toturn on / turn offenable / disablerefer tosee文本格式约定元素约定可点击的 UI 元素、菜单项、按钮标签加粗selectSave、go toDNSRecords代码、路径、IP、端口、HTTP 动词、状态码、文件名、配置键等宽字体用户需要从中选择的下拉选项斜体嵌套菜单分隔符单词加粗、分隔符用普通符号OptionsSettings需要等宽字体的内容IP 地址与网段、端口号、API 命令GET、POST、终端命令wrangler login、文件路径、文件名与扩展名wrangler.toml、配置键、数据类型string、int64、环境变量名、HTTP 头Content-Length、HTTP 状态码400、200、作为输入/输出的 URL、DNS 记录类型AAAA。两条禁令不将程序或工具名加粗——wrangler和npm用等宽而非加粗。不对开关状态使用斜体—— enabled 和 disabled 不应斜体化。大小写规范Cloudflare 产品与功能名大写Cloudflare Workers、Cloudflare WAF、Waiting Room、Zero Trust。通用技术概念小写load balancing、web application firewall、bot management。Internet大写、cloud小写。标题使用句子式大小写sentence case——只大写第一个单词与专有名词。常见术语对照正确错误DDoSDDOS, ddosSSLsslTLStlsWAFwafCAPTCHACaptcha, captchaZero Trustzero trustInternetinternet链接规范使用根相对路径/workers/get-started/绝不写https://developers.cloudflare.com/workers/get-started/。不带文件扩展名/workers/get-started/不是/workers/get-started.mdx。不支持相对链接./page不可用。必须带结尾斜杠/workers/get-started/不是/workers/get-started。使用描述性链接文本——绝不用 here、this page、read more、click here。标准句式For more information, refer to Page Title.To do something, refer to Section Title.不使用Learn more about...、To read more...、refer the [Page] page/documentation。标题与层级仅用句子式大小写——只大写第一个单词与专有名词。层级必须连续——H2 → H3 → H4不可跳级。正文中无 H1——页面titlefrontmatter 会渲染为 H1。标题末尾不加标点。页面标题与小节标题不用动名词短语Install Wrangler 而非 Installing Wrangler。副标题/子标题必须是动词或名词短语——绝不写成疑问句How do I install Wrangler?或行动号召。title与sidebar.label中不使用 emoji。列表规则流程步骤用有序列表顺序执行事实、数据或选项用无序列表。不应用无序列表的情况过程或步骤改用有序列表少于三个条目改写为句子每条超过三行的条目拆分为子小节无序列表规则所有条目必须平行保持相同语法形式。条目为完整句子时才加标点否则不加。目标 3–6 条六条规则six-pack rule是很好的默认值——最多 6 个要点、每个不超过 6 个词。每条以最重要的词开头。表格规则所有列必须有表头使用句子式大小写表头末尾不加标点。避免合并单元格——会破坏屏幕阅读器的导航。用完整句子引出表格并以冒号结尾不把表格嵌入句子中间。不用表格做页面排版——表格只放关系型数据。行按逻辑排序无逻辑顺序时按字母顺序。空单元格使用—em dash。标点规则牛津逗号。三个及以上并列项使用Workers, KV, and R2 而非 Workers, KV and R2。Em dash — 两侧带空格用于插入补充想法Cloudflare protects your site — and your users.。连字符-用于名词前的复合修饰语enterprise-class WAF名词后不加连字符Our WAF is enterprise class.。分号。尽量避免拆成短句。引号。使用直引号不用弯引号。避免对无生命物体使用所有格the device address 而非 the devices address。冒号。用于引出列表、表格和图片前面必须是完整句子。日期。文档中使用 ISO 8601YYYY-MM-DD。避免时效性内容正文中写具体日期、年月——容易过时。数字规则正文中 0–9 的整数拼写为单词10 及以上用数字。度量值、测量值与 UI 中的数值一律用数字且必须与 UI 显示完全一致。超过三位数使用逗号1,000、7,465。数字与单位之间始终保留空格128 GB、30 Tbps、4 KB。单位符号复数形式不变10 m不是10 ms。代码块约定开栅栏后必须指定语言语言名全小写。始终指定语言无合适语言时用txt别名text、plaintext。代码块中的空行不要使用 trailing spaces。终端命令不加前缀$、%、PS等——复制按钮会原样复制这些字符。Linux/macOS 命令用sh或bash。Windows PowerShell 用powershell。Windows 控制台命令用txt。Cloudflare 专属组件约定强制Workers JS/TS 示例必须使用TypeScriptExample不得使用裸js/ts栅栏。Wrangler 配置必须使用WranglerConfig且输入 TOMLcompatibility_date使用$today。包安装命令必须使用PackageManagers。组件体系必用组件与完整清单组件注册与导入可复用组件添加到 src/components.ts~/components桶导出并从~/components导入。页面专属的包装组件或一次性组件可改用深路径如~/components/BaseSchemaProperties.astro而不进桶。导入必须位于 frontmatter 块之后。从 src/components.ts 可以看到全部 80 导出包括Render、TypeScriptExample、WranglerConfig、PackageManagers、Steps、Tabs/TabItem、Details、Plan、DashButton、APIRequest、Glossary、PublicStats等印证了下方清单的完整性。强制组件用法不得用裸栅栏替代场景必用组件Workers JS/TS 示例TypeScriptExampleWrangler 配置WranglerConfigTOML 输入compatibility_date用$today包安装/执行命令PackageManagers多步骤流程StepsDashboard 导航步骤DashButton而非裸链接组件速查表组件用途Render从src/content/partials/{product}/{file}.mdx嵌入可复用 partialTypeScriptExampleWorkers TS 示例自动生成 JS 标签页WranglerConfigWrangler 配置同步 TOML JSON 标签页PackageManagers跨 npm、yarn、pnpm、bun 的包安装/执行命令WranglerCommand自动生成的完整 Wrangler 命令参考WranglerNamespace自动生成的 Wrangler 命名空间命令列表Tabs/TabItem可切换标签页syncKeydashPlusAPI或workersExamplesSteps可视化编号流程包装器Details补充内容可折叠区块FileTree文件与目录树展示Width内容宽度约束为large75%、medium50%、small25%Plan计划可用性徽章typeall、paid、pro、business、enterprise、add-onFeatureTable按计划的功能可用性来自src/content/plans/点号式idProductChangelog内嵌某产品或领域的 changelog 条目ProductAvailabilityText内嵌生命周期状态Beta、Alpha——GA 时渲染为空Feature产品概览页的功能卡片RelatedProduct概览页的关联产品卡片带图标GlossaryTooltip来自src/content/glossary/的悬停提示GlossaryDefinition内联词汇表定义Glossary完整产品词汇表InlineBadge内联状态徽章——避免使用优先在标题中用BadgeBadge标题与侧边栏的彩色状态徽章Beta、New、DeprecatedLinkButton样式化链接按钮variantprimary、secondary、minimalCard/LinkTitleCard/ListCard概览与导航页的样式化卡片容器LinkCard/CardGridNimbus 链接卡片可置于网格中DashButton链接到已验证 dashboard 深链的按钮DirectoryListing导航/概览页的自动子页面列表ListTutorials当前产品的自动教程表格ResourcesBySelector按pcx_content_type、标签或产品过滤的可筛选页面列表PublicStats内联实时统计数据中心、带宽等YouTube按 ID 嵌入 YouTube 视频Stream按 ID 或 collection 文件嵌入 Cloudflare Stream 视频APIRequest从 Cloudflare OpenAPI schema 生成curl命令CURL为任意 URL 生成curl命令PagesBuildPresetPages 框架构建预设详情RuleID可复制的规则 IDWAF / 安全规则SubtractIPCalculator交互式 IP 网段减法计算器AvailableNotifications列出产品的可用通知类型AnchorHeading自定义锚点 ID 的标题——用于组件内/非 MDX 文件Description页面标题下方渲染的描述块Markdown在 JSX 内渲染 Markdown 字符串——主要用于格式化 partial 变量完整的 props、示例与边界情况见 .agents/references/components.md。关键组件的实现原理WranglerConfig的$today机制WranglerConfig.astro 的源码揭示了其内部实现——组件解析 TOML 或 JSONC 代码块把$today魔术字符串替换为构建当天的 ISO 日期new Date().toISOString().split(T)[0]并通过injectCompatDateComment在compatibility_date上方注入提示注释TOML 用#、JSON 用//提醒读者保持日期为最新removeSchemaprop 用于省略 JSON 输出的$schema行。这意味着文档作者只需维护一份配置TOML/JSON 双格式与日期注入均由构建期自动完成。DashButton的深链校验DashButton的url必须存在于src/content/dash-routes/index.json否则构建失败。仓库中确实存在 src/content/dash-routes 目录含index.json等 3 个文件这保证了所有 dashboard 深链在发布前都被验证。Render的 partial 参数机制Render从 src/content/partials1343 个.mdx文件嵌入复用内容partial 的 frontmatter 可声明params必填参数与?后缀的可选参数支持通过{props.product}这样的 JS 表达式引用。Admonitions提示框:::note[Optional header] For supplementary context that is not essential to the main flow. Defaults to Note. ::: :::caution[Optional header] For actions that could cause issues or data loss. Defaults to Warning. ::: :::tip[Optional header] For best practices or opinionated recommendations outside the main content. Defaults to Tip. :::使用规则note用于无法融入正文的补充信息。caution用于可能破坏功能或影响安全性的操作。tip用于最佳实践与观点性建议。页面顶部可用无标题note声明计划可用性限制Only available on Enterprise plans.。保持简短不超过约 3 段或 3 个要点需要更多则创建独立章节。同一小节内同类型 admonition 不超过一个。编号步骤内部不加 admonition 标题——背景色已足够区分。整体少用。如果页面大部分内容都被 admonition 包裹应重构内容。流程写作规则Procedures流程必须包裹在Steps中。先说位置再行动作先说目的再行动作。将登录与导航合并进第一步。写 log in to 而非 log into。可选步骤以 (Optional) 开头。无方向性语言、无 please、无键盘快捷键。.agents/references/procedures.md 进一步细化了这些规则单步骤流程将步骤并入导语句子不写单项列表。子步骤用小写字母a, b, c子子步骤用小写罗马数字i, ii, iii。位置→动作In theDNSsection, selectAdd record.目的→动作To delete the rule, selectDelete.。第一步合并登录与导航Log in to the Cloudflare dashboard and go toDNSRecords.。用户需要按Enter时将其纳入该步骤。同一任务的多个流程用独立标题、页面或Tabs分隔不在同一页面堆叠多个无序编号列表。流程之后用 Next steps 引出后续任务而非 Post-requisites 章节。步骤文本不用动名词SelectSave 而非 SelectingSave。文件与目录约定文件名全小写、单词用连字符分隔get-started.mdx、api-shield-call-sequence.png。每个文件夹必须有index.mdx。文档页面src/content/docs/{product}/Partialsrc/content/partials/{product}/图片src/assets/images/{product}/—— 图片不得放入src/content/Changelogsrc/content/changelog/{product}/src/content/允许的文件类型仅.mdx、.md、.json、.yml、.yaml、.txtCI 会拒绝其他一切类型。截图与图片规范谨慎使用截图——维护成本高因为 UI 变化需要重新截图。适用于任务简单但用文字难以描述清楚的场景尤其是对 dashboard 导航不熟悉的新用户。例外changelog 条目中可自由使用截图被视为时间点参考。规范保持原始宽高比。宽度 500–600 px分辨率 72 dpi。不包含敏感信息必要时打码。避免包含侧边导航变化频繁。始终提供描述性 alt 文本。内容图片使用 Markdown 图片语法不用裸img标签。只用行内图片语法alt。不用引用式图片链接![alt][1]配合[1]: ~/assets/images/...定义——Astro 的资源管线无法解析引用式定义中的~/别名图片会渲染为损坏的相对 URL。图片存于src/assets/images/{product}/以~/assets/images/{product}/...引用。这能启用 Astro 资源管线优化、响应式变体、缓存破除。只有需要稳定静态 URL 的资源如 OG 图片、徽章、非 Astro 上下文引用的文件才用public/。不要在public/images/存放文档截图或图表。示例Cloudflare dashboard showing the DNS records page with an A record highlightedalt 文本规则描述图片显示的内容及其重要性约 150 字符以内。不以 Image of 或 Screenshot of 开头。纯装饰性图片用空 alt![]()。功能性图片按钮图标描述动作而非外观。不重复相邻说明文字。不堆砌关键词。图表中不要只靠颜色区分元素同时使用标签、形状或图案。无障碍规范不使用方向性语言see above、on the right——按名称引用元素。图表中不只靠颜色区分元素——添加标签或形状。前置条件信息放在步骤之前。代码示例前提供上下文说明代码的作用。示例值预留的保留值这些保留值不会解析到真实在线资源可放心用于示例类型值域名example.com、example.org、myappexample.comIPv4 网段192.0.2.0/24、198.51.100.0/24、203.0.113.0/24URL 占位符YOUR_DOMAIN、ZONE_ID、ACCOUNT_IDAPI shell 变量$ZONE_ID、$CLOUDFLARE_API_TOKEN用于 curl 块非 API 上下文中使用ALL_CAPS_UNDERSCORES的尖括号变量占位符在 API 示例curl 块、APIRequest组件中使用$VARIABLE_NAME的 shell 变量格式。与其他参考文档的关系本文是写作规范的三份 Agent 参考之一建议配合使用组件参考所有组件的 props、示例与边界情况是撰写 MDX 时的查表工具。流程写作参考how-to 与 tutorial 中分步指令的结构与措辞细则。完整版 style-guide规范分歧时的最终权威其中 ai-consumability 章节专门讨论了文档如何被 AI 系统更好地消费与检索。写作与评审页面时以本规范为基线、以组件参考为补充、以完整版指南为准绳可以确保每个页面在构建校验、可读性、无障碍与 AI 可消费性四个维度上保持一致。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cloudflare Docs 编辑规范与 Agent 写作指南：基于仓库 `.agents/references/style-guide.md` 的权威参考手册
Cloudflare Docs 编辑规范与 Agent 写作指南基于仓库.agents/references/style-guide.md的权威参考手册【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs本指南面向在 Cloudflare 官方文档仓库cloudflare-docs中撰写与评审技术内容的开发者与 AI Agent系统梳理 .agents/references/style-guide.md 这一精简编辑规范。它从完整版 style-guide 中提炼出可执行的强制规则涵盖 MDX 语法陷阱、frontmatter 字段校验、写作风格、文本格式、组件强制用法、代码块约定、无障碍与示例值等关键主题。阅读完本文你将掌握如何编写能通过构建校验、风格统一且利于搜索与 AI 消费的 Cloudflare 文档页面并理解这些规则背后的源码实现依据。规范定位与权威来源.agents/references/style-guide.md是仓库内面向 Agent以及人类协作者的精简规范文件。文件开头明确说明其内容从完整版 style-guide 蒸馏而来当两者存在分歧时以完整版源码页面为准。这意味着本参考手册不是孤立文档而是与以下目录共同构成文档写作的知识体系完整版风格指南存放于src/content/docs/style-guide/包含 frontmatter、组件、内容类型等完整章节。组件参考.agents/references/components.md提供全部 MDX 组件的 props、示例与边界情况。流程写作参考.agents/references/procedures.md规范 how-to 与 tutorial 页面的分步指令写法。从源码结构看src/content/docs/style-guide/下还有api-content-strategy/、documentation-content-strategy/、how-we-docs/含 AI 可消费性等子章节说明这套规范同时服务于面向人类的可读性与面向 AI 的可消费性两个目标。MDX 语法陷阱会静默破坏构建的字符在 MDX 中部分字符具有特殊含义若在正文、表格或标题中未加转义会导致构建失败字符问题修复方式{}被解释为 JS 表达式用反引号包裹或使用\{\}被解释为 JSX 元素使用lt;gt;或包裹在反引号中两条硬性规则组件导入必须位于 frontmatter 块之后。这是 Astro/MDX 的内容解析顺序要求。已使用但未导入的组件是静默构建失败。即页面不会报语法错误但运行时会渲染异常排查成本较高。因此写完 MDX 后务必检查每个用到的组件是否都已在import中声明。代码块的输出展示约定展示命令输出时将第二个代码块紧跟在命令块之后并在语言名后添加output后缀sh npx wrangler vectorize create tutorial-index --dimensions3 --metriccosine txt output ✅ Successfully created index tutorial-index 换行使用br/绝不使用两个尾随空格。Frontmatter必填字段与可选字段必填字段字段规则title必填纯文本pcx_content_type必填必须是下方枚举中的合法值之一description对带pcx_content_type的页面必填。1–2 句自包含描述长度 50–160 字符合法的pcx_content_type取值21 个changelog、concept、configuration、design-guide、example、faq、get-started、glossary、how-to、integration-guide、implementation-guide、learning-unit、navigation、overview、reference、reference-architecture、reference-architecture-diagram、release-notes、solution-guide、troubleshooting、tutorial、video。这些内容类型对应完整版规范中的 content-types 章节每种类型都有独立的写作指引例如how-to与tutorial在结构上的差异。可选字段字段类型说明sidebar.ordernumber左侧导航中的排序数字越小越靠前sidebar.labelstring覆盖导航标签默认取titlesidebar.hiddenboolean从导航隐藏但页面仍可访问productsarray按文件名关联src/content/directory/中的目录条目difficultystring仅用于教程Beginner、Intermediate、Advanced显示在教程列表中reviewedstring最近一次完整端到端评审日期格式YYYY-MM-DDsummarystring页面标题下方渲染的简短描述noindexboolean为页面添加noindex用于已废弃/遗留内容chatbot_deprioritizeboolean降低该页面在 Support AI 回复中的优先级与noindex配套使用canonicalstring覆盖link relcanonical的 URLhideChildrenboolean将该导航组折叠为指向索引页的单一链接遗留透传Nimbus 也读取sidebar.group.hideIndexfeedbackboolean显示/隐藏反馈提示框默认为true完整示例--- title: Create a Cloudflare Tunnel pcx_content_type: how-to description: Create a Cloudflare Tunnel to securely connect your private network to Cloudflare without exposing a public IP address. products: - cloudflare-tunnel sidebar: order: 2 difficulty: Beginner reviewed: 2025-01-15 ---源码层面的校验实现frontmatter 的合法性由 src/content.config.ts 与 src/schemas/base.ts 通过 Zod 模式在构建期校验。可以观察到几个印证点src/content.config.ts 中docscollection 使用strictFrontmatter: false并显式声明pcx_content_type、products、reviewed、order、difficulty、summary、canonical、hideChildren、feedback等字段注释明确指出这些字段仅需通过校验以便内容原样摄入导航/侧边栏语义由 Nimbus 自己的键sidebar.order、sidebar.hideChildren负责。src/schemas/base.ts 中baseSchema为这些字段提供了带描述信息的类型约束例如pcx_content_type被描述为页面用途由 Content strategy 中的具体页面定义。src/schemas/types/sidebar.ts 定义了sidebar对象的 Zod 模式ordernumber、labelstring、hidden默认false、badge字符串或{text, variant}对象、group.label覆盖索引页的默认 Overview 标签、group.hideIndex默认false从侧边栏隐藏索引页。pcx_content_type的取值之所以必须严格枚举是因为 ResourcesBySelector 与 ListTutorials 等组件会按该字段对页面进行过滤、聚合与自动列表渲染。写作风格语气、句式与用词核心规则主动语态、现在时。被动语态会模糊执行者并让内容快速过时。不使用缩略形式。写 do not、cannot、will not绝不写 dont、cant、wont。句长 8–12 词。一个句子只表达一个观点。操作步骤用祈使语气。以动词开头Select、Run、Go to。平实语言。避免晦涩词汇与行话缩写首次出现时给出全称。先目的、后动作。写 To create a tunnel, run...不写 Run this command to create a tunnel.。避免 LLM 套话。不用 Its important to note、leverage、seamless、dive into、straightforward 等措辞。用 for example 替代e.g.用 that is 替代i.e.绝不用etc.改写或显式列出条目。指令中不使用 please。不使用方向性语言above、below、on the right改为按名称引用元素。页面标题、标题与侧边栏标签中不使用 emoji。缩写与首字母缩略词首次出现时拼出全称之后保持一致Transport Layer Security (TLS)。基本无需拼出全称的缩写API、DVD、HTML、PDF、PC、RAM、REST、URL、USB以及计量单位MB、GB。缩写与首字母缩略词中不加句点写TLS、VPN不写T.L.S.、V.P.N.。不使用网络俚语不用tl;dr、IMO、FYI。需避免的行话不要用请使用whitelist / blacklistallowlist / blocklistmaster / slaveprimary / replica或语境相关术语man-in-the-middle attackon-path attacksanity checkvalidate / smoke testenable / disable (toggle)turn on / turn offout-of-the-boxdefaulton-premon-premises包容性语言不使用种族歧视、性别歧视或能力歧视术语。对假设主体使用性别中立代词they/them。避免涉及心理健康的隐喻crazy、insane。避免对硬件或软件使用性别化称呼she、he。术语与 UI 交互措辞使用不使用selectclickgo tonavigate toturn on / turn offenable / disablerefer tosee文本格式约定元素约定可点击的 UI 元素、菜单项、按钮标签加粗selectSave、go toDNSRecords代码、路径、IP、端口、HTTP 动词、状态码、文件名、配置键等宽字体用户需要从中选择的下拉选项斜体嵌套菜单分隔符单词加粗、分隔符用普通符号OptionsSettings需要等宽字体的内容IP 地址与网段、端口号、API 命令GET、POST、终端命令wrangler login、文件路径、文件名与扩展名wrangler.toml、配置键、数据类型string、int64、环境变量名、HTTP 头Content-Length、HTTP 状态码400、200、作为输入/输出的 URL、DNS 记录类型AAAA。两条禁令不将程序或工具名加粗——wrangler和npm用等宽而非加粗。不对开关状态使用斜体—— enabled 和 disabled 不应斜体化。大小写规范Cloudflare 产品与功能名大写Cloudflare Workers、Cloudflare WAF、Waiting Room、Zero Trust。通用技术概念小写load balancing、web application firewall、bot management。Internet大写、cloud小写。标题使用句子式大小写sentence case——只大写第一个单词与专有名词。常见术语对照正确错误DDoSDDOS, ddosSSLsslTLStlsWAFwafCAPTCHACaptcha, captchaZero Trustzero trustInternetinternet链接规范使用根相对路径/workers/get-started/绝不写https://developers.cloudflare.com/workers/get-started/。不带文件扩展名/workers/get-started/不是/workers/get-started.mdx。不支持相对链接./page不可用。必须带结尾斜杠/workers/get-started/不是/workers/get-started。使用描述性链接文本——绝不用 here、this page、read more、click here。标准句式For more information, refer to Page Title.To do something, refer to Section Title.不使用Learn more about...、To read more...、refer the [Page] page/documentation。标题与层级仅用句子式大小写——只大写第一个单词与专有名词。层级必须连续——H2 → H3 → H4不可跳级。正文中无 H1——页面titlefrontmatter 会渲染为 H1。标题末尾不加标点。页面标题与小节标题不用动名词短语Install Wrangler 而非 Installing Wrangler。副标题/子标题必须是动词或名词短语——绝不写成疑问句How do I install Wrangler?或行动号召。title与sidebar.label中不使用 emoji。列表规则流程步骤用有序列表顺序执行事实、数据或选项用无序列表。不应用无序列表的情况过程或步骤改用有序列表少于三个条目改写为句子每条超过三行的条目拆分为子小节无序列表规则所有条目必须平行保持相同语法形式。条目为完整句子时才加标点否则不加。目标 3–6 条六条规则six-pack rule是很好的默认值——最多 6 个要点、每个不超过 6 个词。每条以最重要的词开头。表格规则所有列必须有表头使用句子式大小写表头末尾不加标点。避免合并单元格——会破坏屏幕阅读器的导航。用完整句子引出表格并以冒号结尾不把表格嵌入句子中间。不用表格做页面排版——表格只放关系型数据。行按逻辑排序无逻辑顺序时按字母顺序。空单元格使用—em dash。标点规则牛津逗号。三个及以上并列项使用Workers, KV, and R2 而非 Workers, KV and R2。Em dash — 两侧带空格用于插入补充想法Cloudflare protects your site — and your users.。连字符-用于名词前的复合修饰语enterprise-class WAF名词后不加连字符Our WAF is enterprise class.。分号。尽量避免拆成短句。引号。使用直引号不用弯引号。避免对无生命物体使用所有格the device address 而非 the devices address。冒号。用于引出列表、表格和图片前面必须是完整句子。日期。文档中使用 ISO 8601YYYY-MM-DD。避免时效性内容正文中写具体日期、年月——容易过时。数字规则正文中 0–9 的整数拼写为单词10 及以上用数字。度量值、测量值与 UI 中的数值一律用数字且必须与 UI 显示完全一致。超过三位数使用逗号1,000、7,465。数字与单位之间始终保留空格128 GB、30 Tbps、4 KB。单位符号复数形式不变10 m不是10 ms。代码块约定开栅栏后必须指定语言语言名全小写。始终指定语言无合适语言时用txt别名text、plaintext。代码块中的空行不要使用 trailing spaces。终端命令不加前缀$、%、PS等——复制按钮会原样复制这些字符。Linux/macOS 命令用sh或bash。Windows PowerShell 用powershell。Windows 控制台命令用txt。Cloudflare 专属组件约定强制Workers JS/TS 示例必须使用TypeScriptExample不得使用裸js/ts栅栏。Wrangler 配置必须使用WranglerConfig且输入 TOMLcompatibility_date使用$today。包安装命令必须使用PackageManagers。组件体系必用组件与完整清单组件注册与导入可复用组件添加到 src/components.ts~/components桶导出并从~/components导入。页面专属的包装组件或一次性组件可改用深路径如~/components/BaseSchemaProperties.astro而不进桶。导入必须位于 frontmatter 块之后。从 src/components.ts 可以看到全部 80 导出包括Render、TypeScriptExample、WranglerConfig、PackageManagers、Steps、Tabs/TabItem、Details、Plan、DashButton、APIRequest、Glossary、PublicStats等印证了下方清单的完整性。强制组件用法不得用裸栅栏替代场景必用组件Workers JS/TS 示例TypeScriptExampleWrangler 配置WranglerConfigTOML 输入compatibility_date用$today包安装/执行命令PackageManagers多步骤流程StepsDashboard 导航步骤DashButton而非裸链接组件速查表组件用途Render从src/content/partials/{product}/{file}.mdx嵌入可复用 partialTypeScriptExampleWorkers TS 示例自动生成 JS 标签页WranglerConfigWrangler 配置同步 TOML JSON 标签页PackageManagers跨 npm、yarn、pnpm、bun 的包安装/执行命令WranglerCommand自动生成的完整 Wrangler 命令参考WranglerNamespace自动生成的 Wrangler 命名空间命令列表Tabs/TabItem可切换标签页syncKeydashPlusAPI或workersExamplesSteps可视化编号流程包装器Details补充内容可折叠区块FileTree文件与目录树展示Width内容宽度约束为large75%、medium50%、small25%Plan计划可用性徽章typeall、paid、pro、business、enterprise、add-onFeatureTable按计划的功能可用性来自src/content/plans/点号式idProductChangelog内嵌某产品或领域的 changelog 条目ProductAvailabilityText内嵌生命周期状态Beta、Alpha——GA 时渲染为空Feature产品概览页的功能卡片RelatedProduct概览页的关联产品卡片带图标GlossaryTooltip来自src/content/glossary/的悬停提示GlossaryDefinition内联词汇表定义Glossary完整产品词汇表InlineBadge内联状态徽章——避免使用优先在标题中用BadgeBadge标题与侧边栏的彩色状态徽章Beta、New、DeprecatedLinkButton样式化链接按钮variantprimary、secondary、minimalCard/LinkTitleCard/ListCard概览与导航页的样式化卡片容器LinkCard/CardGridNimbus 链接卡片可置于网格中DashButton链接到已验证 dashboard 深链的按钮DirectoryListing导航/概览页的自动子页面列表ListTutorials当前产品的自动教程表格ResourcesBySelector按pcx_content_type、标签或产品过滤的可筛选页面列表PublicStats内联实时统计数据中心、带宽等YouTube按 ID 嵌入 YouTube 视频Stream按 ID 或 collection 文件嵌入 Cloudflare Stream 视频APIRequest从 Cloudflare OpenAPI schema 生成curl命令CURL为任意 URL 生成curl命令PagesBuildPresetPages 框架构建预设详情RuleID可复制的规则 IDWAF / 安全规则SubtractIPCalculator交互式 IP 网段减法计算器AvailableNotifications列出产品的可用通知类型AnchorHeading自定义锚点 ID 的标题——用于组件内/非 MDX 文件Description页面标题下方渲染的描述块Markdown在 JSX 内渲染 Markdown 字符串——主要用于格式化 partial 变量完整的 props、示例与边界情况见 .agents/references/components.md。关键组件的实现原理WranglerConfig的$today机制WranglerConfig.astro 的源码揭示了其内部实现——组件解析 TOML 或 JSONC 代码块把$today魔术字符串替换为构建当天的 ISO 日期new Date().toISOString().split(T)[0]并通过injectCompatDateComment在compatibility_date上方注入提示注释TOML 用#、JSON 用//提醒读者保持日期为最新removeSchemaprop 用于省略 JSON 输出的$schema行。这意味着文档作者只需维护一份配置TOML/JSON 双格式与日期注入均由构建期自动完成。DashButton的深链校验DashButton的url必须存在于src/content/dash-routes/index.json否则构建失败。仓库中确实存在 src/content/dash-routes 目录含index.json等 3 个文件这保证了所有 dashboard 深链在发布前都被验证。Render的 partial 参数机制Render从 src/content/partials1343 个.mdx文件嵌入复用内容partial 的 frontmatter 可声明params必填参数与?后缀的可选参数支持通过{props.product}这样的 JS 表达式引用。Admonitions提示框:::note[Optional header] For supplementary context that is not essential to the main flow. Defaults to Note. ::: :::caution[Optional header] For actions that could cause issues or data loss. Defaults to Warning. ::: :::tip[Optional header] For best practices or opinionated recommendations outside the main content. Defaults to Tip. :::使用规则note用于无法融入正文的补充信息。caution用于可能破坏功能或影响安全性的操作。tip用于最佳实践与观点性建议。页面顶部可用无标题note声明计划可用性限制Only available on Enterprise plans.。保持简短不超过约 3 段或 3 个要点需要更多则创建独立章节。同一小节内同类型 admonition 不超过一个。编号步骤内部不加 admonition 标题——背景色已足够区分。整体少用。如果页面大部分内容都被 admonition 包裹应重构内容。流程写作规则Procedures流程必须包裹在Steps中。先说位置再行动作先说目的再行动作。将登录与导航合并进第一步。写 log in to 而非 log into。可选步骤以 (Optional) 开头。无方向性语言、无 please、无键盘快捷键。.agents/references/procedures.md 进一步细化了这些规则单步骤流程将步骤并入导语句子不写单项列表。子步骤用小写字母a, b, c子子步骤用小写罗马数字i, ii, iii。位置→动作In theDNSsection, selectAdd record.目的→动作To delete the rule, selectDelete.。第一步合并登录与导航Log in to the Cloudflare dashboard and go toDNSRecords.。用户需要按Enter时将其纳入该步骤。同一任务的多个流程用独立标题、页面或Tabs分隔不在同一页面堆叠多个无序编号列表。流程之后用 Next steps 引出后续任务而非 Post-requisites 章节。步骤文本不用动名词SelectSave 而非 SelectingSave。文件与目录约定文件名全小写、单词用连字符分隔get-started.mdx、api-shield-call-sequence.png。每个文件夹必须有index.mdx。文档页面src/content/docs/{product}/Partialsrc/content/partials/{product}/图片src/assets/images/{product}/—— 图片不得放入src/content/Changelogsrc/content/changelog/{product}/src/content/允许的文件类型仅.mdx、.md、.json、.yml、.yaml、.txtCI 会拒绝其他一切类型。截图与图片规范谨慎使用截图——维护成本高因为 UI 变化需要重新截图。适用于任务简单但用文字难以描述清楚的场景尤其是对 dashboard 导航不熟悉的新用户。例外changelog 条目中可自由使用截图被视为时间点参考。规范保持原始宽高比。宽度 500–600 px分辨率 72 dpi。不包含敏感信息必要时打码。避免包含侧边导航变化频繁。始终提供描述性 alt 文本。内容图片使用 Markdown 图片语法不用裸img标签。只用行内图片语法alt。不用引用式图片链接![alt][1]配合[1]: ~/assets/images/...定义——Astro 的资源管线无法解析引用式定义中的~/别名图片会渲染为损坏的相对 URL。图片存于src/assets/images/{product}/以~/assets/images/{product}/...引用。这能启用 Astro 资源管线优化、响应式变体、缓存破除。只有需要稳定静态 URL 的资源如 OG 图片、徽章、非 Astro 上下文引用的文件才用public/。不要在public/images/存放文档截图或图表。示例Cloudflare dashboard showing the DNS records page with an A record highlightedalt 文本规则描述图片显示的内容及其重要性约 150 字符以内。不以 Image of 或 Screenshot of 开头。纯装饰性图片用空 alt![]()。功能性图片按钮图标描述动作而非外观。不重复相邻说明文字。不堆砌关键词。图表中不要只靠颜色区分元素同时使用标签、形状或图案。无障碍规范不使用方向性语言see above、on the right——按名称引用元素。图表中不只靠颜色区分元素——添加标签或形状。前置条件信息放在步骤之前。代码示例前提供上下文说明代码的作用。示例值预留的保留值这些保留值不会解析到真实在线资源可放心用于示例类型值域名example.com、example.org、myappexample.comIPv4 网段192.0.2.0/24、198.51.100.0/24、203.0.113.0/24URL 占位符YOUR_DOMAIN、ZONE_ID、ACCOUNT_IDAPI shell 变量$ZONE_ID、$CLOUDFLARE_API_TOKEN用于 curl 块非 API 上下文中使用ALL_CAPS_UNDERSCORES的尖括号变量占位符在 API 示例curl 块、APIRequest组件中使用$VARIABLE_NAME的 shell 变量格式。与其他参考文档的关系本文是写作规范的三份 Agent 参考之一建议配合使用组件参考所有组件的 props、示例与边界情况是撰写 MDX 时的查表工具。流程写作参考how-to 与 tutorial 中分步指令的结构与措辞细则。完整版 style-guide规范分歧时的最终权威其中 ai-consumability 章节专门讨论了文档如何被 AI 系统更好地消费与检索。写作与评审页面时以本规范为基线、以组件参考为补充、以完整版指南为准绳可以确保每个页面在构建校验、可读性、无障碍与 AI 可消费性四个维度上保持一致。【免费下载链接】cloudflare-docsCloudflare’s documentation项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare-docs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
