Help us learn about your current experience with the documentation. Take the survey.

文档风格指南

本文件定义了GitLab文档的标准，包括语法、格式等。
有关具体词汇的指南，请参阅词汇表。

GitLab的语气

GitLab品牌指南定义了整个组织的语气。

基于该指导原则，GitLab文档中的语气力求简洁、直接且精确。目标是提供易于搜索和浏览的信息。

文档中的语气应口语化但简短，友好但简洁。

文档是单一事实来源（SSoT）

GitLab文档是所有与实施、使用及故障排除相关的产品信息的单一事实来源（SSoT）。文档持续演进，会随着新产品和新功能的推出而更新，也会因清晰度、准确性和完整性方面的改进而更新。

这一政策：

  • 防止信息孤岛，使查找关于GitLab产品的信息更加容易。
  • 并不意味着内容不能在文档的多个地方重复。

主题类型

GitLab使用主题类型来组织产品文档。

主题类型帮助用户更快地消化信息。它们还能解决这些问题：

  • 内容难以找到。 GitLab文档全面且包含大量有用信息。主题类型创建了可重复的模式，使内容更容易扫描和解析。
  • 内容通常是从贡献者的角度撰写的。 GitLab文档由各类贡献者撰写。主题类型（特别是任务）有助于将信息整理成帮助他人的格式，而非记录功能是如何实现的。

文档优先方法论

产品文档应是完整且可信的资源。

  • 如果问题的答案存在于文档中，请分享文档链接而不是重新措辞信息。
  • 当您遇到GitLab文档中没有的信息时，创建合并请求（MR）将该信息添加到文档中。然后分享MR以传达该信息。

我们越自发地将信息添加到文档中，文档就越能帮助他人高效完成任务和解决问题。

为本地化而写作

GitLab 文档尚未本地化，但我们遵循有助于面向全球受众撰写的指南。

GitLab 的声音 要求我们清晰直接地撰写，同时考虑翻译。
我们的风格指南、词汇表 和 Vale 规则 确保文档的一致性。

当文档被翻译成其他语言时，每个单词的含义必须清晰。
机器翻译、GitLab Duo Chat 和其他 AI 工具的使用日益增加，这意味着一致性变得更加重要。

以下规则可以帮助文档更高效地翻译。

需避免：

  • 隐藏主语的短语，例如 there is 和 there are。
  • 模糊的代词，例如 it。
  • 以 -ing 结尾的单词。
  • 容易混淆的单词，例如 since 和 because。
  • 拉丁缩写，例如 e.g. 和 i.e.。
  • 特定文化的引用，例如 一石二鸟。

建议使用：

  • 标准的 链接文本。
  • 使用 列表 和 表格，而不是复杂的句子和段落。
  • 常用缩写，例如 AI 和 CI/CD，以及之前已完整拼写的缩写。

此外，请记住以下指导原则：

  • 保持 功能名称 及其交互方式的一致性。
  • 拆分名词串。例如，不用 project integration custom settings，而是使用 custom settings for project integrations。
  • 为国际受众一致地格式化 日期和时间。
  • 谨慎使用 插图，包括截图。
  • 对于 UI 文本，允许翻译中最多 30% 的扩展和收缩。
    要查看字符串在其他语言中的扩展或收缩程度，可将该字符串粘贴到 Google Translate 中并查看结果。
    请一位会说该语言的同事验证翻译是否清晰。

Markdown

所有 GitLab 文档均采用 Markdown 编写。

文档网站 使用 Hugo 静态站点生成器及其默认的 Markdown 引擎 Goldmark。

通过使用 markdownlint 和 Vale 测试 Markdown 格式。

Markdown 中的 HTML

硬编码的 HTML 是有效的，但由于以下几个原因不被鼓励：

  • 自定义标记可能会破坏未来的全站变更或设计系统更新。
  • 自定义标记没有测试覆盖来确保整个网站的一致性。
  • 自定义标记可能不具备响应性或可访问性。
  • 自定义标记可能不符合 Pajamas 指南。
  • Markdown 中的 HTML 和 CSS 在 /help 上不会渲染。
  • 手动编写 HTML 容易出错。 malformed HTML 可能会破坏页面布局或其他组件。

如果满足以下条件，则允许使用 HTML：

  • Markdown 中不存在等效项。
  • 内容由技术作家审核批准。
  • 自定义元素的需求紧急，无法等待技术写作工程师的实施。

如果您有关于文档网站上可用的新元素的创意或请求，请提交一个 功能请求。

Markdown 中的标题级别

每个文档页必须在 元数据 中包含一个 title 属性。
呈现为 HTML 时，title 成为 H1 元素。
不要在 Markdown 中添加 H1 标题，因为每页只能有一个。

  • 对于每个子节，递增标题级别。换句话说，增加主题标题前 # 字符的数量。
  • 避免标题级别高于 H5（#####）。如果需要超过五个标题级别，请将主题移至新页面。高于 H4 的标题级别不会显示在右侧边栏导航中。
  • 不要跳过级别。例如：## > ####。
  • 在主题标题前后留一个空行。
  • 如果在主题标题中使用代码，请确保代码在反引号中。
  • 不要在主题标题中使用粗体文本。

Markdown中的描述列表

要定义术语或区分选项，请使用描述列表。对于UI元素列表，请改用常规 列表 而非描述列表。

不要将描述列表与其他样式混合使用。

Term 1
: Definition of Term 1

Term 2
: Definition of Term 2

这些列表会呈现为如下效果：

Term 1
Definition of Term 1
Term 2
Definition of Term 2

短代码

短代码 是模板代码片段，我们可以将其包含在Markdown内容中，以在页面上显示非标准元素（例如提醒框或标签页）。

GitLab文档使用以下短代码：

语言

GitLab文档应清晰易懂。

  • 避免冗余词汇。
  • 表述清晰、简洁，紧扣主题目标。
  • 使用美式英语及美式语法。（已在 British.yml 中测试。）

主动语态

在大多数情况下，使用主动语态而非被动语态，文本更易理解和翻译。

例如，使用：

  • 开发人员编写应用程序的代码。

而非：

  • 应用程序代码由开发人员编写。

有时，以 GitLab 作为主语会显得生硬。例如 GitLab 导出报告。此时应改用被动语态，例如 报告被导出。

客户视角

关注GitLab为客户带来的功能和益处，而非GitLab创建的内容。

例如，使用：

  • 使用合并请求比较源分支和目标分支中的代码。

而非：

  • GitLab允许你比较代码。
  • GitLab创建了让你能比较代码的功能。
  • 合并请求让你比较代码。

表明未从客户视角撰写的词语有 allow 和 enable。尝试改用 you，并直接与用户对话。

建立信任

产品文档应专注于提供清晰简洁的信息，不添加销售或营销文本。

  • 不要使用诸如 easily 或 simply 这类词。
  • 不要使用营销短语，如“此功能将为你节省时间和金钱。”

相反，聚焦事实和可实现的目标。具体举例：

  • 使用此功能时，构建时间可能会减少。
  • 创建项目时使用此功能可节省时间。API 会生成文件，你无需手动干预。

自指式写作

避免撰写关于文档本身的内容。例如，不要使用：

  • 本页面展示…
  • 本指南解释…

这些表述会拖慢用户节奏。直接切入正题即可。例如，不用：

  • 本页面解释不同类型的管道。

而是用：

  • GitLab 有多种类型的管道以满足你的开发需求。

已在 SelfReferential.yml 中测试。

大小写

作为公司，我们倾向于使用小写。

主题标题

主题标题使用句子大小写。例如：

  • # 使用变量配置管道
  • ## 使用待办事项清单

UI 文本

当提及特定用户界面文本（如按钮标签、页面、标签页或菜单项）时，使用与用户界面显示相同的大小写。

若你认为用户界面文本存在风格错误，请创建问题或MR提议修改用户界面文本。

功能名称

功能名称应为小写。

但在极少数情况下，功能名可为标题大小写。例外情况包括：

  • 以专有名词形式添加到 markdownlint 中，以便在整个文档中统一应用。
  • 添加到 词汇表 中。

