企业官网建设流程全解析

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 中，部分字符具有特殊含义，若在正文、表格或标题中未加转义，会导致构建失败：

两条硬性规则：

• 组件导入必须位于 frontmatter 块之后。这是 Astro/MDX 的内容解析顺序要求。
• "已使用但未导入"的组件是静默构建失败。即页面不会报语法错误，但运行时会渲染异常，排查成本较高。因此写完 MDX 后务必检查每个用到的组件是否都已在import中声明。

代码块的输出展示约定

展示命令输出时，将第二个代码块紧跟在命令块之后，并在语言名后添加output后缀：

```sh npx wrangler vectorize create tutorial-index --dimensions=3 --metric=cosine ``` ```txt output ✅ Successfully created index 'tutorial-index' ```

换行使用<br/>，绝不使用两个尾随空格。

Frontmatter：必填字段与可选字段

必填字段

合法的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在结构上的差异）。

可选字段

完整示例

--- 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 模式：order（number）、label（string）、hidden（默认false）、badge（字符串或{text, variant}对象）、group.label（覆盖索引页的默认 "Overview" 标签）、group.hideIndex（默认false，从侧边栏隐藏索引页）。

pcx_content_type的取值之所以必须严格枚举，是因为 ResourcesBySelector 与 ListTutorials 等组件会按该字段对页面进行过滤、聚合与自动列表渲染。

写作风格：语气、句式与用词

核心规则

• 主动语态、现在时。被动语态会模糊执行者，并让内容快速过时。
• 不使用缩略形式。写 "do not"、"cannot"、"will not"，绝不写 "don't"、"can't"、"won't"。
• 句长 8–12 词。一个句子只表达一个观点。
• 操作步骤用祈使语气。以动词开头："Select"、"Run"、"Go to"。
• 平实语言。避免晦涩词汇与行话；缩写首次出现时给出全称。
• 先目的、后动作。写 "To create a tunnel, run..."，不写 "Run this command to create a tunnel."。
• 避免 LLM 套话。不用 "It's 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。

需避免的行话

包容性语言

不使用种族歧视、性别歧视或能力歧视术语。对假设主体使用性别中立代词（they/them）。避免涉及心理健康的隐喻（"crazy"、"insane"）。避免对硬件或软件使用性别化称呼（"she"、"he"）。

术语与 UI 交互措辞

文本格式约定

需要等宽字体的内容：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）——只大写第一个单词与专有名词。

常见术语对照：

链接规范

• 使用根相对路径：/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 device's address"）。
• 冒号。用于引出列表、表格和图片，前面必须是完整句子。
• 日期。文档中使用 ISO 8601（YYYY-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且输入 TOML，compatibility_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等，印证了下方清单的完整性。

强制组件用法（不得用裸栅栏替代）

组件速查表

完整的 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/partials（1343 个.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 toDNS>Records."。
• 用户需要按Enter时，将其纳入该步骤。
• 同一任务的多个流程用独立标题、页面或Tabs分隔，不在同一页面堆叠多个无序编号列表。
• 流程之后用 "Next steps" 引出后续任务，而非 "Post-requisites" 章节。
• 步骤文本不用动名词："SelectSave" 而非 "SelectingSave"。

文件与目录约定

• 文件名：全小写、单词用连字符分隔：get-started.mdx、api-shield-call-sequence.png。
• 每个文件夹必须有index.mdx。
• 文档页面：src/content/docs/{product}/
• Partial：src/content/partials/{product}/
• 图片：src/assets/images/{product}/—— 图片不得放入src/content/
• Changelog：src/content/changelog/{product}/
• src/content/允许的文件类型仅：.mdx、.md、.json、.yml、.yaml、.txt，CI 会拒绝其他一切类型。

截图与图片规范

谨慎使用截图——维护成本高，因为 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 highlighted

alt 文本规则：

• 描述图片显示的内容及其重要性（约 150 字符以内）。
• 不以 "Image of" 或 "Screenshot of" 开头。
• 纯装饰性图片用空 alt：![]()。
• 功能性图片（按钮图标）描述动作而非外观。
• 不重复相邻说明文字。
• 不堆砌关键词。

图表中：不要只靠颜色区分元素，同时使用标签、形状或图案。

无障碍规范

• 不使用方向性语言（"see above"、"on the right"）——按名称引用元素。
• 图表中不只靠颜色区分元素——添加标签或形状。
• 前置条件信息放在步骤之前。
• 代码示例前提供上下文，说明代码的作用。

示例值：预留的保留值

这些保留值不会解析到真实在线资源，可放心用于示例：

非 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