极狐 GitLab

文档风格指南

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

极狐GitLab 声音#

极狐GitLab 品牌指南定义了整个组织使用的声音。

在此基础上，极狐GitLab 文档中的声音力求简洁、直接、准确。目标是提供易于搜索和浏览的信息。

文档中的声音应该对话式但简短，友好但精炼。

文档是唯一真实来源 (SSoT)#

极狐GitLab 文档是所有与实施、使用和故障排除相关的产品信息的 SSoT。文档不断演进，会随着新产品和功能以及清晰度、准确性和完整性的改进而更新。

此策略：

  • 防止信息孤岛，使查找极狐GitLab 产品信息更加容易。
  • 并不意味着内容不能在文档的多个位置重复出现。

主题类型#

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

主题类型帮助用户更快地消化信息。它们还有助于解决以下问题：

  • 内容难以查找。 极狐GitLab 文档全面且包含大量有用信息。主题类型创建可重复的模式，使内容更易于浏览和解析。
  • 内容通常从贡献者的角度编写。 极狐GitLab 文档由各种贡献者编写。主题类型（特别是任务）有助于将信息整理成旨在帮助他人的格式，而不是记录功能的实现方式。

文档优先方法论#

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

  • 如果问题的答案存在于文档中，请分享文档链接，而不是重新表述信息。
  • 当你遇到极狐GitLab 文档中没有的信息时，创建一个合并请求 (MR) 将信息添加到文档中。然后分享该 MR 以传达信息。

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

为本地化而写作#

我们遵循有助于为全球受众写作的指南。

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

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

以下规则有助于更高效地翻译文档。

避免：

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

使用：

此外，请牢记以下指南：

  • 与功能名称及其交互方式保持一致。
  • 拆分名词字符串。例如，使用 项目集成的自定义设置 代替 项目集成自定义设置。
  • 为国际受众统一
  • 使用 HTML <kbd> 标签。
  • 组合键中的 <kbd> 标签之间不要加空格。
  • 拼写出按键的全名，但 Alt 除外（Vale 规则：SubstitutionWarning.yml）。
  • 如果是操作键，按键的首字母大写。例如，Shift、Command、Delete。
  • 如果是字母键，使用大写。
  • 使用 ↑、↓、← 和 → 表示箭头键。

例如：

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

此示例渲染效果为：

要停止命令，请按 Control+C。

斜体和强调#

在产品文档中避免使用斜体表示强调。 相反，应编写足够清晰的内容，无需强调。极狐GitLab 和 https://docs.gitlab.com 使用无衬线字体，但斜体文本在无衬线页面中并不突出。

列表#

使用列表以更易于浏览的格式呈现信息。

  • 使列表中的所有项保持平行结构。 例如，不要有些项以名词开头，有些以动词开头。

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

  • 所有项使用相同的标点符号。

  • 如果项不是一个完整的句子，不要使用句号。

  • 在每个完整的句子后使用句号，或者当列表项与引导短语结合构成完整句子时使用句号。 不要使用分号或逗号。

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

    markdown
    篮子里装有这些水果：

- 香蕉
- 苹果

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

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

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

  • 避免使用列表项来完成引导短语。这种格式可能难以本地化 为使用不同句子结构的语言。 例如，使用：

    markdown
    您可以通过以下方式获取许可证密钥：

- 从电子邮件中复制许可证密钥。
- 下载文件。

    而不是：

    markdown
    您可以通过以下方式获取许可证密钥：

- 从电子邮件中复制。
- 下载文件。

在有序列表和无序列表之间选择#

对于一系列步骤，使用有序列表。例如：

markdown
按照以下步骤执行操作。

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

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

markdown
以下内容被导入：

- 内容 1
- 内容 2
- 内容 3

列表标记#

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

列表项中的嵌套#

以下内容可以嵌套在列表项下，这样它们会以与列表项相同的 缩进渲染：

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

markdown
1- 无序列表项 1
2
3  使用 2 个空格缩进的一行，与上面的 `U` 对齐。
4
5- 无序列表项 2
6
7  > 一个将嵌套在列表项 2 内的引用块。
8
9- 无序列表项 3
10
11  ```plaintext
12  一个嵌套在列表项 3 内的代码块
13  ```
14
15- 无序列表项 4
16
17  ![嵌套在列表项 4 下的图像。](image.png)

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

markdown
1. 有序列表项 1

   使用 3 个空格缩进的一行，与上面的 `O` 对齐。

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

markdown
11. 有序列表项一。
21. 有序列表项二。
3   - 嵌套的无序列表项一。
4   - 嵌套的无序列表项二。
51. 有序列表项三。
6
7- 无序列表项一。
8- 无序列表项二。
9  1. 嵌套的有序列表项一。
10  1. 嵌套的有序列表项二。
11- 无序列表项三。

指南#

使用指南短代码创建样式化的有序步骤列表。 您可以在指南中嵌套其他短代码（如警告）。 但是，请谨慎使用，因为渲染样式可能会使内容难以浏览。

不要在指南中使用指南。

要创建指南，请遵循以下示例：

markdown
1{{</* guide */>}}
2
31. 带文本的指南项。
4
5   仅包含文本的项。
61. 带警告的指南项。
7
8   这是一个包含警告的项。
9
10   > [!note]
11   > 这是一个注意。
12
13{{</* /guide */>}}

此代码在极狐GitLab 文档站点上渲染为：

