企业官网建设流程全解析

• 文档
• 教程
• 云原生

本文基于 Knative 官方文档仓库中的风格指南 documenting-code.md，系统讲解 Knative 文档中代码片段、CLI 命令、YAML 资源与变量占位符的书写标准。读完后，你将能够按照 Knative 文档社区的既有规范撰写或评审技术文档中的代码内容，并结合mkdocs.yml与自定义样式表理解这些规范背后的渲染机制，使产出与现有文档（如 Eventing 配置指南、Functions 片段库）保持一致。

风格指南在 Knative 文档体系中的位置

Knative 文档仓库将全部写作规范集中在contribute-to-docs/style-guide/目录下，包括本文档 documenting-code.md 以及 标题与格式规范、语气与语言、词汇与短语列表、内容复用。

风格指南目录说明 中有一句值得注意的定调：

You don't need to read the whole style guide before contributing to Knative documentation. Unpolished contributions delivered early are better than perfect contributions delivered late.

也就是说，规范的目标是降低协作摩擦、保证文档风格统一，而不是设立贡献门槛。本文聚焦其中"代码如何写"这一篇，它与其余各篇是互补关系：标题用祈使句（见 style-and-formatting.md），正文用现在时和主动语态（见 voice-and-language.md），而本文档负责其中的代码部分。

哪些文本必须使用行内代码格式

指南第一条明确了行内代码格式（inline code）的适用边界，只对以下五类文本使用：

• 文件名（Filenames）
• 路径名（Path names）
• YAML 文件中的字段和取值（Fields and values from a YAML file）
• 任何需要输入到 CLI 的文本
• CLI 工具名称（CLI names）

这一条与 style-and-formatting.md 中"标题中不要使用代码格式"的规则配套：标题写Configure the class annotation而不是Configure the class annotation加反引号。两者合起来定义了"代码格式只出现在正文的具体技术对象上"这一原则，避免读者把普通英文单词误认为是需要逐字输入的内容。

为代码块指定编程语言

每个代码围栏（fence）都必须声明语言标识符，用于语法高亮；对不属于任何编程语言的内容——典型如 CLI 命令——统一使用bash：

正确示例（Go 源码标注go）：

package main import "fmt" func main() { fmt.Println("hello world") }

错误示例（同一段 Go 源码误标为bash）：

package main import "fmt" func main() { fmt.Println("hello world") }

这条规则看似简单，但直接影响阅读体验与语法高亮效果。Knative 文档使用 MkDocs Material 主题（见 mkdocs.yml），围栏上的语言标识会被映射为对应的 highlight 类；语言标错时高亮规则与内容不匹配，代码可读性直接受损。

命令说明的标准句式："... by running the command:"

指南对"引出命令"的导语给出了标准格式：

X the Y by running the command:

该句式需要同时满足四条标准：

1. 明确提到"运行命令"（running the command），这一点并不总是显而易见的；
2. 用词是 "run"，而不是 "type"、"execute" 等——一致性优先；
3. 先描述命令的作用，再给出命令本身；
4. 尽可能简短。

若必须偏离该标准句，仍须满足上述四条标准。

正确示例：

Create the service by running the command:

kn create service <service-name>

Where<service-name>is the name of your Knative Service.

错误示例共三种典型偏差：

• 只写 "Create the service:"——没有提到"运行命令"，也没有先说清动作的完整语义；
• 只写 "Run:"——没有描述命令的作用；
• 写 "Run the following command to create a service:"——语义颠倒，把"运行命令"放在了动作描述之前，且不如标准句简洁。

这一句式并非只写在指南里。从仓库中现网文档的用法看，它被严格一致地执行，例如 event-display.md 片段：

1. Apply the YAML file by running the command: kubectl apply -f <filename>.yaml Where `<filename>` is the name of the file you created in the previous step.

以及 broker-configuration.md 中的 "Start acurlpod by running the following command:"。对贡献者而言，这意味着"标准句 + Where 变量说明"是 Knative 文档中命令段的固定范式，新增文档照此书写即可通过风格一致性检查。

YAML 文档化：两步走，以及 apply 与 edit 的选用

指南规定 YAML 相关内容一律采用两步法：第一步创建 YAML 文件，第二步应用该文件。并给出选择kubectl apply还是kubectl edit的判据：

• 用户自行创建的文件/对象用kubectl apply：它同时覆盖"创建"和"更新"两种场景，且用户的本地文件是唯一事实来源（source of truth）；
• 随 Knative 软件分发的对象用kubectl edit：例如 Knative Serving 和 Knative Eventing 的 ConfigMap。

此外，当 YAML 是作为 CLI 命令的一部分被输入时，代码块开头要写yaml语言标识。

正确写法示例：

创建或更新资源时：

1. Create a YAML file using the following template:

   # YAML FILE CONTENTS

2. Apply the YAML file by running the command:

   kubectl apply -f <filename>.yaml

   Where<filename>is the name of the file you created in the previous step.

编辑 ConfigMap 时：

kubectl -n <namespace> edit configmap <resource-name>

而以下两种"heredoc 一步到位"的写法被明确判定为错误：

cat <<EOF | kubectl create -f - # code EOF

kubectl apply -f - <<EOF # code EOF

从文档工程角度看（指南未逐条列出原因，以下为基于两步法要求的推断）：heredoc 把"定义资源"与"下发资源"揉进同一条命令，既无法让读者把 YAML 内容保存为可复用的本地文件（与"本地文件是 source of truth"的原则相悖），也无法在变量说明和排错时把两步拆开定位问题。

代码块中变量占位符的书写规范

变量统一使用尖括号小写连字符格式：<service-name>。具体规则有四条：

• 全部小写；
• 单词之间用连字符（hyphen）分隔；
• 每个变量必须在代码块下方给出解释；
• 解释的固定句式是 "Where...<service-name>is…"。

单个变量

正确：

kn create service <service-name>

Where<service-name>is the name of your Knative Service.

错误（使用大写下划线风格并改变说明句式）：

kn create service {SERVICE_NAME}

{SERVICE_NAME} = The name of your service

多个变量

正确（所有变量汇总到一个 "Where:" 列表中）：

kn create service <service-name> --revision-name <revision-name>

Where:

• <service-name>is the name of your Knative Service.
• <revision-name>is the desired name of your revision.

错误（为每个变量各起一行 "Where..."）：

kn create service <service-name> --revision-name <revision-name>

Where<service-name>is the name of your Knative Service. Where<revision-name>is the desired name of your revision.

这一约定同样体现在现网文档中，例如 broker-configuration.md 里先写kubectl get broker <broker-name>，再统一说明 "Where<broker-name>is the name of your Broker."

用省略号标注代码摘录

当展示的是 YAML 文件的一个摘录而非完整可运行的示例时，必须在缺失上下文的行用...显式标出，以表明"这只是所需文件的一部分"。

正确：

apiVersion: serving.knative.dev/v1 kind: Service metadata: ... spec: ... traffic: - percent: 54 revisionName: config-00008 ...

错误（看起来像完整文件、实际缺了metadata等内容，读者可能直接复制导致 apply 失败）：

apiVersion: serving.knative.dev/v1 kind: Service metadata: spec: traffic: - percent: 54 revisionName: config-00008

这条规则的价值在于把"可复制即运行"与"仅为示意"两类代码块在视觉上区分开，防止读者把教学摘录当成完整清单。

CLI 输出块：{ .bash .no-copy }的规则与实现原理

指南规定：展示命令输出（而非命令本身）时，代码块的语言标识应写为自定义 CSS 类"{ .bash .no-copy }"而不是bash，其作用是移除代码块右侧的"复制到剪贴板"按钮——输出没有复制价值，按钮属于噪音。

正确：

<some-code>

错误：

<some-code>

这一语法为何能生效，可以在仓库构建配置中找到完整证据链：

1. mkdocs.yml 中 Material 主题启用了content.code.copy特性，它会给所有代码块注入"Copy"按钮；
2. 同一配置启用了attr_listMarkdown 扩展，它允许在代码围栏后以{ ... }语法附加 CSS 类（即{ .bash .no-copy }这种写法的来源）；
3. 仓库自定义样式表 extra.css 中定义了：

.highlight.no-copy .md-clipboard { display: none; }

即当代码块携带no-copy类时，.md-clipboard（复制按钮容器）被隐藏。三者结合，{ .bash .no-copy }在保留 bash 高亮的同时精准关闭了复制按钮。

现网文档中这一模式已大量落地，例如 event-display.md 中展示kubectl apply输出（service.serving.knative.dev/event-display created）与 Pod 列表时均使用no-copy块；broker-configuration.md 展示 Broker 的kubectl get输出时同样如此；社区代码示例如 helloworld-go 的 README 也在kubectl输出处使用了该写法。

命令行标志：统一使用短格式

指南最后一条规则：文档中出现的命令标志一律使用短格式，例如用-n而不是--namespace。

正确：

kubectl apply -f <filename>.yaml -n <namespace>

错误：

kubectl apply --filename <filename>.yaml --namespace <namespace>

这与"标准句保持尽可能短"的整体精神一致：短标志让命令在文档排版中更紧凑，也更贴近开发者日常肌肉记忆。

本地验证与快速自检清单

文档仓库提供了本地预览链路：hack/mkdocs.sh 以mkdocs serve --livereload方式启动站点（默认端口 8000），完整流程参见 本地预览指南。提交 PR 前在本地过一遍渲染效果，是验证代码块语言标识、no-copy按钮是否消失、省略号排版是否符合预期的最直接手段。

把本文档的核心规则压缩成一份可操作的自检清单：

相关资源

• 原始风格指南条目：documenting-code.md
• 风格指南总目录：Knative style guide
• 标题、链接与排版规范：style-and-formatting.md
• 语气与用词规范：voice-and-language.md
• 构建配置（主题特性与 Markdown 扩展）：mkdocs.yml
• 复制按钮隐藏样式：docs/stylesheets/extra.css
• 遵循上述范式的现网示例：broker-configuration.md、event-display.md
• 本地预览文档：previewing-docs-locally.md

• 文档
• 教程
• 云原生