若该术语不在词汇表中，请联系GitLab技术作家寻求建议。有关命名功能的帮助及确保符合GitLab标准的指导，参见 手册。

默认情况下，不要匹配 功能页面 或 features.yml 中的术语或短语的大小写。

其他术语

需大写的名称包括：

  • GitLab 产品层级。例如， GitLab Free 和 GitLab Ultimate。
  • 第三方组织、软件及产品。例如，Prometheus、 Kubernetes、Git 和 The Linux Foundation。
  • 方法或方法论。例如，持续集成 (Continuous Integration)、 持续部署 (Continuous Deployment)、Scrum 和 Agile。

遵循该实体权威来源所列的大写风格，其可能采用非标准的大小写样式。例如：GitLab 和 npm。

虚假用户信息

文档中不要包含真实的用户名或电子邮件地址。

对于文本：

  • 使用多样化的或无性别指向的名字，搭配常见姓氏，例如 Sidney Jones、Zhang Wei 或 Alex Garcia。
  • 虚假的电子邮件地址以 example.com 结尾。

对于截图：

  • 截图前临时编辑页面：

    1. 右键点击你想修改的文本。
    2. 选择 Inspect。
    3. 在 Elements 对话框中，编辑 HTML 以替换包含真实用户信息的文本为示例数据。
    4. 关闭对话框。网页上的所有用户数据现在应已替换为你输入的示例数据。
    5. 进行截图。

  • 或者，在测试环境中创建示例账户，并在那里截取截图。

  • 如果无法重现环境，可使用图像编辑工具（如 macOS 上的 Preview）模糊用户数据。

虚假 URL

在文档中加入示例 URL 时，使用：

  • 当域名通用时，使用 example.com。
  • 仅指代 GitLab 自托管版时，使用 gitlab.example.com。 对于 GitLab.com，使用 gitlab.com。

虚假令牌

文档中不要使用真实令牌。

使用以下虚假令牌作为示例：

令牌类型 令牌值
个人访问令牌 <your_access_token>
应用 ID 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6
应用密钥 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df
CI/CD 变量 Li8j-mLUVA3eZYjPfd_H
项目 Runner 令牌 yrnZW46BrtBFqM7xDzE7dddd
实例 Runner 令牌 6Vk7ZsosqQyfreAxXTZr
触发令牌 be20d8dcc028677c931e04f3871a9b
Webhook 密钥令牌 6XhDroRcYPM5by_h-HLY
健康检查令牌 Tu7BgjR9qeZTEyRzGG2P

缩写

鼓励使用缩写，能营造友好随意的语气， 尤其在教程、指导文档和 用户界面 中。

不过，有些缩写应避免使用：

不应使用缩写形式 示例 应改为
与专有名词和动词连用时 Terraform’s 是个有用的工具。 Terraform 是个有用的工具。
用于强调否定 Don’t 用 Y 安装 X。 Do not 用 Y 安装 X。
在参考文档中 Don’t 设置限制。 Do not 设置限制。
在错误消息中 向 localhost 发起的请求 aren’t 允许。 向 localhost 发起的请求 are not 允许。

所有格

对于专有名词（如组织或产品名称），不要使用所有格（’s’）。

例如，不要写成 Docker's CLI，而应写作 the Docker CLI。

详情请参阅 Google 文档风格指南。

介词

必要时可在句末使用介词。 悬垂或孤立的介词是可以接受的。例如：

  • 你可以离开你所属的小组。
  • 将凭证分享给你想授权的用户。

这些表达比替代说法更口语化：

  • 你可以离开你所属的那个小组。
  • 将凭证分享给那些你想授权的用户。

首字母缩略语

如果使用首字母缩略语，请在页面上首次出现时写出全称。同一页内不要再重复写出全称。

  • 标题：尽量避免在主题标题中使用缩写，尤其是当缩写未被广泛认知时。
  • 复数：尽量不要让缩写变为复数。例如，使用 YAML 文件，而非 YAMLs。若必须使缩写变为复数，不要使用撇号。例如，使用 APIs，而非 API's。
  • 所有格：对缩写使用所有格时要谨慎。若有可能， 改写句子以避免缩写变为所有格。若必须使缩写变为所有格，考虑写出完整词语。

数字

文本中的数字，零到九用单词拼写，十及以上用数字表示。更多信息请参见 微软风格指南。

文本

  • 使用Markdown编写。

  • 新段落前插入空行。

  • 不同标记之间插入空行（例如，每段、标题和列表之后）。示例：

    ## 标题

段落。

- 列表项1
- 列表项2

行长度

为了使源内容易于阅读，并便于比较差异，请遵循以下最佳实践。

  • 将长行在约100个字符处拆分。（例外：不要拆分链接。）
  • 每个新句子从新的一行开始。

注释

要在Markdown中嵌入注释，使用发布时不呈现的标准HTML注释。示例：

<!-- 这是不会呈现的注释 -->

标点符号

遵循以下标点符号指南。

  • 完整句子以句号结尾，包括表格中的完整句子。
  • 在三个或更多项目的列表中，在最后一个 and 或 or 前使用系列（牛津）逗号。（已在 OxfordComma.yml 中测试。）

在间距方面：

  • 句子之间使用一个空格。（使用多个空格的情况已在 SentenceSpacing.yml 中测试。）
  • 不要使用非断开空格。改用标准空格。（已在 lint-doc.sh 中测试。）
  • 不要使用制表符进行缩进。改用空格。考虑配置你的代码编辑器，使其在按下 Tab 键时输出空格而不是制表符。

不要使用这些标点符号：

  • ;（分号）：改用两个句子。
  • –（短破折号）或 —（长破折号）：改用单独的句子或逗号。
  • “ ” ‘ ’：双引号或单引号（花体引号）。改用直引号。（已在 NonStandardQuotes.yml 中测试。）

占位符文本

在代码块中，你可能需要提供使用特定值的命令或配置。

在这种情况下，使用 < 和 > 来标注读者必须用自己的值替换文本的位置。

例如：

cp <your_source_directory> <your_destination_directory>

如果占位符不在代码块中，使用 < 和 > 并将占位符包裹在单个反引号中。例如：

选择 **Grant admin consent for `<application_name>`**。

引号

遵循 微软关于引号的指南。

尽量避免对用户输入使用引号，而是使用反引号。

文本格式化

格式化文本时，使用：

  • 加粗 用于UI元素和页面。
  • 内联代码样式 用于输入、输出、代码等类似内容。
  • 代码块 用于命令行示例、多行输入、输出、代码等类似内容。
  • <kbd> 用于键盘命令。

加粗

加粗用于：

  • 有可见标签的UI元素。匹配标签的文本和大小写。
  • 导航路径。

不要对关键词或强调使用加粗。

UI元素包括：

  • 按钮
  • 复选框
  • 设置
  • 菜单
  • 页面
  • 标签

例如：

  • 选择 取消。
  • 在 问题 页面…
  • 在 流水线 标签…

要使文本加粗，用双星号（**）包裹。例如：

1. 选择 **取消**。

当你对UI元素使用加粗格式时，将任何标点符号放在加粗标签之外。 此规则包括句号、逗号、冒号和右尖括号（>）。

标点符号属于句子结构的一部分，而非你强调的UI元素本身。

当标点符号是UI元素本身的一部分时，将其包含在加粗标签中。

例如：

  • **开始审核**: 这是描述启动审核按钮的文字。
  • 选择 **概览** > **用户**。

内联代码

内联代码是用单反引号（`）包裹的文本。例如：

在 **Name** 文本框中输入 `test`。

在内联代码中使用以下内容：

  • 用户在界面中输入的文本。
  • 短输入和输出，如 true、false、Job succeeded 等。
  • 文件名、配置参数、关键词和代码。例如，.gitlab-ci.yml、--version 或 rules:。
  • 简短错误消息。
  • API 和 HTTP 方法（POST）。
  • HTTP 状态码。完整形式（404 File Not Found）和缩写形式（404）。
  • HTML 元素。例如，<sup>。包含尖括号。

例如：

  • 在 Name 文本框中输入 test。
  • 使用 rules: CI/CD 关键词控制何时向流水线添加任务。
  • 发送 DELETE 请求删除 Runner。发送 POST 请求创建一个。
  • 任务日志完成时显示 Job succeeded。

代码块

代码块将代码文本与常规文本分离，用户可以复制粘贴。

在代码块中使用以下内容：

  • CLI 和 cURL 命令。
  • 多行输入、输出和代码示例，这些内容对于 内联代码 来说过于庞大。

要添加代码块，在文本上方和下方添加三重反引号（```），并在顶部指定语法名称以实现正确的语法高亮。例如：

```markdown
这是一个使用 Markdown 演示 **粗体** 和 `反引号` 的代码块。
```