{{< guide >}}

  1. 带文本的指南项。

    仅包含文本的项。

  2. 带警告的指南项。

    这是一个包含警告的项。

    这是一个注意。

{{< /guide >}}

指南样式仅在极狐GitLab 文档站点（https://docs.gitlab.com）上渲染。 在极狐GitLab 产品帮助中，指南显示为常规的有序列表项。

指南仅用于教程。对于大多数任务，请使用有序列表。

表格#

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

创建指南#

为了保持表格的可访问性和可浏览性，表格不应有任何 空单元格。如果某个单元格没有其他有意义的值，请考虑输入 N/A 表示“不适用”或 None。

为了使表格更易于维护：

  • 如果表格有 Description 列，如果可能，请将其放在最右侧。

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

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

  • 对于非常宽的表格，可以省略最右侧列中的额外空格。 例如：

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

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

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

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

大表格的选项#

您可以使用 Hugo 类属性 使表格紧凑或可展开。 为了避免在表格中引入 lint 错误，请在启用所有规则的情况下在本地测试表格。

Hugo 类属性仅在极狐GitLab 文档站点（https://docs.gitlab.com）上渲染。

紧凑表格#

紧凑表格在必要时可垂直和水平滚动，并且高度受限。 默认情况下，页面中放不下的宽表格会自动紧凑。长表格不会自动紧凑。您可以选择添加 condensed 类属性来减少表格在页面上占用的空间。

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

或

markdown
1
2| 参数      | 默认值        | 要求          |
3|-----------|--------------|--------------|
4| `param1`  | `true`       | A 和 B。      |
5| `param2`  | `gitlab.com` | 无            |
6{class="condensed"}

可展开表格#

可展开表格有一个 展开表格 按钮，选中后会在对话框中打开表格。 要创建可展开表格，请使用 expandable 类属性。

要使表格同时紧凑和可展开，请同时使用这两个属性。例如：

markdown
{.condensed .expandable}

或：

markdown
{class="condensed expandable"}

用于表格格式化的编辑器扩展#

为了确保所有 Markdown 文件中的表格格式一致，请考虑使用 VS Code Markdown Table Formatter 格式化您的表格。 要配置此扩展以遵循上述指南，请开启 Follow header row length 设置。 要开启此设置：

  • 在 UI 中：

    1. 在 VS Code 菜单中，转到 Code > Settings > Settings。
    2. 搜索 Limit Last Column Length。
    3. 在 Limit Last Column Length 下拉列表中，选择 Follow header row length。

  • 在您的 VS Code settings.json 中，添加一行：

    json
    {
  "markdown-table-formatter.limitLastColumnLength": "Follow header row length"
}

要使用此扩展格式化表格，请选中整个表格，右键单击所选内容， 然后选择 Format Selection With。在 VS Code 命令面板中选择 Markdown Table Formatter。

如果您使用 Sublime Text，可以尝试 Markdown Table Formatter 插件，但它没有 Follow header row length 设置。

对现有表格的更新#

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

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

表格标题#

表格标题使用句子大小写。例如，Keyword value 或 Project name。

功能表格#

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

选项Markdown渲染效果备注
否{{</* no */>}}为屏幕阅读器渲染一个隐藏的 span：<span class="gl-sr-only">no</span>
是{{</* yes */>}}渲染一个可见的勾选图标和一个为屏幕阅读器隐藏的 span：<span class="gl-sr-only">yes</span>

不要在 API 文档或内联文本中使用这些短代码。对于 API 文档，请遵循 API 主题模板。

脚注#

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

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

脚注格式#

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

例如：

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

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

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

例如：

markdown
**脚注**：

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

表格和脚注将渲染如下：

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

脚注：

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

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

markdown
1**脚注**：
2
3<!-- 禁用有序列表规则 https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md029---ordered-list-item-prefix -->
4<!-- markdownlint-disable MD029 -->
5
61. 这是第一个脚注。
72. 这是第二个脚注。
83. 这是第三个脚注。
94. 这是第四个脚注。
105. 这是第五个脚注。
11
12<!-- markdownlint-enable MD029 -->

链接#

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

然而，大多数内容是通过搜索找到的，您应避免在任何页面上放置过多链接。 过多的链接会妨碍可读性。

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

内联链接#

使用内联链接而不是参考链接。内联链接更易于解析 和编辑。 （Vale 规则：ReferenceLinks.yml）

  • 应该：

    markdown
    更多信息，请参见[合并请求](path/to/merge_requests.md)

  • 不应该：

    markdown
    更多信息，请参见[合并请求][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)
  • 可选。使用带有特定引用的完整 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。

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

  • 不要在主题标题中使用步骤编号。
  • 尽可能不要使用将来可能更改的词语。

更改链接和标题#

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

请考虑在推送更改之前在本地运行链接检查 以防止流水线失败。

链接文本#

请遵循以下链接文本指南。

有关在 UI 中编写链接文本的信息，请参见 Pajamas。

标准文本#

