企业官网建设流程全解析

Backstage 文档写作风格指南：从语言规范到源码工具链的完整实践

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage

本指南系统梳理 Backstage 开源仓库的文档写作规范，覆盖语言与语气、Markdown 格式标准、代码片段约定、Admonitions 与 Accordions 用法、内容最佳实践以及官方词汇表，并结合仓库中的 Docusaurus 站点配置、Vale 文档检查脚本 与 链接验证脚本 展示这些规范如何被工具化落地。阅读后你将掌握一套可直接用于 Backstage 文档贡献（以及大型开源项目文档协作）的写作与审查标准。

文档指南的定位与适用场景

Backstage 的官方文档风格指南位于 docs/contribute/doc-style-guide.md，它的定位非常明确：这是一组 guideline（指南），而非硬性规则。编写文档时应运用最佳判断力，如果发现指南本身需要改进，欢迎通过 Pull Request 提议修改。

该指南服务于两类读者：

• Backstage 贡献者：在提交文档改动（尤其是 Markdown 文件）时需要遵循的写作与格式约定。仓库的 CONTRIBUTING.md 明确指出文档贡献是参与 Backstage 的最佳起点之一，并推荐先通读本风格指南（见 CONTRIBUTING.md 文档贡献章节）。
• 在文档站点写作的任何参与者：包括插件作者、维护者以及撰写教程、词汇表、架构决策记录（ADR）的社区成员。

语言：美式英语与文档站点

Backstage 文档统一使用U.S. English（美式英语）的拼写和语法。这意味着诸如color、behavior、center这类美式拼写是标准写法。

文档站点本身由Docusaurus构建，使用标准 Markdown，并支持 Docusaurus 特有的扩展特性（如 admonitions）。这一点可以从仓库根目录的 microsite/docusaurus.config.ts 得到印证：文档目录被直接配置为../docs（配置位置），并启用了 Mermaid、OpenAPI 文档等能力。因此，任何贡献到docs/的 Markdown 都会经过 Docusaurus 的解析与渲染管线。

语气：像一位知识渊博的同事

指南对文档语气给出了五条核心原则。整体目标是：亲切（approachable）、专业（professional）、有帮助（helpful）。写作时把自己想象成一位知识渊博的同事，正在向一位熟悉软件开发、但刚接触该主题的同行解释问题。

文档格式标准

用粗体标注界面元素

提到按钮、菜单项等界面元素时使用粗体，不要用引号。

用斜体定义或引入新术语

首次定义或引入新术语时使用斜体，而不是粗体或引号。

文件名、目录与路径使用代码样式

所有文件名、目录路径必须用反引号包裹。

行内代码与命令使用代码样式

包名与 API 引用使用代码样式

涉及包名、函数名、配置字段时一律使用反引号：

用尖括号表示占位符

占位符使用尖括号，并在文字中说明它代表什么：

yarn workspace @backstage/plugin-<plugin-name> start

引号内标点遵循国际标准

句号放在引号外（英式/国际习惯），除非标点本来就是引文的一部分：

代码片段格式

不要包含命令提示符

代码块中只写命令本身，不要带上$等提示符：

命令与输出分离

命令与输出分别放在独立代码块中，并用文字引导：

yarn start

输出类似于：

[0] webpack output is served from / [1] Loaded config from app-config.yaml

使用合适的语言标签

围栏代码块必须使用正确的语言标识符：

• ts或typescript：TypeScript 代码
• yaml：YAML 配置
• shell：shell 命令
• log：命令输出
• shell-session：同时包含提示符与输出的对话记录
• diff：changeset 变更
• text：其他都不合适时（如目录树）

一个容易忽略的细节：标识符必须是 Prism 能识别的语言，凡是超出 Docusaurus 默认内置集合的语言，都必须在站点配置的additionalLanguages中登记，否则代码块不会报错，但会静默失去语法高亮。Backstage 站点的实际配置如下（microsite/docusaurus.config.ts#L678-L704）：