使用代码块时：

  • 在代码块上下方添加空行。
  • 使用其中一个 支持的语法名称。如果没有更好的选项，请使用 plaintext。
  • 当代码块中包含另一个已使用三重反引号的嵌套代码块时，使用四重反引号（````` ）。上面的示例内部使用了四重反引号来说明代码块格式。

要在代码块中表示缺失信息，请使用注释或 省略号。例如：

  • # 为可读性移除
  • // ...

键盘快捷键

引用按键操作时，使用 HTML 的 <kbd> 标签。例如：

要停止命令，按 <kbd>Control</kbd>+<kbd>C</kbd>。

此示例渲染为：

要停止命令，按 Control+C。

斜体和强调

在产品文档中避免 使用斜体进行强调。相反，编写清晰的内容，无需强调即可理解。GitLab 和 https://docs.gitlab.com 使用无衬线字体，但斜体文字在这种页面中 并不突出。

列表

使用列表以更易扫描的格式呈现信息。

  • 使列表中的所有项目平行（即结构一致）。例如，不要让某些项目以名词开头，其他项目以动词开头。

  • 所有项目都以大写字母开头。

  • 给所有项目相同的标点符号。

  • 如果项目不是完整句子，则不要使用句号。

  • 完整句子后使用句号。不要使用分号或逗号。

  • 在引导短语后添加冒号（:）。例如：

    要完成任务：

- 执行此操作。
- 执行另一项操作。

  • 不要使用 粗体 格式定义列表中的关键词或概念。仅对 UI 元素标签使用粗体。例如：

    • **开始审核**：这是启动审核按钮的描述。
    • 离线环境：这是离线环境的描述。

    对于关键词和概念，可以考虑使用 参考主题 或 描述列表 作为替代格式。

选择有序或无序列表

使用有序列表表示步骤序列。例如：

按照以下步骤执行操作。

1. 首先，执行第一步。
1. 然后，执行下一步。
1. 最后，执行最后一步。

当步骤不需要按顺序完成时，使用无序列表。例如：

这些内容被导入：

- 项目 1
- 项目 2
- 项目 3

列表标记

  • 对无序列表使用破折号（-）而非星号（*）。
  • 有序列表的每个项目都以 1. 开头。渲染时，列表项会按顺序排列。
  • 在列表前后留空行。
  • 用空格（而非制表符）开头来表示 嵌套子项。

列表项内的嵌套

以下项目可以嵌套在列表项下，因此它们会以与列表项相同的缩进显示：

嵌套项目应始终与列表项的第一个字符对齐。对于无序列表（使用 -），每级缩进使用两个空格：

- 无序列表项 1

  一行嵌套文本，使用 2 个空格与上方的 `U` 对齐。

- 无序列表项 2

  > 一个引用块，将嵌套
  > 在列表项 2 内部。

- 无序列表项 3

  ```plaintext
  嵌套在列表项 3 内部的代码块
  ```

- 无序列表项 4

  ![嵌套在列表项 4 下方的图像。](image.png)

对于有序列表，每级缩进使用三个空格：

1. 有序列表项 1

   一行嵌套文本，使用 3 个空格与上方的 `O` 对齐。

您可以在其他列表中嵌套列表。

1. 有序列表项一。
1. 有序列表项二。
   - 嵌套的无序列表项一。
   - 嵌套的无序列表项二。
1. 有序列表项三。

- 无序列表项一。
- 无序列表项二。
  1. 嵌套的有序列表项一。
  1. 嵌套的有序列表项二。
- 无序列表项三。

表格

表格应用于以直接的方式描述复杂信息。在许多情况下，无序列表足以描述每个项目都有单个描述的项目列表。但是，如果您有最适合用矩阵描述的数据，则表格是最好的选择。

创建指南

为了使表格易于访问和可扫描，表格不应有任何空白单元格。如果单元格没有其他有意义的值，请考虑输入 N/A 表示“不适用”或 None。

为了让表格更易维护：

  • 如果表格包含 Description 列，尽可能将其设为最右侧列。

  • 添加额外的空格以使列宽一致。例如：

    | 参数 | 默认值 | 要求 |
|------|--------|------|
| `param1` | `true` | A 和 B。 |
| `param2` | `gitlab.com` | 无 |

  • 对于非常宽的表格，跳过最右列中的额外空格。例如：

    | 设置 | 默认值 | 描述 |
|------|--------|------|
| 设置 1 | `1000` | 短描述。 |
| 设置 2 | `2000` | 长描述，如果此列中的每个单元格都对齐，会使表格过宽并添加过多空白。 |
| 设置 3 | `0` | 另一个短描述。 |

  • 表格的标题（第一）行和分隔符（第二）行的长度应相同。不要使用缩短的分隔符行，如 |-|-|-| 或 |--|--|。

  • 如果大表格无法自动格式化，您可以跳过自动格式化，但：

    • 使前两行长度相同。
    • 在 | 字符和单元格内容之间放置空格。例如 | 单元格 1 | 单元格 2 |，而不是 |单元格1|单元格2|。

表格格式化的编辑器扩展

为确保所有 Markdown 文件中的表格格式一致，建议使用 VS Code 的 Markdown Table Formatter 格式化表格。\n要配置此扩展程序遵循上述指南，请启用 Follow header row length 设置。\n要启用该设置：\n\n- 在界面中：\n\n 1. 在 VS Code 菜单中，转到 代码 > 设置 > 设置。\n 1. 搜索 Limit Last Column Length。\n 1. 在 Limit Last Column Length 下拉列表中选择 Follow header row length。\n\n- 在您的 VS Code settings.json 中，添加新行：\n\n json\n {\n "markdown-table-formatter.limitLastColumnLength": "Follow header row length"\n }\n \n\n要使用此扩展程序格式化表格，请选择整个表格，右键单击选择，然后选择 Format Selection With。在 VS Code 命令面板中选择 Markdown Table Formatter。\n\n如果您使用 Sublime Text，请尝试 Markdown Table Formatter 插件，但它没有 Follow header row length 设置。

现有表格的更新

当您在现有表格中添加或编辑行时，某些行可能不再对齐。如果只更改几行，请不要重新对齐整个表格。如果您重新对齐列以适应宽度，diff 将难以阅读，因为整个表格显示为已修改。

Markdown 表格自然会随着时间的推移而失去对齐，但在 docs.gitlab.com 上仍然正确呈现。下次重构页面时，技术写作团队可以重新对齐单元格。

表头

表头应使用句子大小写。例如，Keyword value 或 Project name。

功能表格

在创建功能列表表格时（例如在权限页面上每个角色可用的功能），使用这些短语：

选项 Markdown 显示结果
否 {{< icon name="dash-circle" >}} No dash-circle No
是 {{< icon name="check-circle-filled" >}} Yes check-circle-filled Yes

不要在API文档中使用这些SVG图标。
请遵循API主题模板。

脚注

仅在无法将内容包含在表格本身中时，才在表格下方使用脚注。
例如，必须在以下情况使用脚注：

  • 在多个表格单元格中提供相同的信息。
  • 包含会破坏表格布局的内容。

脚注格式

在表格中，对每个脚注使用HTML上标标签 <sup>。
将该标签放在句子的末尾。句子与标签之间留一个空格。

例如：

| 应用名称 | 描述               |
|:---------|:-------------------|
| 应用A    | 描述文本。<sup>1</sup> |
| 应用B    | 描述文本。<sup>2</sup> |

添加脚注时，不要重新排序表格中现有的标签。

对于表格下方的脚注，使用 **Footnotes**: 后跟有序列表。

例如：

**Footnotes**:  

1. 这是第一个脚注。  
1. 这是第二个脚注。

表格和脚注将呈现如下：

应用名称 描述
应用A 描述文本。1
应用B 描述文本。2

Footnotes:

  1. 这是第一个脚注。
  2. 这是第二个脚注。
五条或更多脚注

如果有五条或更多无法包含在表格本身的脚注，请对列表项使用连续数字。
如果使用连续数字，必须禁用Markdown规则 029：

**Footnotes**:  

<!-- 禁用有序列表规则 https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix -->
<!-- markdownlint-disable MD029 -->

1. 这是第一个脚注。  
2. 这是第二个脚注。  
3. 这是第三个脚注。  
4. 这是第四个脚注。  
5. 这是第五个脚注。  

<!-- markdownlint-enable MD029 -->

链接

链接是帮助读者找到所需信息的重要方式。

但是，大多数内容通过搜索发现，应避免在任何页面上放置过多链接。
过多链接会影响可读性。

  • 不要在同一页面上重复链接。例如，在页面A上，不要多次链接到页面B。
  • 不要在标题中使用链接。包含链接的标题会导致错误。
  • 不要在链接的任何单词之间使用硬换行。
  • 避免单个段落中包含多个链接。
  • 避免单个任务中包含多个链接。
  • 在任何一页上，尽量不使用超过15个指向其他页面的链接。
  • 考虑使用相关主题来减少打断任务流程的链接。
  • 尽量避免锚点链接到同一页面的章节。让用户依赖右侧导航。

内联链接

使用内联链接而非引用链接。内联链接更易解析和编辑。
（Vale 规则：ReferenceLinks.yml）

  • 正确示例：

    欲了解更多信息，请参阅[合并请求](path/to/merge_requests.md)

  • 错误示例：

    欲了解更多信息，请参阅[合并请求][1]。  

[1]: path/to/merge_requests.md

同仓库内的链接

要链接到同一仓库中的其他文档（.md）文件：

  • 使用带相对文件路径的内联链接。例如：[GitLab.com 设置](../user/gitlab_com/_index.md)。
  • 将整个链接放在一行，即使链接很长。（Vale 规则：MultiLineLinks.yml）。

在GitLab仓库中，不要从任何其他目录链接到/development目录。

要链接到文档之外的文件（例如从开发文档链接到特定代码文件）：

  • 使用完整URL。例如：[`app/views/help/show.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/views/help/show.html.haml)
  • 可选。使用带有特定ref的完整URL。例如：[`app/views/help/show.html.haml`](https://gitlab.com/gitlab-org/gitlab/-/blob/6d01aa9f1cfcbdfa88edf9d003bd073f1a6fff1d/app/views/help/show.html.haml)

不同仓库中的链接

若要链接到另一个仓库中的页面，请使用完整的 URL。 例如，要从 GitLab 仓库中的一个页面链接到 Charts 仓库， 可使用类似 [GitLab Charts 文档](https://docs.gitlab.com/charts/) 的 URL。

锚点链接

每个主题标题都有一个锚点链接。例如，标题为 ## 这是一个示例 的主题，其锚点为 #this-is-an-example。

当您更改主题标题文本时，锚点链接也会随之变化。为避免断链：

  • 请勿在主题标题中使用步骤编号。
  • 如有可能，请不要使用未来可能会改变的词汇。

更改链接和标题

当您更改主题标题时，锚点链接会发生变化。如果其他文档页面 或代码文件链接到此锚点，流水线任务可能会失败。

建议在将更改推送到仓库前，先在本地运行链接检查，以防止流水线失败。

链接文本

遵循以下指南编写链接文本。

标准文本

使用符合以下模式的文本：

  • 有关更多信息，请参阅 [链接文本](link.md)。
  • 要 [执行此操作]，请参阅 [链接文本](link.md)。

例如：

  • 有关更多信息，请参阅 [合并请求](link.md)。
  • 要创建审核应用，请参阅 [审核应用](link.md)。

若需扩展此文本，可使用类似 有关此功能的更多信息，请参阅… 的短语。

请勿使用以下结构：

  • 了解关于…的信息
  • 阅读更多…
  • 有关更多信息，请参阅 [合并请求](link.md) 页面。
  • 有关更多信息，请参阅 [合并请求](link.md) 文档。

使用描述性文本而非 here

使用描述性文本作为链接，而不是 “here” 或 “this page” 这类词。 对于主题或页面的名称，请使用小写。 您无需完全匹配主题或页面的名称，只需编辑文本使其具有描述性并符合指南即可。

正确做法：

  • 有关更多信息，请参阅 [合并请求](link.md)。
  • 有关更多信息，请参阅 [角色与权限](link.md)。
  • 有关更多信息，请参阅 [如何配置常见设置](link.md)。

错误做法：

  • 有关更多信息，请参阅 [此页面](link.md)。
  • 有关更多信息，请前往 [此处](link.md)。
  • 有关更多信息，请参阅 [此文档](link.md)。

链接到问题

当链接到问题时，请在链接中包含问题编号。例如：

  • 有关更多信息，请参阅 [问题 12345](link.md)。

请勿使用井号（issue #12345）。

链接到外部文档

如有可能，请避免链接到外部文档。这些链接可能会过时且难以维护。

有时需要添加此类链接。它们或许能澄清故障排除步骤，或帮助避免内容重复。 有时它们会更精确，且会被更积极地维护。

对于您添加的每个外部链接，请权衡客户收益与维护困难。

链接到手册

限制链接到手册。有些链接不可避免，例如许可条款、数据使用与访问策略、 测试协议以及条款和条件。

机密或受限访问链接

请勿直接链接到：

这些链接会对以下对象无效：

  • 权限不足的人员。
  • 自动化链接检查工具。

如果您必须使用其中某个链接：

  • 如果链接指向机密问题或内部手册页面，请注明该问题或页面仅对 GitLab 团队成员可见。
  • 如果链接需要特定角色或权限，请注明相关信息。
  • 将链接放在反引号中，以免导致链接检查失败。

示例：

  • GitLab 团队成员可在以下机密问题中查看更多信息：
`https://gitlab.com/gitlab-org/gitlab/-/issues/<issue_number>`
  • GitLab 团队成员可在以下内部手册页面中查看更多信息：
`https://internal.gitlab.com/handbook/<link>`
  • 拥有项目 Maintainer 角色的用户可以使用流水线编辑器：
`https://gitlab.com/gitlab-org/gitlab/-/ci/editor`

链接到特定代码行

当链接到文件中的特定行时，应链接到提交而非分支。代码行会随时间变化。使用提交链接来指向某一行可确保用户到达你引用的那一行。在项目中查看文件时显示的省略号菜单中的**永久链接（Permalink）**选项，提供了该文件最新提交的链接。

  • 正确：[链接到第3行](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)
  • 错误：[链接到第3行](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3)。

如果该链接表达式因额外提交而改变了行号，你仍可在文件中搜索该查询。在这种情况下，更新文档以确保它链接到文件的最新版本。

导航

在记录如何导航GitLab界面时：

  • 始终先说明位置，再说明操作。
    • 从可见性（Visibility）下拉列表（位置）中选择公开（Public）（操作）。
  • 简洁且具体。例如：
    • 正确：选择保存（Save）。
    • 不正确：选择**保存（Save）**以使更改生效。
  • 如果步骤必须包含原因，应以原因开头。这有助于用户更快扫描。
    • 正确：要查看更改，请在合并请求中选择链接。
    • 不正确：在合并请求中选择链接以查看更改。

菜单名称

在提及GitLab用户界面的主要元素时，使用以下术语：

  • 左侧边栏（Left sidebar）：这是用户界面左侧的导航侧边栏。
    • 请勿使用短语上下文切换器（context switcher）或切换上下文（switch contexts）。相反，尝试通过一组可重复的步骤引导用户到确切位置。
    • 请勿使用短语探索（Explore）菜单或你的工作（Your work）侧边栏。相反，使用左侧边栏。
  • 右侧边栏（Right sidebar）：这是用户界面右侧的导航侧边栏，特定于打开的问题、合并请求或史诗（epic）。

UI元素名称

所有UI元素都应加粗。导航路径中的>不应加粗。

各个UI元素的指南在词汇表中。

如何编写导航任务步骤

为确保一致性，请使用以下示例来编写任务主题中的导航步骤。尽管存在替代步骤（包括默认固定的项目），但仍应使用这些步骤。

打开项目设置：

1. 在左侧边栏上，选择**搜索或前往（Search or go to）**并找到你的项目。
1. 选择**设置（Settings）** > **CI/CD**。
1. 展开**通用流水线（General pipelines）**。

打开组设置：

1. 在左侧边栏上，选择**搜索或前往（Search or go to）**并找到你的组。
1. 选择**设置（Settings）** > **CI/CD**。
1. 展开**通用流水线（General pipelines）**。

打开顶级组的设置：

1. 在左侧边栏上，选择**搜索或前往（Search or go to）**并找到你的组。
   该组必须是顶级的。
1. 选择**设置（Settings）** > **CI/CD**。
1. 展开**通用流水线（General pipelines）**。

打开项目或组设置：

1. 在左侧边栏上，选择**搜索或前往（Search or go to）**并找到你的项目或组。
1. 选择**设置（Settings）** > **CI/CD**。
1. 展开**通用流水线（General pipelines）**。

创建项目：

1. 在左侧边栏顶部，选择**新建（Create new）**（
 plus 
）和**新项目/仓库（New project/repository）**。

创建组：

1. 在左侧边栏顶部，选择**新建（Create new）**（
 plus 
）和**新组（New group）**。

打开管理区（Admin）：

1. 在左侧边栏底部，选择**管理区（Admin）**。
1. 选择**设置（Settings）** > **CI/CD**。

第二步无需重复“在左侧边栏上”。

打开**你的工作（Your work）**菜单项：

1. 在左侧边栏上，选择**搜索或前往（Search or go to）**。
1. 选择**你的工作（Your work）**。

选择头像：

1. 在左侧边栏上，选择你的头像。

在某些下拉列表中保存选择：

1. 进入你的问题页面。
1. 在右侧边栏的**迭代（Iteration）**部分，选择**编辑（Edit）**。
1. 从下拉列表中选择要与该问题关联的迭代。
1. 选择下拉列表外的任何区域。

查看所有项目：

1. 在左侧边栏上，选择**搜索或前往（Search or go to）**。
1. 选择**查看我所有的项目（View all my projects）**。

查看所有组：

1. 在左侧边栏上，选择**搜索或前往（Search or go to）**。
1. 选择**查看我所有的组（View all my groups）**。

可选步骤

如果步骤是可选的，以单词可选。开头。

例如：

1. 可选。输入作业描述。

推荐步骤

如果步骤是推荐的，以单词推荐。开头。

例如：

1. 推荐。输入作业描述。

记录键盘快捷键和命令

当两种选项都存在时，编写UI说明而不是键盘命令。
此准则适用于GitLab和第三方应用程序（如VS Code）。

GitLab的键盘命令在GitLab键盘快捷键中记录。

同时记录多个字段

如果UI文本足够解释某个部分的字段，不要为每个字段包含任务步骤。相反，在一个任务步骤中总结多个字段。

使用短语完成这些字段。

例如：

  1. 在左侧边栏，选择搜索或前往并找到你的项目。
  2. 选择设置 > 仓库。
  3. 展开推送规则。
  4. 完成这些字段。

如果你正在记录多个字段且只有一个字段需要解释，在同一步骤中进行：

  1. 展开推送规则。
  2. 完成这些字段。分支名称必须是正则表达式。

要描述多个字段，使用无序列表项：

  1. 展开通用流水线。
  2. 完成这些字段。
    • 分支名称必须是正则表达式。
    • 用户必须是具有至少Maintainer角色的用户。

插图

GitLab文档使用两种插图类型：

  • 截图：用于展示GitLab用户界面的部分内容。
  • 图表：用于说明流程或实体间的关系。

插图可以帮助读者理解概念、他们在复杂过程中的位置，或如何与应用程序交互。谨慎使用插图，因为：

  • 它们会过时。
  • 本地化难度大且成本高。
  • 屏幕阅读器无法读取。

如果必须在文档中使用插图，应满足：

  • 补充文本，而非替代它。读者不应仅依赖插图获取所需信息。
  • 前面的文本中有介绍性句子。例如：“以下图表说明了产品分析流程：”。
  • 具备可访问性。有关更多信息，请参阅特定于截图和图表的指南。
  • 排除个人身份信息。

截图

如果某些相关信息无法用文字传达，请使用截图显示GitLab用户界面的一部分。

捕获截图

拍摄截图时：

  • 确保截图内容符合GitLab SAFE框架。若需检查，请遵循SAFE流程图。
  • 确保其提供价值。勿使用lorem ipsum文本。尝试模拟功能在实际场景中的使用方式，并使用真实文本。
  • 仅捕获相关UI。勿包含不必要的空白或对说明要点无帮助的UI区域。GitLab的侧边栏可能会变化，因此除非绝对必要，否则勿将其纳入截图。
  • 保持小巧。若无需显示全屏宽度，则不必展示。尽可能缩小浏览器窗口以使元素紧密排列并减少空白。尽量保持截图尺寸最小。
  • 检查图像在页面上的呈现效果。本地预览图像或使用合并请求中的评审应用。确保图像不模糊或过于突兀。
  • 保持一致。协调文档页面上已有截图的风格，确保一致的阅读体验。确保导航主题设置为默认偏好Indigo，语法高亮主题也设置为默认偏好Light。

添加标注

要在截图中强调某个区域，使用箭头。

  • 颜色使用#EE2604。若在macOS上使用Preview应用，这是默认红色。
  • 线宽使用3 pt。若在macOS上使用Preview应用，这是列表中的第三条线。
  • 使用如下图像所示的箭头样式。
  • 若有多个箭头，尽量使其平行。

红箭头标注突出显示了GitLab用户界面中的问题和合并请求图标。

图片要求

  • 调整任何过宽或过高的截图。
    • 宽度应不超过1000像素。
    • 高度应不超过500像素。
    • 确保截图在调整大小和压缩后仍清晰。
  • 所有图片必须被压缩至100 KB或更小。
    在许多情况下，无需降低画质即可将图片压缩至25 - 50 KB甚至更小。
  • 以描述图片功能或概念的小写文件名保存图片：
    • 如果图片是GitLab界面的截图，根据以下格式在文件名末尾附加GitLab版本号：image_name_vX_Y.png。例如，从GitLab 11.1的流水线页面截取的截图，有效文件名为pipelines_v11_1.png。
    • 如果你添加的是不包含用户界面部分的插图，需添加对应发布版本的版本号。对于合并请求（MR）添加到11.1里程碑的情况，插图的合法文件名为devops_diagram_v11_1.png。
  • 将图片放在名为img/的单独目录中，该目录位于你正在处理的.md文档所在的同一目录内。
    • 不要链接外部托管的图片。下载副本并将其存储在docs目录下合适的img目录中。
  • 优先考虑使用PNG图像而非JPEG。
  • 使用https://ezgif.com/optimize或类似工具压缩GIF。

另见如何链接和嵌入视频以说明文档。

压缩图片

你应该始终压缩添加到文档中的新图片。一个知名工具是pngquant，它跨平台且开源。通过访问官方网站并按照操作系统说明进行安装。

如果你使用macOS并希望所有截图自动压缩，阅读让截图缩小80%的一个简单技巧。

GitLab有一个Ruby脚本来简化手动流程。在你本地克隆的https://gitlab.com/gitlab-org/gitlab根目录中，在终端运行：

  • 压缩前，如果你想，可检查所有文档PNG图片是否已压缩：

    bin/pngquant lint

  • 使用pngquant压缩所有文档PNG图片：

    bin/pngquant compress

  • 压缩特定文件：

    bin/pngquant compress doc/user/img/award_emoji_select.png doc/user/img/markdown_logo.png

  • 压缩特定目录中的所有PNG文件：

    bin/pngquant compress doc/user/img

动画图片

避免使用动画图片（如动态GIF）。它们可能会分散用户的注意力并造成困扰。

如果你要描述用户界面中的复杂交互并想包含视觉表示来帮助读者理解，可以：

  • 使用静态图片（截图），如有必要，添加标注以突出屏幕上的区域。
  • 创建交互的短视频并链接到它。

向内容中添加图片链接

在文档中包含图片的Markdown代码如下：
![图片描述，用于alt标签](img/document_image_title_vX_Y.png)

替代文本

替代文本提供无障碍体验。
屏幕阅读器使用替代文本来描述图像，若图像无法下载则显示替代文本。

替代文本应描述图像的上下文，而非内容本身。添加与页面或章节主题相关的上下文。想象一下，如果你正在帮助某人阅读和交互页面，而他们看不到图像，你会如何描述它。

正确做法：
![一名跑步者向 Docker API 发送请求。](img/document_image_title_vX_Y.png)

错误做法：
![Runner 和 Docker 架构](img/document_image_title_vX_Y.png)

撰写替代文本时需注意：

  • 编写简短且描述性的替代文本，长度不超过155个字符。屏幕阅读器通常在此字符数后停止读取。
  • 若图像包含复杂信息（如工作流图），请使用简短的替代文本来识别图像，并在正文中包含详细信息。
  • 在字符串末尾使用句号，无论是否为句子。
  • 使用句子大小写，避免全大写。某些屏幕阅读器会将大写字母逐个读出。
  • 不要使用诸如“图像”或“图形”之类的短语。
  • 不要使用关键词串。将关键词包含在正文中以增强上下文。
  • 在主题中介绍图像，而非替代文本。
  • 尽量避免重复已在主题中使用过的文本。
  • 不要使用内联样式，如粗体、斜体或反引号。屏幕阅读器会将 **text** 读作 星号 星号 文本 星号 星号。
  • 当图像未为页面添加任何独特信息时（例如，图像是装饰性的，或在正文或标题中已完全描述），请使用空替代文本标签（alt=""）代替完全不包含该标签。空的 alt 标签告知辅助技术您有意省略了文本，而缺失的 alt 标签则会造成歧义。

自动截图生成器

你可以使用自动截图生成器来截取并压缩截图。

  1. 设置 GitLab 开发套件（GDK）。
  2. 进入克隆的 GitLab 仓库子目录，通常是 gdk/gitlab。
  3. 确保 GDK 数据库已完全迁移：bin/rake db:migrate RAILS_ENV=development。
  4. 安装 pngquant，有关更多信息请参阅工具网站：pngquant
  5. 运行 scripts/docs_screenshots.rb spec/docs_screenshots/<screenshot_generator_name>.rb <里程碑版本>。
  6. 根据脚本中 it 参数定义的 gitlab/doc 位置，确定截图的位置。
  7. 提交新创建的截图。

扩展工具

若要添加额外的截图生成器：

  1. 在 spec/docs_screenshots 目录中，添加一个带有 _docs.rb 扩展名的新文件。

  2. 向文件中添加以下信息：

    require 'spec_helper'

RSpec.describe '<我正在截取截图的内容>', :js do
  include DocsScreenshotHelpers # 辅助程序，启用截图机制

  before do
    page.driver.browser.manage.window.resize_to(1366, 1024) # 页面的长度和宽度
  end

  3. 在每个 it 块中，添加截图保存的路径：

    it '<images/目录路径>'

你可以使用 visit <路径> 截取页面的截图。
为了避免空白截图，请使用 expect 等待内容加载。

单个元素截图

你可以截取单个元素的截图。

  • 向你的截图生成器文件中添加以下内容：

    screenshot_area = find('<元素>') # 查找元素
scroll_to screenshot_area # 滚动到元素
expect(screenshot_area).to have_content '<内容>' # 等待你要捕获的内容
set_crop_data(screenshot_area, <填充值>) # 带填充地捕获元素

使用 spec/docs_screenshots/container_registry_docs.rb 作为指南来创建你自己的脚本。

图表

如果信息仅通过文本难以理解，可使用图表来说明流程或实体间的关系。

若要创建图表，可使用 Mermaid（推荐）或 [Draw.io](https://draw.io）。

Mermaid 是推荐的绘图工具，但不适用于所有场景。例如，复杂的图表需求可能导致布局难以理解。

GUI 绘图工具可帮助作者克服 Mermaid 的复杂性和布局问题。Draw.io 是首选的 GUI 工具，因为在使用编辑器时，图表及其定义均存储在 SVG 文件中，因此可以编辑。Draw.io 也与 GitLab Wiki 集成。

功能 Mermaid Draw.io
所需编辑器 文本编辑器 Draw.io 编辑器
所见即所得编辑 dash-circle 否 check-circle-filled 是
可通过 grep 查找文本内容 check-circle-filled 是 dash-circle 否
外观由谁控制 网站 CSS 图表作者
文件格式 SVG SVG
VS Code 集成（带扩展） check-circle-filled 是（预览和本地编辑） check-circle-filled 是（预览和本地编辑）
动态生成 check-circle-filled 是 dash-circle 否

准则

制作易访问且易维护的图表时，请遵循以下准则：

  • 保持图表简单且聚焦。仅包含必要元素和信息。
  • 使用不同但一致的视觉提示（如形状、颜色和字体）来区分类别：
    • 矩形代表流程或步骤。
    • 菱形代表决策点。
    • 实线表示元素间的直接关系。
    • 虚线表示元素间的间接关系。
    • 箭头表示流程或方向。
    • GitLab Sans 字体。
  • 为图表元素添加清晰的标签和简短描述。
  • 为图表添加标题和简短说明。
  • 对于复杂流程，考虑创建多个简单图表而非一个大型图表。
  • 验证图表在不同设备和屏幕尺寸下显示良好。
  • 请勿包含链接。嵌入在图表中的链接（通过 click 操作 实现）无法通过我们的链接检查工具测试。
  • 当流程变更时，更新图表以保持文档或代码的准确性。

使用 Mermaid 创建图表

若要了解如何使用 Mermaid 语法 创建图表，请参阅 Mermaid 用户指南 以及 Mermaid 网站上的示例。

要在 GitLab 文档中使用 Mermaid 创建图表：

  1. 在 Mermaid Live Editor 中创建图表。

  2. 复制 Code 窗格的内容，并将其粘贴到 Markdown 文件中，包裹在 mermaid 代码块内。更多详情，请参阅 GitLab Flavored Markdown for Mermaid。

  3. 若要为图表添加 GitLab 字体样式，请在 Mermaid 代码块声明与图表类型之间添加以下行：

    %%{init: { "fontFamily": "GitLab Sans" }}%%

  4. 在声明图表类型（如 flowchart 或 sequenceDiagram）的下一行，添加以下行以实现无障碍访问：

    accTitle: 你的图表标题
accDescr: 用一句话描述图表的作用，不要换行。

    确保标题和描述符合 替代文本准则。

例如，此流程图同时包含无障碍访问信息和字体信息：

```mermaid
%%{init: { "fontFamily": "GitLab Sans" }}%%
flowchart TD
    accTitle: 示例图表标题
    accDescr: 对你的图表的描述

    A[从这儿开始] -->|操作| B[下一步]
```

使用 Draw.io 创建图表

可以使用 Draw.io 网页应用或（非官方）VS Code Draw.io Integration 扩展来创建图表。两种工具提供相同的图表编辑体验，但网页应用提供了可编辑的示例图表。

使用网页应用

要通过 Draw.io 网页应用创建图表：

  1. 在 Draw.io 网页应用中创建图表。遵循 样式指南。
  2. 保存图表：
    1. 在 Draw.io 网页应用中，选择 文件 > 导出为 > SVG。
    2. 勾选 包含我的图表副本：所有页面 复选框，然后选择 导出。使用文件扩展名 drawio.svg 以表示它可以在 Draw.io 中编辑。
  3. 将 SVG 添加到文档作为图片。这些 SVG 使用与其他非 SVG 图片相同的 Markdown 语法。
使用 VS Code 扩展

要通过 VS Code 的 Draw.io Integration 扩展创建图表：

  1. 在将要包含图表的目录中，创建一个以 drawio.svg 为后缀的空文件。

  2. 在 VS Code 中打开该文件，然后创建图表。遵循 样式指南。

  3. 保存文件。

    图表的定义以 Draw.io 兼容的格式存储在 SVG 文件中。

  4. 将 SVG 添加到文档作为图片。这些 SVG 使用与其他非 SVG 图片相同的 Markdown 语法。

样式指南

在 Draw.io 中创建图表时，其视觉风格应与使用 Mermaid 创建的图表一致。以下规则是对通用 样式指南 的补充。

字体：

  • 所有文本使用 Inter 字体。此字体未包含在默认字体中。若要将 Inter 字体添加为自定义字体：
    1. 从字体下拉列表中选择 自定义。
    2. 选择 Google 字体，并在 字体名称 文本框中输入 Inter。

形状：

  • 对于元素，使用矩形形状。
  • 对于流程图，使用 流程图 形状集合中的形状。
  • 表示相同元素的形状应具有相同的形状和大小。
  • 对于带有文本的元素，确保文本与形状轮廓之间有足够的空白。如果需要，增大形状的尺寸以及图中所有相似形状的尺寸。

颜色：

Emoji

不要为任何目的使用 Markdown 表情符号格式，例如 :smile:。请改用 GitLab SVG 图标。

GitLab SVG 图标

你可以直接在文档中使用来自 GitLab SVG 库 的图标。例如，{{< icon name="tanuki" >}} 渲染结果如下： tanuki 。

大多数情况下，避免在文本中使用图标。但是，当悬停文本是描述 UI 元素的唯一可用方式时，请使用图标。例如，删除 或 编辑 按钮通常只有悬停文本。

当你确实使用图标时，先写悬停文本，再跟上 SVG 引用（括号内）。

  • 避免：选择 {{< icon name="pencil" >}} **编辑**。 这会生成：选择 pencil 编辑。
  • 应改为：选择 **编辑** ({{< icon name="pencil" >}})。 这会生成：选择 编辑 ( pencil )。

不要用文字描述图标：

  • 避免：选择 **清除作业日志** (垃圾桶图标)。
  • 应改为：选择 **清除作业日志** ({{< icon name="remove" >}})。 这会生成：选择 清除作业日志 ( remove )。

当按钮没有任何悬停文本时，描述图标。随后创建一个 UX 问题单，为按钮添加悬停文本以提高可访问性。

  • 避免：选择 {{< icon name="ellipsis_v" >}}。
  • 应改为：选择垂直省略号 ({{< icon name="ellipsis_v" >}})。 这会生成：选择垂直省略号 ( ellipsis_v )。

视频

强烈建议在文档中添加 GitLab YouTube 视频教程，除非视频已过时。视频不应替代文档，而应补充或说明文档。如果视频中关于功能及其关键用例的内容对文档覆盖不足，你应该：

  • 将此细节添加到文档文本中。
  • 创建问题以审查视频并更新页面。

不要将视频上传到产品仓库。添加链接 或 嵌入视频 即可。

链接到视频

要链接到视频，请包含一个YouTube图标，这样读者可以在阅读前扫描页面上的视频。在链接后附上视频发布日期，帮助识别可能过时的视频。

<i class="fa-youtube-play" aria-hidden="true"></i>
概览请见[视频标题](https://link-to-video)。
<!-- 视频发布于YYYY-MM-DD -->

你可以链接任何对GitLab用户有用的最新视频。

嵌入视频

GitLab文档站点支持嵌入式视频。

你只能从GitLab的官方YouTube账号嵌入视频。对于其他来源的视频，请改为链接它们。

在大多数情况下，链接到视频，因为嵌入式视频会占用页面上大量空间，可能分散读者的注意力。

要嵌入视频：

  1. 复制此过程中的代码并粘贴到你的Markdown文件中。在其上下各留一行空白。不要编辑代码（不要删除或添加空格）。
  2. 在YouTube中访问你要显示的视频URL。从浏览器复制常规URL（https://www.youtube.com/watch?v=VIDEO-ID），替换<div class="video-fallback">下方行中的视频标题和链接。
  3. 在YouTube中选择分享，然后选择嵌入。
  4. 仅复制<iframe>源（src）URL（https://www.youtube-nocookie.com/embed/VIDEO-ID），粘贴它以替换iframe标签中src字段的内容。
  5. 在链接下方附上视频发布日期，帮助识别可能过时的视频。
在此处留一行空白
<div class="video-fallback">
  查看视频：<a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">视频标题</a>。
</div>
<figure class="video-container">
  <iframe src="https://www.youtube-nocookie.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen></iframe>
</figure>
<!-- 视频发布于YYYY-MM-DD -->
在此处留一行空白

这在GitLab文档站点上的呈现效果如下：

查看视频：什么是GitLab。

采用这种格式时：

  • figure标签用于语义化SEO，video-container类确保视频响应式并在不同移动设备上显示。
  • <div class="video-fallback">是必要的回退方案（针对/help），因为GitLab Markdown处理器不支持iframe。它在文档站点上隐藏，但在/help中显示。
  • www.youtube-nocookie.com域名启用了YouTube嵌入式播放器的隐私增强模式。该模式允许限制cookie偏好的用户查看嵌入式视频。

链接到点击演示

链接到点击演示应遵循与视频类似的指南。

对于点击演示，请见[演示标题](https://link-to-demo)。
<!-- 演示发布于YYYY-MM-DD -->

警告框

使用警告框来引起对信息的关注。谨慎使用，且切勿让一个警告框紧接另一个警告框。

警告框通过Hugo短代码生成：

{{< alert type="note" >}}

这是需要注意的事项。

{{< /alert >}}

有效的警告类型有flag、note、warning和disclaimer。

警告框仅在GitLab文档站点（https://docs.gitlab.com）上呈现。在GitLab产品帮助中，警告框显示为纯文本。

标志

使用此警告类型描述功能的可用性。有关如何格式化flag警告的信息，请参阅记录部署在功能开关后的功能。

注意

谨慎使用注意框。过多注意框会使主题难以扫描。

与其添加注意框：

  • 将句子重写为段落的一部分。
  • 把信息放入单独的段落。
  • 在新主题标题下放置内容。

如果必须使用注意框，请使用以下格式：

{{< alert type="note" >}}

这是需要注意的事项。

{{< /alert >}}

它在GitLab文档站点上的呈现效果如下：

这是需要注意的事项。

警告

使用警告表示已弃用的功能，或提供可能导致数据丢失的操作警告。

{{< alert type="warning" >}}

这是需要警惕的事项。

{{< /alert >}}

它在GitLab文档站点上的呈现效果如下：

这是需要警惕的事项。

免责声明

若你必须撰写关于我们尚未交付的功能的内容，请在适用内容附近添加关于前瞻性陈述的免责声明。

免责声明通过使用模板生成，不应包含其他文本。

添加如下免责声明：

{{< alert type="disclaimer" />}}

它在 GitLab 文档网站上呈现为：

This page contains information related to upcoming products, features, and functionality. It is important to note that the information presented is for informational purposes only. Please do not rely on this information for purchasing or planning purposes. The development, release, and timing of any products, features, or functionality may be subject to change or delay and remain at the sole discretion of GitLab Inc.

若页面所有内容均不可用，请在页面顶部使用一次关于前瞻性陈述的免责声明。

若某主题内容未准备就绪，请在该主题中使用免责声明。

有关更多信息，请参阅未来版本的承诺功能。

引用块

在产品文档中避免使用引用块。它们会让文本难以扫描。替代方案包括：

GitLab 风格 Markdown (GLFM) 页面是少数使用引用块区分纯文本与渲染示例的案例。但在多数情况下，应避免使用。

标签页

在文档网站上，可将文本格式化为标签页展示。

勿在标签页内放入版本历史项目符号、主题标题、HTML 或标签页自身。仅使用段落、列表、警告框和代码块。其他样式可能无法正常渲染。若有疑虑，保持简单。

要创建一组标签页，可参考此示例：

{{< tabs >}}

{{< tab title="标签页一" >}}

这是标签页一的内容。

{{< /tab >}}

{{< tab title="标签页二" >}}

这是标签页二的其他内容。

{{< /tab >}}

{{< /tabs >}}

此代码在 GitLab 文档网站上呈现为：

这是标签页一的内容。

这是标签页二的其他内容。

标签页标题需简短且一致，确保平行且以大写字母开头。例如：

  • Linux 包（Omnibus）、Helm 图表（Kubernetes）（记录配置编辑时，遵循配置编辑指南）
  • 15.1 及更早版本、15.2 及后续版本

在我们实现针对标签页断链的自动化测试前，勿直接链接至单个标签页。有关更多信息，请参阅问题 225。

有关标签页的更多细节，请参阅Pajamas。

卡片

使用卡片创建含子页面链接的着陆页。

要创建一组卡片，可参考此示例：

{{< cards >}}

- [第一个页面](first_page.md)
- [另一个页面](another/page.md)
- [再一个页面](one_more.md)

{{< /cards >}}

卡片仅在 GitLab 文档网站（https://docs.gitlab.com）上呈现。在 GitLab 产品帮助中，一组卡片会显示为链接的无序列表。

卡片的描述取自 Markdown 页面标头的 description 元数据。

在顶级页面上使用卡片，此时卡片是页面的唯一内容。

维护版本

使用维护版本短代码创建由维护政策指定的当前受支持的 GitLab 版本的无序列表：

{{< maintained-versions >}}

维护版本仅在 GitLab 文档网站的预发布版（https://docs.gitlab.com）上呈现。在其他场景及 /help 中，会显示指向文档网站的链接。

抄袭

勿从其他来源复制粘贴内容，除非是有限引用且注明了来源。通常，用自己的话重新表述相关信息或链接至其他来源会更佳。

未来版本的承诺功能

勿承诺在未来版本中交付功能。例如，避免使用“此功能的支持已计划”这类表述。

我们无法保证未来的功能工作，此类承诺可能引发法律问题。相反，应表明存在问题。例如：

  • 改进的支持已在 [问题 <issue_number>](https://link-to-issue) 中提出。
  • 你无法执行此操作，但 [issue 12345](https://link-to-issue) 建议改变该行为。

你可表示我们计划移除某项功能。

若必须记录未来功能，请使用免责声明。

产品与功能

在 GitLab 产品文档中描述产品和功能时，请参考本节信息。

避免名称中的换行

如果功能或产品名称包含空格，不要用换行符分割名称。 当名称更改时，搜索或grep带有换行的文本会更复杂。

产品可用性详情

产品可用性详情提供有关功能的信息，并显示在主题标题下方。

阅读更多关于 产品可用性详情。

特定章节

某些样式应应用于特定章节。本节概述了特定章节的样式。

帮助与反馈部分

该部分显示在每个文档末尾，可通过在前置元数据中添加键值来省略：

---
feedback: false
---

默认情况下会保留此部分。若要从文档中省略它，必须先咨询技术作家。

GitLab 重启

当需要重启或重新配置 GitLab 时，通过链接到 doc/administration/restart_gitlab.md 避免重复，并根据需要将 “reconfigure” 替换为 “restart”，示例如下：

保存文件并 [重新配置 GitLab](../../../administration/restart_gitlab.md)，使更改生效。

如果文档位于 doc/ 目录之外，请使用完整路径而非相对链接：
https://docs.gitlab.com/administration/restart_gitlab。

如何记录不同的安装方法

GitLab 支持五种官方安装方法。若在句子和标题中使用这些词，请使用以下短语：

  • Linux 包
  • Helm 图表
  • GitLab Operator
  • Docker
  • 自编译

当 使用标签页 时，可添加解释性括号：

  • Linux 包（Omnibus）
  • Helm 图表（Kubernetes）
  • GitLab Operator（Kubernetes）
  • Docker
  • 自编译（源码）

使用标签页描述 GitLab 自托管配置流程

配置流程可能需要用户编辑配置文件、重新配置 GitLab 或重启 GitLab。在这种情况下：

  • 使用 tabs 区分不同的安装方法。
  • 使用与之前列表中完全相同的安装方法名称。
  • 按照以下顺序使用它们。
  • 将代码块缩进以与所属的列表项对齐。
  • 为每个代码块使用适当的语法高亮（ruby、shell 或 yaml）。
  • 对于 YAML 文件，始终包含父级设置。
  • 重新配置或重启 GitLab 的最后一步可以原样使用，因为每次都是一样的。

在描述配置编辑时，使用此片段并根据需要进行编辑：

{{< tabs >}}

{{< tab title="Linux 包 (Omnibus)" >}}

1. 编辑 `/etc/gitlab/gitlab.rb`：

   ```ruby
   external_url "https://gitlab.example.com"

  1. 保存文件并重新配置 GitLab：

    sudo gitlab-ctl reconfigure

{{< /tab >}}

{{< tab title=“Helm 图表 (Kubernetes)” >}}

  1. 导出 Helm 值：

    helm get values gitlab > gitlab_values.yaml

  2. 编辑 gitlab_values.yaml：

    global:
  hosts:
    gitlab:
      name: gitlab.example.com

  3. 保存文件并应用新值：

    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

{{< /tab >}}

{{< tab title=“Docker” >}}

  1. 编辑 docker-compose.yml：

    version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url "https://gitlab.example.com"

  2. 保存文件并重启 GitLab：

    docker compose up -d

{{< /tab >}}

{{< tab title=“自编译 (源码)” >}}

  1. 编辑 /home/git/gitlab/config/gitlab.yml：

    production: &base
  gitlab:
    host: "gitlab.example.com"

  2. 保存文件并重启 GitLab：

    # 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart

{{< /tab >}}

{{< /tabs >}}


它呈现为：



  



  
  
  

    
    
    
    
    
    

  1. 

    编辑 /etc/gitlab/gitlab.rb：
    


    
  
    external_url "https://gitlab.example.com"
    

    2. 

  2. 

    保存文件并重新配置 GitLab：
    


    
  
    sudo gitlab-ctl reconfigure
    

    3. 



  







  
  
  

    
    
    
    
    
    

  1. 

    导出 Helm 值：
    


    
  
    helm get values gitlab > gitlab_values.yaml
    

    2. 

  2. 

    编辑 gitlab_values.yaml：
    


    
  
    global:
  hosts:
    gitlab:
      name: gitlab.example.com
    

    3. 

  3. 

    保存文件并应用新值：
    


    
  
    helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
    

    4. 



  







  
  
  

    
    
    
    
    
    

  1. 

    编辑 docker-compose.yml：
    


    
  
    version: "3.6"
services:
  gitlab:
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url "https://gitlab.example.com"
    

    2. 

  2. 

    保存文件并重启 GitLab：
    


    
  
    docker compose up -d
    

    3. 



  







  
  
  

    
    
    
    
    
    

  1. 

    编辑 /home/git/gitlab/config/gitlab.yml：
    


    
  
    production: &base
  gitlab:
    host: "gitlab.example.com"
    

    2. 

  2. 

    保存文件并重启 GitLab：
    


    
  
    # 对于运行 systemd 的系统
sudo systemctl restart gitlab.target

# 对于运行 SysV init 的系统
sudo service gitlab restart
    

    3.