使用遵循以下模式之一的文本：

  • 更多信息，请参见[链接文本](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）。

指向 API 的链接#

链接到 API 文档时，使用小写。例如：

  • 要导入您的 GitHub 仓库，请参见[导入 API](link.md)。

不要将首字母大写以匹配页面标题。例如，不要使用：

  • 要导入您的 GitHub 仓库，请参见[Import API](link.md)。

指向外部文档的链接#

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

有时链接是必需的。它们可能有助于澄清故障排除步骤或帮助避免内容重复。 有时它们更精确，并且会更积极地得到维护。

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

指向手册的链接#

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

机密或受限访问链接#

不要直接链接到：

这些链接对于以下人员会失败：

  • 没有足够权限的人。
  • 自动链接检查器。

如果您必须使用这些链接之一：

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

示例：

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

链接到特定代码行#

当链接到文件中的特定行时，请链接到提交而不是 分支。代码行会随时间变化。通过使用 提交链接链接到行，可以确保用户到达您所指的行。在查看项目中的文件时， 省略号菜单中的 永久链接 下拉项提供了指向该文件最新提交的链接。

  • 应该：[链接到第 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 UI 时：

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

UI 元素的名称#

在极狐GitLab UI 中，使用以下名称：

典型极狐GitLab 应用程序页面构成的线框图。

  1. 顶栏
  2. 左侧边栏：用户界面左侧的导航边栏。
    • 不要使用短语 **探索** 菜单 或 **您的工作** 边栏。而是使用 左侧边栏。
  3. ... 面板：基于主要上下文。例如，如果上下文是合并请求，则将其称为 合并请求面板。
  4. 详情面板：支持主要上下文。特定于所选议题或史诗。
  5. 极狐GitLab Duo 面板
  6. 极狐GitLab Duo 侧边栏

右侧边栏 是用户界面右侧的导航边栏， 特定于打开的议题、合并请求或史诗。

除 极狐GitLab Duo 外，以上所有术语均使用小写。

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

有关各个 UI 元素的额外指南，请参见词汇表。

如何编写导航任务步骤#

为了保持一致性，请使用这些示例在任务主题中编写导航步骤。 尽管可能存在替代步骤，包括默认固定的项目， 请改用这些步骤。

要打开项目设置：

markdown
1. 在顶栏中，选择 **搜索或跳转到** 并找到您的项目。
1. 在左侧边栏中，选择 **设置** > **CI/CD**。
1. 展开 **通用流水线**。

要打开群组设置：

markdown
1. 在顶栏中，选择 **搜索或跳转到** 并找到您的群组。
1. 在左侧边栏中，选择 **设置** > **CI/CD**。
1. 展开 **通用流水线**。

要打开顶级群组的设置：

markdown
1. 在顶栏中，选择 **搜索或跳转到** 并找到您的群组。
   该群组必须位于顶级。
1. 在左侧边栏中，选择 **设置** > **CI/CD**。
1. 展开 **通用流水线**。

要打开项目或群组设置：

markdown
1. 在顶栏中，选择 **搜索或跳转到** 并找到您的项目或群组。
1. 在左侧边栏中，选择 **设置** > **CI/CD**。
1. 展开 **通用流水线**。

要创建项目：

markdown
1. 在右上角，选择 **新建** (<span class="gitlab-icon gitlab-icon-plus"></span>) 和 **新建项目/仓库**。

要创建群组：

markdown
1. 在右上角，选择 **新建** (<span class="gitlab-icon gitlab-icon-plus"></span>) 和 **新建群组**。

要打开 管理员 区域：

markdown
1. 在右上角，选择 **管理员**。
1. 在左侧边栏中，选择 **设置** > **CI/CD**。

要打开 您的工作 菜单项：

markdown
1. 在顶栏中，选择 **搜索或跳转到**。
1. 选择 **您的工作**。

要选择您的头像：

markdown
1. 在右上角，选择您的头像。

要在某些下拉列表中保存所选内容：

markdown
1. 进入你的议题。
1. 在右侧边栏的 **迭代** 部分，选择 **编辑**。
1. 从下拉列表中，选择要与此议题关联的迭代。
1. 选择下拉列表外的任意区域。

要查看你的所有项目：

markdown
1. 在顶部栏中，选择 **搜索或跳转到**。
1. 选择 **查看我的所有项目**。

要查看你的所有群组：

markdown
1. 在顶部栏中，选择 **搜索或跳转到**。
1. 选择 **查看我的所有群组**。

可选步骤#

如果某个步骤是可选的，请以 Optional 后跟句号开头。

例如：

markdown
1. Optional。输入作业的描述。

推荐步骤#

如果某个步骤是推荐的，请以 Recommended 后跟句号开头。

例如：

markdown
1. Recommended。输入作业的描述。

记录键盘快捷键和命令#

当两种选项都存在时，请编写 UI 指令而非键盘命令。 此准则适用于极狐GitLab 和第三方应用程序，比如 VS Code。

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

一次记录多个字段#

如果 UI 文本已充分解释了某个部分中的字段，不要为每个字段都添加任务步骤。 相反，在单个任务步骤中总结多个字段。

请使用短语 填写字段。

例如：

  1. 在顶部栏中，选择 搜索或跳转到 并找到你的项目。
  2. 在左侧边栏，选择 设置 > 代码仓。
  3. 展开 推送规则。
  4. 填写字段。

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

  1. 展开 推送规则。
  2. 填写字段。分支名称 必须是一个正则表达式。

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

  1. 展开 通用流水线。
  2. 填写字段。
    • 分支名称 必须是一个正则表达式。
    • 用户 必须是至少具有 维护者 角色的用户。

图示#

极狐GitLab 文档使用两种图示类型：

  • 截屏，用于展示一部分极狐GitLab 用户界面。
  • 图表，用于说明流程或实体之间的关系。

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

  • 它们会过时。
  • 它们很难且成本高昂地进行本地化。
  • 屏幕阅读器无法读取它们。

如果必须在文档中使用图示，应满足以下要求：

  • 补充文本，而非替代文本。 读者不应仅依赖图示来获取所需信息。
  • 在前置文本中有引导句。 例如，下图说明了产品分析流程：。
  • 是可访问的。有关更多信息，请参阅针对截屏和图表的指南。
  • 排除个人身份信息。

截屏#

在无法通过文本传达某些相关信息时，使用截屏来展示极狐GitLab 用户界面的一部分。

截取屏幕截图#

当你截取屏幕截图时：

  • 确保截图内容符合 极狐GitLab SAFE 框架。要检查，请遵循 SAFE 流程图。
  • 确保它提供价值。 不要使用 lorem ipsum 文本。 尝试模拟功能在真实场景中的使用方式，并 使用逼真的文本。
  • 只捕获相关的 UI。 不要包含不必要的空白 区域或 UI 中无助于说明问题的部分。极狐GitLab 中的 侧边栏可能会变化，因此除非绝对必要，否则不要在截图中包含它们。
  • 保持小尺寸。 如果你不必显示屏幕的整个宽度，就不要显示。 尽可能缩小浏览器窗口大小，使元素聚拢并减少空白空间。尽量保持截图尺寸尽可能小。
  • 检查图片在页面上的渲染效果。 在本地预览图片，或在合并请求中使用 审查应用。确保图片不模糊或令人不适。
  • 保持一致。 与文档页面已有的其他截图相互协调，以提供一致的阅读体验。确保你的导航主题 设置为默认偏好 Neutral，并且语法高亮主题也设置为默认偏好 Light。

添加标注#

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

  • 颜色使用 #EE2604。如果你在 macOS 上使用预览应用程序，这是默认的红色。
  • 线宽使用 3 pt。如果你在 macOS 上使用预览应用程序，这是列表中的第三条线。
  • 使用下图中所示的箭头样式。
  • 如果有多个箭头，尽可能让它们平行。

红色箭头标注，突出显示所有用户和你的群组的 CI/CD 组件标签页。

图片要求#

  • 调整任何过宽或过高的截屏尺寸。
    • 宽度应不超过 1000 像素。
    • 高度应不超过 500 像素。
    • 确保截图在调整大小和压缩后仍然清晰。
  • 使用 PNG 图片而非 JPEG。
  • 所有图片 必须 压缩 到 100 KB 或以下。 在许多情况下，通常可以在不降低图片质量的情况下达到 25-50 KB 或更小。
  • 使用描述性小写文件名保存图片， 以说明图片中的功能或概念：
    • 如果图片是极狐GitLab 界面的截图，请根据以下格式在文件名后附加极狐GitLab 版本号： image-name-vX_Y.png。例如，对于极狐GitLab 11.1 管道页面的截图，有效名称是 pipelines-v11_1.png。
    • 如果你添加的插图不包含用户界面的任何部分，请添加与图片添加到的版本对应的版本号。 对于添加到 11.1 里程碑的 MR，插图的有效名称是 devops-diagram-v11_1.png。
  • 将图片放置在与正在处理的 .md 文档相同目录下的 独立子目录 img/ 中。
    • 不要链接到外部托管的图片。下载副本并将其存储在适当的 img 目录中，该目录位于 docs 目录内。
  • 使用 https://ezgif.com/optimize 或类似工具压缩 GIF。

另请参阅如何链接和嵌入 视频 来丰富文档说明。

压缩图片#

压缩你添加到文档中的新图片。 这有助于减小文件大小并提高页面加载性能。

你可以使用 pngquant，它是跨平台和 开源的。请访问其官方网站并按照你的操作系统说明进行安装。

你可以自动或手动压缩图片：

要使用 pngquant 脚本，在本地 https://gitlab.com/gitlab-org/gitlab 副本的根目录中， 根据需要运行以下命令：

  • 要检查所有文档 PNG 图片是否已压缩：

    shell
    bin/pngquant lint

  • 要压缩所有文档 PNG 图片：

    shell
    bin/pngquant compress

  • 要压缩特定文件：

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

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

    shell
    bin/pngquant compress doc/user/img
将图片文件转换为 PNG 格式#

如果压缩脚本创建了 .compressed 文件而没有原地压缩， 很可能这些文件扩展名是 PNG，但实际是其他图片格式（如 JPEG）。

png_quantizator gem 在非 PNG 文件上会崩溃，导致脚本无法完成。

前提条件：

  • 安装 GraphicsMagick：

    shell
    # macOS：
brew install graphicsmagick

要将图片文件转换为 PNG 格式：

  1. 检查文件格式：

    shell
    file doc/user/img/problematic_file.png

    file 命令检查文件内容（魔数/头部）而非 扩展名。一个命名错误的 JPEG 文件会显示：

    shell
    doc/user/img/problematic_file.png: JPEG image data, JFIF standard 1.01...

  2. 使用 GraphicsMagick 将文件转换为 PNG 格式：

    shell
    gm convert problematic_file.png corrected_file.png

  3. 再次运行压缩脚本。

如果原始是 JPEG 文件，转换后的 PNG 文件可能看起来更大， 因为 PNG 使用无损压缩，而 JPEG 使用有损压缩。

删除图片#

当你从英文文档中删除对图片的引用时，不要删除图片文件。 本地化文档（例如，日文页面）使用与英文文档相同的图片文件。 即使图片在英文文档中不再被引用，翻译后的页面可能仍在使用它。

文档站点构建过程会检查图片路径。如果你删除了仍被使用的图片， 合并请求流水线中的 hugo_build 作业将会失败。

未被使用的图片会在 月度维护 中进行清理。

动画图片#

避免使用动画图片（如动画 GIF）。它们可能会让用户分心 或感到厌烦。

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

  • 使用静态图片（截图），并在必要时添加标注来强调屏幕的某个区域。
  • 创建一个简短的交互视频并链接到它。

将图片链接添加到内容中#

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

替代文本#

替代文本提供了可访问的体验。 屏幕阅读器使用替代文本来描述图片，并且如果图片下载失败，替代文本会显示。

替代文本应描述图片的上下文，而非内容。添加与页面或章节主题相关的上下文。 设想一下，如果你正在帮助某人阅读和浏览页面，而他们看不见图片时，你会如何描述这张图片。

正确：

![一个 Runner 向 Docker API 发送请求。](img/document_image_title_vX_Y.png)

错误：

![Runner 和 Docker 架构](img/document_image_title_vX_Y.png)

编写替代文本时：

  • 编写简短的、描述性的替代文本，不超过 155 个字符。 屏幕阅读器通常在读取这么多字符后停止。
  • 如果图片包含复杂信息，如工作流程图，使用简短的替代文本 来标识图片，并在文本中提供详细信息。
  • 在字符串末尾使用句号，无论它是否是一个句子。
  • 使用句子式大小写，避免全大写。 某些屏幕阅读器会将大写字母逐个读出。
  • 不要使用诸如 Image of 或 Graphic of 之类的短语。
  • 不要使用一串关键词。 在文本中包含关键词以增强上下文。
  • 在主题中引入图片，而不是在替代文本中。
  • 尽量避免重复主题中已使用的文本。
  • 不要使用内联样式，如粗体、斜体或反引号。 屏幕阅读器会将 **text** 读作 star star text star star。
  • 当图片没有为页面添加任何独特信息时，使用空的 alt 文本标签 (alt="") 而不是完全省略标签。例如，当图片是装饰性的，或者已在正文或标题中充分描述时。空的 alt 标签告诉辅助技术你是有意省略了文本，而缺失的 alt 标签则含义模糊。

自动截屏生成器#

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

  1. 设置 GitLab Development Kit (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/<name_of_screenshot_generator>.rb <milestone-version>。
  6. 根据脚本中 it 参数定义的 gitlab/doc 位置，确定截屏的位置。
  7. 提交新创建的截屏。
扩展该工具#

要添加额外的截屏生成器：

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

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

    ruby
    1require 'spec_helper'
2
3RSpec.describe '<我要截屏的内容>', :js do
4  include DocsScreenshotHelpers # 启用截屏机制辅助方法
5
6  before do
7    page.driver.browser.manage.window.resize_to(1366, 1024) # 页面的长度和宽度
8  end

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

    ruby
    it '<path/to/images/directory>'

你可以使用 visit <path> 截取页面屏幕。 为避免空白截屏，使用 expect 等待内容加载。

单元素截屏#

你可以截取单个元素的屏幕。

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

    ruby
    screenshot_area = find('<element>') # 查找元素
scroll_to screenshot_area # 滚动到该元素
expect(screenshot_area).to have_content '<content>' # 等待你要捕获的内容
set_crop_data(screenshot_area, <padding>) # 捕获添加了边距的元素

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

图表#

如果某个流程或实体间的关系过于复杂，仅凭文本难以理解，请使用图表来说明。

要创建图表，可以使用以下任一工具：

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

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

特性MermaidDraw.io
所需编辑器文本编辑器Draw.io 编辑器
所见即所得编辑 否 是
可通过 grep 查找的文本内容 是 否
外观控制方式网站的 CSS图表的作者
文件格式SVGSVG
VS Code 集成（通过扩展） 是（预览和本地编辑） 是（预览和本地编辑）
动态生成 是 否

图表指南#

要创建可访问且可维护的图表，请遵循以下准则：

  • 保持图表简单且专注。只包含必要的元素和信息。

  • 仅使用形状来区分元素。不要使用颜色来区分元素，因为 图表必须兼容浅色和深色模式。

    推荐的形状有：

    • 矩形用于流程或步骤。
    • 菱形用于决策点。
    • 实线用于元素间的直接关系。
    • 虚线用于元素间的间接关系。
    • 箭头用于流程或过程中的方向。

  • 代表相同元素的形状应具有相同的形状和大小。

  • 为图表元素添加清晰的标签和简短描述。

  • 对于包含文本的元素，确保文本与 形状轮廓之间有足够的空白。如有必要，增加形状的大小，并相应调整图表中 所有 类似形状。

  • 为图表添加标题和简短描述。

  • 文本使用 GitLab Sans 字体，或使用 Google Inter 字体作为备选。

  • 对于复杂流程，考虑创建多个简单图表，而不是一个大图表。

  • 验证图表在不同设备和屏幕尺寸下的显示效果是否良好。

  • 不要包含链接。图表中嵌入的带有 click 动作 的链接无法通过我们的链接检查工具进行测试。

  • 当流程更改时，更新图表以及文档或代码，以保持准确性。

使用 Mermaid 创建图表#

要学习如何使用 Mermaid 语法 创建图表， 请参见 Mermaid 用户指南 和 Mermaid 站点上的示例。

要使用 Mermaid 为极狐GitLab 文档创建图表：

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

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

  3. 在声明图表类型（如 flowchart 或 sequenceDiagram）之后， 添加以下行以确保可访问性：

    yaml
    accTitle: your diagram title here
accDescr: describe what your diagram does in a single sentence, with no line breaks.

    确保标题和描述遵循 替代文本指南。

例如，以下流程图包含可访问性信息：

markdown
1```mermaid
2flowchart TD
3    accTitle: Example diagram title
4    accDescr: A description of your diagram
5
6    A[Start here] -->|action| B[next step]
7```

使用 Draw.io 创建图表#

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

使用 Draw.io 创建的图表必须遵守通用的 图表指南 以及 Draw.io 特定指南。

Draw.io 指南#

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

字体：

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

形状：

  • 对于元素，使用矩形形状。
  • 对于流程图，请使用 Flowchart 形状集合中的形状。
使用 Web 应用程序#

要使用 Draw.io Web 应用程序创建图表：

  1. 在 Draw.io Web 应用程序中，创建图表。
  2. 保存图表：
    1. 在 Draw.io Web 应用程序中，选择 File > Export as > SVG。
    2. 选中 Include a copy of my diagram: All pages 复选框，然后选择 Export。使用 文件扩展名 drawio.svg 表明它可以在 Draw.io 中编辑。
  3. 将 SVG 作为图片添加到文档中。 这些 SVG 使用与其他非 SVG 图片相同的 Markdown。
使用 VS Code 扩展#

要使用 Draw.io Integration 扩展为 VS Code 创建图表：

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

  2. 在 VS Code 中打开该文件，然后创建图表。

  3. 保存文件。

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

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

Emoji#

不要将 Markdown 表情格式（例如 :smile:）用于任何目的。应使用 极狐GitLab SVG 图标。

极狐GitLab SVG 图标#

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

。

在大多数情况下，应避免在文本中使用图标。 然而，当按钮仅通过悬停文字描述时（例如，删除 或 编辑 按钮 通常只有悬停文字），可以使用图标。

当你确实需要使用图标时，应以悬停文字开头，并在其后跟括号中的 SVG 引用。

  • 避免：选择 {{</* icon name="pencil" */>}} **编辑**。 这会渲染为：选择 编辑。
  • 应使用：选择 **编辑** ({{</* icon name="pencil" */>}})。 这会渲染为：选择 编辑 ()。

不要使用词语来描述图标：

  • 避免：选择 **清除作业日志**（垃圾桶图标）。
  • 应使用：选择 **清除作业日志** ({{</* icon name="remove" */>}})。 这会渲染为：选择 清除作业日志 ()。

当按钮没有任何悬停文字时，应描述图标。 然后创建一个 UX bug 议题 为该按钮添加悬停文字以提升可访问性。

  • 避免：选择 {{</* icon name="ellipsis_v" */>}}。
  • 应使用：选择垂直省略号 ({{</* icon name="ellipsis_v" */>}})。 这会渲染为：选择垂直省略号 ()。

视频#

强烈建议在文档中添加极狐GitLab YouTube 视频教程，除非视频已过时。视频不应取代 文档，而应作为补充或说明。如果视频中的内容对于某个功能及其关键用例至关重要， 但在文档中没有充分涵盖，你应该：

  • 将此详细信息添加到文档文本中。
  • 创建一个议题来审查视频并更新页面。

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

链接到视频#

要链接到视频，请包含一个 YouTube 图标，以便读者可以在阅读前浏览页面 以查找视频。对于链接文本，请遵循 关于文本的通用指南。 在链接后注明视频的发布日期，以帮助识别 可能已过时的视频。

markdown
<i class="fa-youtube-play" aria-hidden="true"></i>
有关概述，请参阅 [合并请求](https://link-to-video)。
<!-- 视频发布于 YYYY-MM-DD -->

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

嵌入视频#

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

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

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

要嵌入视频：

text
1## 链接到点击演示 {#link-to-click-through-demos}
2
3链接到点击演示应遵循与[视频](#videos)类似的指南。
4
5```markdown
6有关点击演示，请参阅[演示标题](https://link-to-demo)。
7<!-- 演示发布于 YYYY-MM-DD -->

警告框#

使用警告框来引起对信息的注意。要少用，并且切勿让一个警告框紧跟着另一个警告框。

警告框通过使用 Markdown 警报 生成：

plaintext
> [!注意]
> 此处的文本将显示在警告框内。

有效的警报类型有 功能标志、注意、警告 和 免责声明。这些类型不区分大小写。

功能标志#

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

注意#

要少用注意提示。太多的注意提示会让主题难以浏览。

而不是添加注意提示：

  • 将句子重写为段落的一部分。
  • 将信息放在自己的段落中。
  • 将内容放在新的主题标题下。

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

plaintext
> [!注意]
> 这是需要注意的内容。

在极狐GitLab 文档站点上，它呈现为：

这是需要注意的内容。

警告#

使用警告来表示已弃用的功能，或对可能导致数据丢失的过程发出警告。

plaintext
> [!警告]
> 这是需要被警告的内容。

在极狐GitLab 文档站点上，它呈现为：

这是需要被警告的内容。

免责声明#

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

免责声明警报是通过使用模板来填充的，并且不应包含任何其他文本。

像这样添加免责声明：

plaintext
> [!免责声明]

在极狐GitLab 文档站点上，它会呈现免责声明文本：

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

如果某个主题的内容尚未准备好，请在该主题中使用免责声明。

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

块引用#

避免在产品文档中使用块引用。它们会使文本难以浏览。与其使用块引用，不如考虑使用：

极狐GitLab Flavored Markdown (GLFM) 页面是一个罕见案例，它使用块引用来区分纯文本和渲染示例。然而，在大多数情况下，您应该避免使用它们。

选项卡#

在文档站点上，您可以将文本格式化为选项卡形式。

不要在选项卡中放置版本历史点、主题标题、HTML 或选项卡。只使用段落、列表、警告框和代码块。其他样式可能无法正确渲染。如有疑问，请保持简单。

要创建一组选项卡，请参照以下示例：

plaintext
1{{</* tabs */>}}
2
3{{</* tab title="选项卡一" */>}}
4
5这是选项卡一中的一些内容。
6
7{{</* /tab */>}}
8
9{{</* tab title="选项卡二" */>}}
10
11这是选项卡二中的其他一些内容。
12
13{{</* /tab */>}}
14
15{{</* /tabs */>}}

该代码在极狐GitLab 文档站点上呈现为：

这是选项卡一中的一些内容。

对于选项卡标题，要简洁且保持一致。确保它们彼此对仗，并且每个标题都以大写字母开头。例如：

  • Linux package (Omnibus)、Helm chart (Kubernetes)（在文档化配置编辑时，请遵循配置编辑指南）
  • 15.1 and earlier、15.2 and later

关于选项卡的更多详细信息，请参阅 Pajamas。

可折叠面板#

可折叠面板默认处于关闭状态，并且需要一个标题。在渲染的文档中，您必须展开该面板才能查看其中的内容。

markdown
{{</* collapsible title="可折叠面板示例" */>}}

此内容出现在可折叠面板内。

{{</* /collapsible */>}}

仅在极狐GitLab Duo 页面的可用性详情部分使用可折叠面板，以获取关于支持的大语言模型、编辑器以及自部署模型可用性的信息。

不要将可折叠面板用于其他内容。

卡片#

使用卡片来创建带有指向子页面链接的登陆页面。

要创建一组卡片，请参照以下示例：

markdown
1{{</* cards */>}}
2
3- [第一页](first_page.md)
4- [另一页](another/page.md)
5- [再一页](one_more.md)
6
7{{</* /cards */>}}

此外，卡片支持包含可选描述的外部链接。使用以下语法：

markdown
{{</* cards */>}}

- [外部页面标题](https://example.com "可选描述")

{{</* /cards */>}}

卡片仅在极狐GitLab 文档站点（https://gitlab.cn/docs）上渲染。在极狐GitLab 产品帮助中，一组卡片会显示为无序链接列表。

卡片描述从 Markdown 页面头部的 description 元数据中填充。

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

维护版本#

使用维护版本短代码来创建一个无序列表，列出维护策略中指定的当前受支持的极狐GitLab 版本：

markdown
{{</* maintained-versions */>}}

维护版本仅在极狐GitLab 文档站点的预发布版本（https://gitlab.cn/docs）上渲染。在所有其他情况下以及在 /help 中，将显示指向文档站点的链接。

词汇表工具提示#

使用词汇表工具提示的短代码，提供一个简短的定义，当用户悬停时以工具提示形式显示。例如：

markdown
要执行此操作，请使用 {{</* glossary-tooltip text="该术语" */>}}。

当用户悬停在 {{< glossary-tooltip text="该术语" >}} 上时，将显示一个工具提示。

如果为该工具提示配置了词汇表页面，并且用户选择了锚文本，相关的词汇表页面将打开。

使用指南#

如果定义是一个简洁的句子，并且尽量不超过 60 个字符，请使用词汇表工具提示。对于较长的定义，请使用词汇表页面。

每页使用的工具提示不要超过五到十个。每个工具提示都会减慢读者的阅读速度。注意不要用过多的定义让用户不堪重负。

在以下情况下使用词汇表工具提示：

  • 对于页面上首次出现的极狐GitLab 特定术语。
  • 对于读者可能不了解的术语，如 产物 或 分析器。

在以下情况下不要使用词汇表工具提示：

  • 对于常见术语，如代码仓、分支或提交。
  • 对于术语的每个实例。
  • 作为首字母缩写词的替代。如果可以在首次使用时拼出缩写词，并且它是行业标准，请不要使用词汇表工具提示。

创建词汇表术语#

将词汇表定义添加到 docs-gitlab-com 仓库中的 glossary.yaml 文件。每个定义都应简短，并且不包含链接。

词汇表术语在 terms 块中定义，包含以下字段：

term_id

: 词汇表术语的唯一 ID。要链接到词汇表部分，term_id 必须与该术语在词汇表页面上的锚点匹配。

display_name

: 在文档中显示的文本。display_name 字段不区分大小写。例如，短代码中的 text 参数为 "attack surface" 时，会匹配 glossary.yaml 文件中的术语 "Attack Surface"。

glossary

: 可选。指向该术语词汇表定义的链接。如果包含，term_id 将附加到 glossary_url 的末尾。例如，/user/application_security/terminology#attack-surface。

short_description

: 当用户悬停在工具提示上时显示的文本。

glossary.yaml 文件中的词汇表术语定义示例：

yaml
terms:
  - term_id: attack-surface
    display_name: Attack Surface
    glossary: *security_glossary
    short_description: 应用程序中易受攻击的不同位置

词汇表在 glossary.yaml 文件的顶部进行定义。

第一行包含两个唯一 ID：

  1. 词汇表的简短名称。
  2. 词汇表的较长标识符。对于链接到此词汇表的词汇表术语，其 glossary 字段必须与此值匹配。

glossary_url

: 定义该术语的词汇表页面的根 URL。

glossary.yaml 文件中的词汇表定义示例：

yaml
# 词汇表文件
security: &security_glossary
  glossary_url: "/user/application_security/terminology"

结合这些示例，结果如下：

  • 文档中将 "Attack Surface" 显示为链接。
  • 当用户悬停在该链接上时，short_description 字段的内容会显示在工具提示中。
  • 当用户选择该链接时，词汇表页面将在锚点 attack-surface 处打开。

抄袭#

除非是注明出处的有限引用，否则不要从其他来源复制和粘贴内容。通常，最好是使用自己的话重新表述相关信息或链接到来源。

未来版本中承诺的功能#

不要承诺在未来的版本中提供某些功能。例如，避免使用诸如“此功能计划支持”之类的说法。

我们无法保证未来的功能开发，并且这样的承诺可能会引发法律问题。相反，应说明存在一个议题。例如：

  • 对改进的支持已提议在 [issue <议题编号>](https://link-to-issue) 中。
  • 你无法执行此操作，但 [issue 12345](https://link-to-issue) 提议更改此行为。

你可以说我们计划移除某个功能。

如果你必须记录将来的功能，请使用免责声明。

产品和功能#

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

避免名称中的换行#

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

产品可用性详情#

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

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

特定小节#

特定的小节应应用特定的样式。本节概述了对特定小节的样式要求。

帮助和反馈小节#

此小节显示在每个文档的末尾，可以通过在前面元数据中添加一个键来省略：

yaml
---
feedback: false
---

默认情况下是保留它。如果你想从文档中省略它，你必须先与文档工程师确认。

极狐GitLab 重启#

当需要重启或重新配置极狐GitLab 时，为避免重复，可以链接到 doc/administration/restart_gitlab.md，并使用类似这样的文本，根据需要将 'reconfigure' 替换为 'restart'：

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

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

如何记录不同的安装方法#

极狐GitLab 支持五种官方安装方法。如果你在句子和标题中提及它们，请使用以下短语：

  • Linux package
  • Helm chart
  • GitLab Operator
  • Docker
  • Self-compiled

在使用选项卡时，可以添加解释性的括号：

  • Linux package (Omnibus)
  • Helm chart (Kubernetes)
  • GitLab Operator (Kubernetes)
  • Docker
  • Self-compiled (source)

使用选项卡描述极狐GitLab 私有化部署配置步骤#

配置步骤可能要求用户编辑配置文件、重新配置极狐GitLab 或重启极狐GitLab。在这种情况下：

  • 使用选项卡来区分不同的安装方法。
  • 严格按照前面的列表中的名称使用安装方法。
  • 按照下述顺序使用它们。
  • 缩进代码块，使其与所属的列表项对齐。
  • 为每个代码块使用适当的语法高亮（ruby、shell 或 yaml）。
  • 对于 YAML 文件，始终包含父设置。
  • 重新配置或重启极狐GitLab 的最后一步可以直接使用，因为每次都相同。

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

markdown
1{{</* tabs */>}}
2
3{{</* tab title="Linux package (Omnibus)" */>}}
4
51. 编辑 `/etc/gitlab/gitlab.rb`：
6
7   ```ruby
8   external_url "https://gitlab.example.com"
9   ```
10
111. 保存文件并重新配置极狐GitLab：
12
13   ```shell
14   sudo gitlab-ctl reconfigure
15   ```
16
17{{</* /tab */>}}
18
19{{</* tab title="Helm chart (Kubernetes)" */>}}
20
211. 导出 Helm 值：
22
23   ```shell
24   helm get values gitlab > gitlab_values.yaml
25   ```
26
271. 编辑 `gitlab_values.yaml`：
28
29   ```yaml
30   global:
31     hosts:
32       gitlab:
33         name: gitlab.example.com
34   ```
35
361. 保存文件并应用新值：
37
38   ```shell
39   helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
40   ```
41
42{{</* /tab */>}}
43
44{{</* tab title="Docker" */>}}
45
461. 编辑 `docker-compose.yml`：
47
48   ```yaml
49   version: "3.6"
50   services:
51     gitlab:
52       environment:
53         GITLAB_OMNIBUS_CONFIG: |
54           external_url "https://gitlab.example.com"
55   ```
56
571. 保存文件并重启极狐GitLab：
58
59   ```shell
60   docker compose up -d
61   ```
62
63{{</* /tab */>}}
64
65{{</* tab title="Self-compiled (source)" */>}}
66
671. 编辑 `/home/git/gitlab/config/gitlab.yml`：
68
69   ```yaml
70   production: &base
71     gitlab:
72       host: "gitlab.example.com"
73   ```
74
751. 保存文件并重启极狐GitLab：
76
77   ```shell
78   # 对于运行 systemd 的系统
79   sudo systemctl restart gitlab.target
80
81   # 对于运行 SysV init 的系统
82   sudo service gitlab restart
83   ```
84
85{{</* /tab */>}}
86
87{{</* /tabs */>}}

它渲染为：

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

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

  2. 保存文件并重新配置极狐GitLab：

    shell
    sudo gitlab-ctl reconfigure