prism: { theme: backstageTheme, // Supported languages: https://prismjs.com/#supported-languages additionalLanguages: ['docker', 'bash', 'log', 'shell-session'], magicComments: [ // ...高亮行、增删行注释约定 ], },

可以看到docker、bash、log、shell-session被显式加入高亮支持列表；同时magicComments还定义了highlight-next-line、highlight-start/highlight-end、highlight-add-*、highlight-remove-*等注释约定，用于在代码块中标记重点行。

Admonitions：警示块的正确用法

Backstage 文档使用 Docusaurus admonitions 作为提示框，四种类型各司其职：

• :::note：补充性信息
• :::tip：有帮助的建议
• :::caution：潜在陷阱
• :::danger：可能导致数据丢失或安全问题的操作

基本语法（admonition 内部支持 Markdown）：

:::note You can use _Markdown_ inside admonitions. :::

自定义标题：把标题放在方括号中紧跟在类型后。需要注意，旧式的"类型后空格直接写标题"写法已经失效——那样写的话 admonition 会渲染成纯文本：

:::tip[Browser window didn't open] Navigate to `http://localhost:3000` yourself. :::

使用注意点：

• 仅在标题能补充类型本身未表达的信息时才添加标题；一个:::note配上Note标题纯属噪音，应省略。
• 保持简短聚焦，每个 admonition 只讲一个清晰要点；如果需要写多个段落，考虑是否应移入正文。
• 避免连续堆叠多个 admonition，过多提示框会稀释影响力。如果某个小节超过两个 admonition，应重构内容，把大部分信息放回普通段落。

Accordions：可折叠区块

使用 HTML 的<details>和<summary>元素创建可折叠区块，适合"常见问题"、冗长的参考表格或会打断阅读流程的补充内容：

<details> <summary>Summary text visible when collapsed</summary> Content inside the accordion. You can use **Markdown** here, including code blocks, lists, and other formatting. </details>

两个关键细节：

1. 在<summary>标签之后、</details>闭合标签之前各留一个空行，否则内部的 Markdown 内容无法正确渲染。
2. <summary>内部的代码一律使用反引号（`）而不是 HTML 的<code>标签——反引号在 summary 元素中能正确渲染，且与全文其他 Markdown 的写法保持一致。

Markdown 元素规范

换行

块级内容（标题、列表、图片、代码块等）之间用一个空行分隔；段落源码按合理的行宽手动换行，这能让 diff 更易审查，也有助于后续本地化翻译。

标题与标题大小写

段落

• 尽量保持段落不超过 6 个句子，避免大段无断落的"文字墙"。
• 需要水平分割线时使用三个连字符（---），但不要把它当作装饰。

链接

描述性链接文字尤为重要：使用屏幕阅读器的用户常常通过逐条列出链接来浏览页面，the Kubernetes configuration能告诉他们链接去向，而裸地址做不到。

当想直接展示地址本身时，语法取决于文件扩展名：

• 在.md文件中，可以用尖括号或 Markdown 链接。
• 在.mdx文件中必须用 Markdown 链接——尖括号在.mdx中不合法，会导致构建失败。

仓库对链接的自动化校验也印证了这些约定：脚本 scripts/verify-links.js 会遍历仓库中的 Markdown，提取所有标题锚点（extractHeadingAnchors，并处理重复标题的-1、-2后缀）以校验页内锚点，同时用INVISIBLE_CHAR_PATTERN拦截 URL 中的零宽字符等不可见 Unicode 字符（见 verify-links.js#L27-L90）。

列表

• 如果列表中有任何一项是完整句子，则每项都以句号结尾；为保证一致性，要么全部是完整句子，要么全部不是。
• 有序列表统一使用数字1.。
• 无序列表使用-。
• 每个列表后留一个空行。
• 嵌套列表缩进两个空格。
• 步骤序列使用编号列表，而不是用 "First"、"Then"、"Finally" 的散文式叙述——编号列表更易扫读、顺序更明确，也方便读者指代具体步骤：

表格

使用带清晰列头的 Markdown 表格，保持内容简洁。对于大量结构化数据，考虑改用列表或拆分独立小节，而不是塞进一张巨型表格。

内容最佳实践

首次出现时拼写缩写

首次使用缩写时，先写出全称并在括号中给出缩写，之后可以单独使用缩写：

例外：URL、API、HTML 这类目标读者（软件开发者）普遍熟知的缩写无需拼写全称。

使用现在时

例外：当必须表达正确含义时，才使用将来时或过去时。

使用主动语态

例外：如果主动语态会导致表达笨拙，可以使用被动语态。

使用简单直接的语言

以 "you" 称呼读者

避免拉丁短语

优先使用英文表达替代拉丁缩写：

例外：表示"等等"时可使用 "etc."。

应避免的写作模式

审慎使用 "we"

"we" 在教程和引导式文章中是可接受的，此时它表示"你和我一起完成这个过程"。但当它指代不明（是 Backstage 项目、维护者还是读者团队）时应避免：

避免行话和习语

部分读者以英语为第二语言，避免行话和习语有助于他们理解：

避免关于未来的声明

不做关于未来的承诺或暗示。如果必须谈论实验性功能，请明确标注它是实验性的。

避免很快过时的声明

避免使用 "currently"、"new" 这类时效性强的词——今天的新功能几个月后可能就不再"新"了：

避免假定读者理解程度的词

避免 "just"、"simply"、"easy"、"easily"、"simple" 这类不增加价值的词：

Backstage 专用词汇表

以下术语在全站必须保持一致用法：

通用词汇表

此外，仓库还提供了词汇表条目的专门写作规范 docs/references/writing-a-glossary-entry.md，说明词条由标题（术语 + 消歧符）、首句定义、可选的补充句与外部链接组成，例如用{word} ({disambiguator})的标题形式区分不同语境下的同名术语——这可以视为本风格指南在"术语一致性"上的延伸落地。

规范的工具化落地：文档质量如何被自动检查

风格指南不只是纸面约定，Backstage 用一套脚本将其落地为 CI 可执行的检查：

1. Vale 语言检查：scripts/check-docs-quality.js 调用 Vale linter（配置文件为根目录的 .vale.ini，其中StylesPath = .github/vale、Vocab = Backstage，文档库即来自本风格指南中的词汇表）。脚本runVale会以--config指定配置并逐文件运行（check-docs-quality.js#L83-L103），ciCheck则在 CI 中只对 PR 改动的.md文件执行检查，并把 Vale 输出转成 GitHub Actions 注解与 eslint 风格的行内报告（check-docs-quality.js#L105-L129）。需要新增专业词汇时，把词加入.github/vale/config/vocabularies/Backstage/accept.txt即可，这一点在 CONTRIBUTING.md 的 Vale 说明中也有提及。

2. 链接验证：scripts/verify-links.js 负责扫描 Markdown 链接，验证目标文件与标题锚点是否存在（自动处理{#custom-id}显式锚点和 GitHub/Docusaurus 兼容的 slug 化规则），并拦截 URL 中的不可见 Unicode 字符，防止出现"看起来正常但点击失效"的链接。

3. 本地执行入口：在 CONTRIBUTING.md 的文档贡献部分（L126、L199）明确给出了本地命令yarn run lint:docs（即yarn lint:docs # Lint all the Markdown files），它运行上述文档质量检查。注意 Vale 需要单独安装并保证全局命令可访问。

对于想要为 Backstage 提交文档的开发者，推荐的工作流是：先在本地运行yarn lint:docs通过 Vale 与链接检查，再对照本指南逐项自查格式与措辞；若 Vale 对某个代码引用报错，用反引号包住该引用即可，若是需要认可的专业术语，则提交到 accept.txt 词汇表。

小结

Backstage 文档风格指南的核心可以浓缩为三句话：用准确、简洁、友好的英文写作，把一切代码与命令相关的内容用反引号标注，让自动化工具（Vale 与链接检查）替你守住格式底线。从语言语气到格式细节，再到词汇表和工具链，这套规范既保证了百万级文档站点（docs 目录 + Docusaurus 渲染）的一致性，也让每一位贡献者的改动都能被快速审查和合并。无论你是贡献 Backstage 文档，还是为自己所在团队搭建文档规范，这份指南都值得直接借鉴。

【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage