Documentation Style Guide

原文：https://docs.gitlab.com/ee/development/documentation/styleguide.html

Documentation Style Guide

本文档定义了 GitLab 文档内容和文件的标准.

有关该文档的更多信息，请参见《 文档指南》 .

有关遵循该准则的编程帮助，请参阅” 测试” .

请参阅 GitLab 手册，以获取适用于所有 GitLab 内容（不仅是文档）的进一步的写作风格指南 .

Documentation is the single source of truth (SSOT)

Why a single source of truth

GitLab 产品和功能的文档是 SSOT，其中包含与实施，使用和故障排除有关的所有信息. 它与新产品和功能保持一致，并不断改进，以提高清晰度，准确性和完整性.

该策略可以防止信息孤岛，从而更轻松地查找有关 GitLab 产品的信息.

它还可以就我们包含在文档中的内容种类提供决策.

All information

只要可以以充分详细的警告和警告的形式提供适当的上下文，就可以包括解决可能很少见或被认为是”危险”的解决问题的措施. 应该包括这类内容，因为它可能对其他人有帮助，并且在正确解释后，其好处大于风险. 如果您认为发现此规则有例外，请与技术写作团队联系.

无论用户遇到何种情况，我们都会将所有故障排除信息添加到文档中. 对于” 疑难解答”部分 ，GitLab 支持人员可以自己合并添加项.

All media types

如果内容与读者相关，则包括任何媒体类型/来源. 您可以自由地包含或链接演示文稿，图表，视频等； 不管它最初是为谁创作的，如果对我们的听众有帮助，我们都可以将其包括在内.

  • 如果使用的图像具有单独的源文件（例如，矢量或图表格式），则将该图像链接到源文件，以便任何人都可以重用或更新它.
  • 除非从引用来源中引用有限的内容，否则请勿复制和粘贴其他来源的内容. 通常，最好用您自己的话语重述相关信息或链接到其他来源.

No special types

在软件行业中，最佳实践是组织不同类型的文档. 例如， Divio 建议 ：

  1. Tutorials
  2. 入门指南
  3. Explanation
  4. 参考（例如，词汇表）

在 GitLab，我们的月度版本中有太多产品更改，以至于我们无法承受持续更新多种类型的信息的负担. 如果我们有多种类型，则信息将过时. 因此，我们只有一个文档模板 .

我们目前不区分特定的文档类型，尽管一旦文档达到成熟度和质量的未来阶段，我们可以重新考虑此政策. 如果您正在阅读此书，那么尽管我们不断进行改进，但仍未达到这一点.

Link instead of summarize

有诱惑力将信息汇总在另一页上. 这将导致信息存在于两个地方. 相反，链接到 SSOT 并解释为什么使用信息很重要.

Organize by topic, not by type

除了顶级受众类型的文件夹（例如， administration ）之外，我们还按主题而不是按类型组织内容，因此可以在主题的单一来源（SSOT）部分中尽可能轻松地找到内容物.

例如，不要创建相似媒体类型的分组. 例如：

  • Glossaries.
  • FAQs.
  • 所有文章或视频的集合.

按类型对内容进行这种分组使得难以浏览所需信息，并且难以维护最新内容. 而是按主题组织内容（例如，与 CI 相关的所有内容都放在一起），并在任何相关内容之间进行交叉链接.

Docs-first methodology

我们采用文档优先的方法，以帮助确保文档保持完整且受信任的资源，并使有关 GitLab 使用的交流更加有效.

  • 如果文档中存在问题的答案，请共享文档链接，而不要改写信息.
  • 当您遇到 GitLab 文档中没有的新信息时（例如，在处理支持案例或测试功能时），第一步应该是创建合并请求（MR），以将该信息添加到文档中. 然后，您可以共享 MR 以便传达此信息.

如上所述，对将来的 GitLab 使用或故障排除有用的新信息不应直接写在论坛或其他消息系统中，而应添加到文档 MR 中，然后再进行引用. 请注意，除其他任何文档更改外，您还可以：

  • 如果不存在，请在文档中添加” 疑难解答”部分 .
  • 取消注释并使用占位符疑难解答部分，该部分包含在我们的文档模板中 （如果存在）.

我们向文档自如地添加有用信息的次数越多，文档就越会被用来（更成功）有效地完成任务和解决问题.

如果您在考虑，创作或编辑文档时遇到问题，请提及适用于DevOps 阶段的编写者，以#docs或 GitLab 中的 Slack 的技术写作团队提出. 否则，请尽力而为. 它并不一定是完美的. 团队很乐意审查和改进您的内容. 在开始您的第一个文档 MR 之前，请查阅文档指南 .

具有与文档不同的任何形式的知识库都将违反文档优先方法，因为其内容会与文档重叠.

Markdown

所有的 GitLab 文档都是使用Markdown编写的.

文档网站使用 GitLab Kramdown 作为 Markdown 渲染引擎. 有关完整的 Kramdown 参考，请参阅《 GitLab Markdown Kramdown 指南》 .

gitlab-kramdown Ruby gem 将来将支持所有GFM 标记 . 也就是说，所有标记都支持在 GitLab 应用程序本身中显示. 目前，请按照链接的样式指南中的规则使用常规的 Markdown 标记.

请注意，特定于 Kramdown 的标记（例如{:.class} ）不会在/help下的 GitLab 实例上正确呈现.

HTML in Markdown

硬编码的 HTML 是有效的，尽管在使用/help时不建议使用. 只要允许 HTML，就可以：

  • Markdown 中没有等效的标记.
  • 高级表是必需的.
  • 需要特殊的样式.
  • 由技术作家审查和批准.

Markdown Rules

GitLab 通过使用markdownlint 测试文档更改来确保所有文档中使用的 Markdown 是一致的，并且易于查看和维护. 当任何文档的 Markdown 格式存在问题时，此棉绒测试将失败，该问题可能导致页面在 GitLab 中无法正确呈现. 当文档使用非标准 Markdown（可以正确显示，但不是 GitLab 文档的当前标准）时，它也会失败.

Markdown rule MD044/proper-names (capitalization)

可能引起混乱的规则是MD044/proper-names ，因为可能无法立即弄清是什么导致 markdownlint 失败或如何纠正失败. 此规则检查每个项目的.markdownlint.json文件中列出的已知单词的列表，以验证是否正确使用了大写字母和反引号. 反引号中的单词将被 markdownlint 忽略.

通常，产品名称应紧跟产品，协议等正式名称的大写字母. 请参阅.markdownlint.json以获取有关 GitLab 文档中经过适当大写测试的单词.

如果使用不正确的大小写，则某些示例将失败：

  • MinIO（需要资本IO ）
  • NGINX（需要所有资金）
  • runit（需要小写r ）

此外，反引号中必须包含命令，参数，值，文件名等. 例如：

  • “在您的.gitlab.yml更改needs关键字……”
    • needs是一个参数，而.gitlab.yml是一个文件，因此两者都需要反引号. 此外， .gitlab.yml没有.gitlab.yml G 或 L，它将使 markdownlint 失败而没有反引号.
  • “Run git clone to clone a Git repository…”
    • git clone是命令，因此它必须是小写字母，而 Git 是乘积，因此它必须具有大写字母 G.

Structure

因为我们希望文档成为 SSOT，所以我们应该按主题（而不是类型）进行组织 .

Folder structure overview

该文档由顶级受众文件夹user ， administration和development （贡献）文件夹分开.

Beyond that, we primarily follow the structure of the GitLab user interface or API.

我们的目标是要建立一个清晰的层次结构，并包含有意义的 URL，例如docs.gitlab.com/user/project/merge_requests/ . 使用这种模式，您可以立即知道您正在导航到有关 Project 功能的用户相关文档； 特别是关于合并请求. 我们网站的路径与我们存储库的路径匹配，因此清晰的结构还使文档更易于更新.

下表显示了什么样的文档.

Directory 这里属于什么
doc/user/ 与用户相关的文档. 可以在 GitLab UI 中完成的所有操作都在这里进行，包括使用/admin界面.
doc/administration/ 要求用户有权访问安装了 GitLab 的服务器的文档. 可以通过 GitLab 界面访问的管理设置位于doc/user/admin_area/ .
doc/api/ API 相关文档.
doc/development/ 与 GitLab 开发相关的文档，无论是贡献代码还是文档. 相关的流程和样式指南应该在此处.
doc/legal/ 有关对 GitLab 进行贡献的法律文件.
doc/install/ 包含有关安装 GitLab 的说明.
doc/update/ 包含有关更新 GitLab 的说明.
doc/topics/ 每个主题的索引（ doc/topics/topic-name/index.md ）：该主题的所有资源.

Work with directories and files

  1. 创建新目录时，请始终以index.md文件开头. 不要使用其他文件名， 也不要创建README.md文件.
  2. 请勿在文件名，目录名，分支名和任何会生成路径的文件中使用特殊字符和空格或大写字母.
  3. 创建新文档时，如果名称中包含多个单词，请确保使用下划线而不是空格或破折号（ - ）. 例如，正确的命名应为import_projects_from_github.md . 相同的规则适用于图像.
  4. 对于图像文件，请勿超过 100KB.
  5. 不要将视频文件上传到产品存储库. 链接或嵌入视频 .
  6. 有四个主要目录， user ， administration ， api和development .
  7. doc/user/目录具有五个主要子目录： project/ ， group/ ， profile/ ， dashboard/和admin_area/ .
    1. doc/user/project/应包含所有与项目相关的文档.
    2. doc/user/group/应包含所有与组有关的文档.
    3. doc/user/profile/应包含所有与个人资料相关的文档. 您在/profile下导航的每个页面都应该有其自己的文档，例如account.md ， applications.md或emails.md .
    4. doc/user/dashboard/应包含所有与仪表板相关的文档.
    5. doc/user/admin_area/应该包含所有与管理员相关的文档，这些文档描述了通过访问 GitLab 的管理界面可以实现的目的（ 不要与需要服务器访问权限的doc/administration混淆 ）.
      1. /admin/application_settings/下的每个类别都应有自己的文档，位于doc/user/admin_area/settings/ . 例如，” 可见性和访问控制”类别应具有位于doc/user/admin_area/settings/visibility_and_access_controls.md .
  8. doc/topics/目录包含与主题相关的技术内容. 必要时创建doc/topics/topic-name/subtopic-name/index.md . 应放置与用户和管理员相关的常规文档.
  9. 目录/workflow/ ， /university/和/articles/已被弃用 ，并且大多数文档已通过较小的迭代移动到了正确的位置.

如果您不确定文档或内容添加应该放在哪里，那么这不会阻止您创作和贡献. 您可以根据自己的最佳判断，然后要求 MR 的审阅者确认您的决定，和/或在此过程的任何阶段询问技术作家. 技术写作团队将审查所有文档更改，无论如何，并且如果有合适的位置，可以移动内容.

Avoid duplication

不要在多个地方包含相同的信息. 链接到 SSOT.

References across documents

  • 给每个文件夹一个 index.md 页面，该页面介绍该主题，介绍其中的页面，并链接到其中的页面（包括任何下一级子路径的索引页面）.
  • 为确保可发现性，请确保每个新文档或重命名的文档都从其更高级别的索引页面和其他相关页面链接.
  • 当引用其他 GitLab 产品和功能时，至少在第一次提及时，链接到它们各自的文档.
  • 当引用第三方产品或技术时，请链接到其外部站点，文档和资源.

Structure within documents

  • 包括结构和模板页面上所述的所有适用小节.
  • Structure content in alphabetical order in tables, lists, and so on, unless there is a logical reason not to (for example, when mirroring the UI or an otherwise ordered sequence).

Language

GitLab 文档应清晰易懂.

  • 清楚，简明并遵守文档的目标.
  • 用美国英语和美国语法书写. （在British.yml测试.）
  • 使用包容性语言.

Point of view

在大多数情况下，使用第二人称（您自己）的观点是适当的，因为它友好且易于理解. （在FirstPerson.yml测试.）

Capitalization

  • 在 GitLab 中大写” G”和” L”.
  • 句子大小写用于：
    • 标题.
    • 标签.
    • 菜单项.
    • 纽扣.
    • 标题. 除非标题中提及产品功能，否则请勿在标题中大写其他单词. 例如：
      • 大写”问题”在## What you can do with GitLab Issues ，但在## Closing multiple issues不可接受.

  • 引用时使用标题大小写：

    • GitLab 功能 . 例如，发行板，地缘和亚军.
    • GitLab 产品层 . 例如，GitLab Core 和 GitLab Ultimate. （在BadgeCapitalization.yml测试.）
    • 第三方产品. 例如，Prometheus，Kubernetes 和 Git.

    • 方法或方法论. 例如，持续集成，持续部署，Scrum 和敏捷. （在.markdownlint.json测试.）

      注意：某些功能也是对象. 例如，” GitLab 的合并请求支持 X”和”为 Z 创建新的合并请求”.

Language to avoid

创建文档时，请限制或避免使用以下动词时态，单词和短语：

  • 避免行话.
  • 避免使用不常见的单词.
  • 不要以第一人称单数形式书写. （在FirstPerson.yml测试.）
    • 代替”我”或”我”，而使用”我们”，”您”，”我们”或”一个”.
    • 在可能的情况下，通过写第二人称（” you”或命令式）来保持用户的注意力.
  • 不要过度使用” that”. 在许多情况下，您可以从句子中删除” that”并提高可读性.
  • 避免使用将来时：
    • 代替”在执行此命令后，GitLab 将显示结果”，而应使用”在执行此命令后，GitLab 显示结果”.
    • 仅在将来某个时间实际发生动作或结果时，才使用将来时来表达.
  • 不要使用斜杠将不同的单词组合在一起，也不要用”或”代替：
    • 代替”和/或”，可以考虑使用”或”，或使用其他明智的结构.
    • 其他示例包括”克隆/获取”，作者/受让人和”命名空间/存储库名称”. 以适当的方式拆分任何此类实例.
    • 该规则的例外情况包括公认的技术术语，例如 CI / CD 和 TCP / IP.

  • We discourage use of Latin abbreviations, such as “e.g.,” “i.e.,” or “etc.,” as even native users of English might misunderstand them. (Tested in LatinTerms.yml.)

    • 代替”即”，使用”即”.
    • 代替”例如”，使用”例如”，”例如”，”例如”或”喜欢”.
    • 代替”等”，可以使用”依此类推”，也可以考虑对其进行编辑，因为它可能含糊不清.
  • 在谈论产品或其功能时，请避免当前使用该词. 该文档按原样描述了该产品，而不是将来的某个不确定点.
  • 避免在增加 GitLab 为其他用户的性能时使用可扩展性一词. 在其他情况下，可以使用” 缩放”或” 缩放”一词，但对于其他用户而言，提高 GitLab 性能的参考应将读者引导至 GitLab 参考架构页面.
  • 避免使用所有形式的短语” 高可用性”和” HA” ，而是将读者引导至 GitLab 参考体系结构，以获取有关配置 GitLab 使其随着时间的推移具有更多用户所需的性能的信息.
  • 不要使用亵渎或 ob 亵. 这样做可能会对其他用户和贡献者产生负面影响，这与 GitLab 的” 多样性”，”包容性”和”归属”的价值背道而驰.
  • 避免使用对种族不敏感的术语或短语 . 例如：
    • 将主数据库和辅助数据库用于数据库和服务器关系.
    • 使用allowlist和denylist来描述访问控制列表.

Word usage clarifications

  • 不要互换使用” may”和” might”：
    • 使用”可能”表示发生某事的可能性. “如果跳过此步骤，则导入过程可能会失败.”
    • 使用”可能”表示允许某人做某事，或者考虑使用”可以”. “您可以在此屏幕上选择一个选项.” 或者，”您可以在此屏幕上选择任一选项.”

Contractions

  • Use common contractions when it helps create a friendly and informal tone, especially in tutorials, instructional documentation, and UIs. (Tested in Contractions.yml.)

    | Do | Don’t | | —- | —- | | it’s | 它是 | | can’t | cannot | | wouldn’t | 不会 | | you’re | 你是 | | you’ve | 你有 | | haven’t | 没有 | | don’t | 不要 | | we’re | 我们是 | | that’s | 那是 | | won’t | 将不会 |

  • 避免少见的宫缩：

    | Do | Don’t | | —- | —- | | 他会 | he’d | | 它会 | it’ll | | 应该有 | should’ve | | 那里会 | there’d |

  • 不要使用带有专有名词和动词的缩略词. 例如：

    | Do | Don’t | | —- | —- | | GitLab 正在创建 X | manbetx 客户端打不开创建 X |

  • 当您需要强调负面情绪时，不要使用收缩. 例如：

    | Do | Don’t | | —- | —- | | 不要为 Y 安装 X | 不要将 X 与 Y 一起安装 |

  • 不要在参考文档中使用收缩. 例如：

    | Do | Don’t | | —- | —- | | 不要设置限制大于 1000 | 请勿将限制设置为大于 1000 | | 对于parameter1 ，默认值为 10 | 对于parameter1 ，默认值为 10 |

  • 避免错误消息中出现收缩. 例子：

    | Do | Don’t | | —- | —- | | 不允许对本地主机的请求 | 不允许对本地主机的请求 | | 指定的 URL 不能使用 | 指定的网址无法使用 |

Text

  • Write in Markdown.
  • 分隔长行（最好最多 100 个字符）可以更轻松地提供有关小块文本的反馈.
  • 在新段落中插入一个空行.

  • 在不同的标记之间插入一个空行（例如，在每个段落，标题，列表等之后）. 例：

    1. ## Header
    3. Paragraph.
    4.  - List item 1
    5. - List item 2

Emphasis

  • 使用双星号（ ** ）将单词或文本标记为粗体（ **bold** ）.
  • 下划线（ _ ）用于斜体（ _italic_ ）文本.
  • 块引用使用大于（ > ）.

Punctuation

检查下表中 GitLab 文档的常规标点规则. 检查以下列表的特定标点规则.

Rule Example
总是以句号结束完整的句子. 有关完整概述，请通读本文档.
在开始新句子时，请始终在句点之后添加空格. 有关完整的概述，请查看此文档. 有关其他参考，请查阅本指南.
不要使用双空格. （在SentenceSpacing.yml测试.） —
不要使用制表符进行缩进. 请改用空格. 您可以将代码编辑器配置为在按 Tab 键时输出空格而不是制表符. —
在列表中最后一个”和/或”之前使用连续逗号（”牛津逗号”）. （在OxfordComma.yml测试.） 您可以创建新问题，合并请求和里程碑.
在句子中使用破折号之前和之后，请始终添加空格（例如，用于替换逗号）. 您应该尝试这样做-还是不可以.
总是在冒号后面使用小写字母. 相关问题：一种在问题之间建立关系的方法.

Placeholder text

在示例中，编写者通常会提供除特定于阅读者的值之外完整的命令或配置.

在这些情况下，使用<和>指出读者必须用自己的值替换文本的位置.

例如：

  1. cp <your_source_directory> <your_destination_directory>

Lists

  • 始终使用大写字母开头列表项，除非它们是反引号或类似的参数或命令.
  • 始终在列表前后留空行.
  • 以空格（不是制表符）开头的行表示嵌套的子项 .

Ordered vs. unordered lists

仅当其项目描述要遵循的步骤序列时，才使用有序列表.

Do:

  1. These are the steps to do something:
  2.  1. First, do the first step.
  3. 1. Then, do the next step.
  4. 1. Finally, do the last step.

Don’t:

  1. This is a list of available features:
  2.  1. Feature 1
  3. 1. Feature 2
  4. 1. Feature 3

Markup

  • 对于无序列表，请使用破折号（ - ）代替星号（ * ）.
  • 在有序列表中的每个项目之前添加前缀1. .. 呈现后，列表项将自动以顺序编号显示.

Punctuation

  • 不要在列表项的末尾添加逗号（ , ）或分号（ ; ）.
  • 如果项目由完整的句子组成，则仅在项目的末尾添加句号. 完整句子的定义是： “完整句子总是包含一个动词，表达一个完整的构想，并且在单独存在时有意义” .
  • Be consistent throughout the list: if the majority of the items do not end in a period, do not end any of the items in a period, even if they consist of a complete sentence. The opposite is also valid: if the majority of the items end with a period, end all with a period.

  • 从解释性文字分隔列表项用冒号（ : ）. 例如：

    1. The list is as follows:
    2.  - First item: this explains the first item.
    3. - Second item: this explains the second item.

Examples:

Do:

  • 第一个清单项目
  • 第二个清单项目
  • 第三清单项目

Don’t:

  • 第一个清单项目
  • 第二个清单项目
  • 第三列表项.

Do:

  • 假设这是一个完整的句子.
  • 假设这也是一个完整的句子.
  • 句子不完整.

请勿（各种句号的使用；多数规则）：

  • 假设这是一个完整的句子.
  • 假设这也是一个完整的句子.
  • 句子不完整

Nesting inside a list item

可以将项目嵌套在列表项目下，以便它们呈现与列表项目相同的缩进. 这可以通过以下方式完成：

嵌套在列表中的项目应始终与列表项目的第一个字符对齐. 在无序列表（使用- ）中，这表示每个缩进级别有两个空格：

  1. - Unordered list item 1
  3.   A line nested using 2 spaces to align with the `U` above.
  4.  - Unordered list item 2
  5.  > A quote block that will nest
  6.  > inside list item 2.
  7.  - Unordered list item 3
  9.   ```plaintext
  10.   a codeblock that will next inside list item 3

  • Unordered list item 4

    an image that will nest inside list item 4 ```

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

  1. 1. Ordered list item 1
  3.    A line nested using 3 spaces to align with the `O` above.
  4.  1. Ordered list item 2
  5.  > A quote block that will nest
  6.  > inside list item 2.
  7.  1. Ordered list item 3
  9.    ```plaintext
  10.    a codeblock that will next inside list item 3

  1. Ordered list item 4

    an image that will nest inside list item 4 ```

您可以使用与上述相同的规则将完整列表嵌套在其他列表中. 如果您希望混合类型，也可以，只要您不混合同一级别的项目即可：

  1. 1. Ordered list item one.
  2. 1. Ordered list item two.
  3.  - Nested unordered list item one.
  4.  - Nested unordered list item two.
  5. 1. Ordered list item three.
  6.  - Unordered list item one.
  7. - Unordered list item two.
  8.  1. Nested ordered list item one.
  9.  1. Nested ordered list item two.
  10. - Unordered list item three.

Tables

应该使用表格以简单的方式描述复杂的信息. 请注意，在许多情况下，无序列表足以描述一个项目列表，而每个项目只有一个简单的描述. 但是，如果您拥有最能用矩阵描述的数据，则表是使用的最佳选择.

Creation guidelines

由于可访问性和可扫描性要求，表中不应包含任何空白单元格. 如果某个单元格没有其他有意义的值，请考虑输入N / A （”不适用”）或不输入 .

为了使表更易于维护，请考虑在列宽上添加额外的空格以使其一致. 例如：

  1. | App name | Description          | Requirements   |
  2. |:---------|:---------------------|:---------------|
  3. | App 1    | Description text 1\.  | Requirements 1 |
  4. | App 2    | Description text 2\.  | None           |

考虑在编辑器中安装插件或扩展程序以格式化表格：

Feature tables

创建功能列表时（例如，” 权限”页面上的某些角色是否可以使用功能），请使用以下短语（基于 SVG 图标）：

  • No: No
  • Yes: Yes

Quotes

仅适用于 Markdown 内容，不适用于优先事项条目：

  • 标准引号：双引号（ " ）.例如：”这用双引号引起来”.
  • 用引号引起来：双引号（ " ）包裹单引号（ ' ）.例如：”我正在用引号引起来”.

有关其他标点规则，请参考GitLab UX 指南 .

Headings

  • 通过在每个文档的开头添加# （在使用 Markdown 时）， 仅在每个文档中添加一个 H1 . h1将是文档<title> .
  • 从h2 （ ## ）开始，并遵循h2 > h3 > h4 > h5 > h6的顺序. 切勿跳过层次结构级别，例如h2 > h4
  • 避免将数字放在标题中. 数字移动，因此文档锚链接也移动，最终导致死链接. 如果您认为在标题中添加数字非常有必要，请确保至少与”合并请求”中的某人进行讨论.
  • 避免在标题中使用符号和特殊字符 . 只要有可能，它们应为纯文本和简短文本.
  • 避免添加显示短暂状态的内容. 例如，如果某个功能被认为是 Beta 或试验性功能，请将此信息放在注释中而不是标题中.
  • 引入新文档时，请注意标题在语法和语法上都是正确的. 提及指定的技术作家（TW）以进行审查. 这是为了确保没有错误标题的文档将在未经审核的情况下生效，从而防止在纠正时出现无效链接和重定向问题.
  • 在标题前后只留一个空白行.
  • 不要在标题中使用链接.
  • 根据功能所属的级别添加相应的产品徽章 .
  • 我们的 docs 网站搜索引擎会区分标题和副标题中使用的单词的优先级. 如标题标题部分所示，使标题标题清晰，描述性且完整，以帮助用户找到正确的示例.
  • 有关将标题大写的指南，请参见大写 .

Heading titles

保持标题清晰，直接. 使每个单词都重要. 为了适应搜索引擎优化（SEO），请尽可能使用命令.

Do Don’t
Configure GDK Configuring GDK
GitLab 发布和维护政策 本节介绍 GitLab 的发布和维护政策
向后移植到较旧的版本 向后移植到较旧的版本
GitLab 页面示例 Examples

有关大写标题的准则，请参见大写部分.

注意：如果更改现有标题，请当心. 任何此类更改可能不仅影响页面内的链接 ，而且还可能影响来自 GitLab 本身的链接以及指向 GitLab 文档的外部链接.

Anchor links

渲染时，标题会自动生成锚链接. ## This is an example生成锚点#this-is-an-example .

请记住，GitLab UI 链接到大量文档以及相应的锚链接，以将用户带到正确的位置. 因此，当您更改标题时，请在doc/* ， app/views/*和ee/app/views/*搜索旧的锚点，以确保您不会破坏从其他文档或 GitLab UI 链接的锚点. 如果找到旧的锚，请确保将其替换为新的锚.

Important:

  • 除非需要链接到文档的特定部分，否则请避免将文档交到标题. 如果方向改变，这将避免将来破坏锚.
  • 如果可能，请避免更改标题，因为它们不仅是内部链接的. 互联网上有指向 GitLab 文档的各种链接，例如教程，演示文稿，StackOverflow 帖子和其他资源.
  • 不要链接到h1标题.

需要注意的是，与 Kramdown，也可以自定义 ID 添加到与降价的标记 HTML 元素，但他们没有在 GitLab 的工作/help . 因此，除非另行通知，否则不要使用此选项.

Links

链接在 GitLab 文档中很重要. 它们使您可以链接而不是进行汇总，以帮助在 GitLab 文档中保留SSoT .

我们提供以下类别的链接指南：

Basic link criteria

  • 使用内联链接 Markdown 标记[Text](https://example.com) . 它更易于阅读，查看和维护. 不要使用[Text][identifier] .

  • 使用有意义的锚文本 . 例如， Read more about GitLab Issue Boards [here](LINK)编写类似” Read more about GitLab Issue Boards [here](LINK) ，而不是撰写Read more about [GitLab Issue Boards](LINK) .

Links to internal documentation

注意： 内部是指同一项目中的文档. 链接到单独项目中的文档时（例如，从 GitLab 文档链接到 Omnibus 文档），必须使用绝对 URL.

请勿使用https://docs.gitlab.com/ee/index.html类的绝对 URL 交叉链接到同一项目中的其他文档. 使用指向文件的相对链接，例如../index.md . （在呈现网站时将这些转换为 HTML.）

相对链接使交叉链接可以正常工作：

  • 在 Review Apps，本地预览和/help .
  • 在本地处理文档时，您可以在此过程中尽早验证它们是否有效.
  • 浏览各自存储库中的文档文件时，可以在 GitLab UI 中使用. 例如，显示在https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/README.md的链接.

链接到内部文档：

  • 使用相对链接指向同一存储库中的 Markdown 文件.
  • 不要使用绝对 URL 或docs.gitlab.com URL.
  • 使用../导航到更高级别的目录.

  • 不要相对于根链接. 例如，/ /ee/user/gitlab_com/index.md .

    Don’t:

    • https://docs.gitlab.com/ee/administration/geo/replication/troubleshooting.html
    • /ee/administration/geo/replication/troubleshooting.md

    Do: ../../geo/replication/troubleshooting.md

  • 始终在链接末尾添加文件名file.md ，扩展名为.md而不是.html .

    Don’t:

    • ../../merge_requests/
    • ../../issues/tags.html
    • ../../issues/tags.html#stages

    Do:

    • ../../merge_requests/index.md
    • ../../issues/tags.md
    • ../../issues/tags.md#stages

注意： GitLab 的/help部分必须使用 Markdown 扩展名.

Links to external documentation

描述与外部软件的交互时，包括指向外部文档的链接通常会很有帮助. 如果可能，请确保您链接到权威来源. 例如，如果您要描述 Microsoft Active Directory 中的功能，请包括指向 Microsoft 官方文档的链接.

Links requiring permissions

不要直接链接到：

这些将因以下原因而失败：

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

Instead:

  • 为了减少混乱，请在文本中提及以下信息之一：
    • 包含在一个机密问题中.
    • 需要项目的特殊权限才能查看.
  • 在反勾号（ ``` ）中提供一个链接，以便那些有权访问该问题的人可以轻松导航到该问题.

Example:

  1. For more information, see the [confidential issue](../../user/project/issues/confidential_issues.md) `https://gitlab.com/gitlab-org/gitlab-foss/-/issues/<issue_number>`.

Link to specific lines of code

链接到文件中的特定行时，请链接到提交而不是分支. 代码行随时间变化，因此，使用 commit 链接链接到一行可确保用户落在您所指的行上. 在查看项目中的文件时，可以使用” 永久链接”按钮，它可以轻松生成指向给定文件的最新提交的链接.

  • Do: [link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/11f17c56d8b7f0b752562d78a4298a3a95b5ce66/.gitlab/issue_templates/Feature%20proposal.md#L3)
  • Don’t: [link to line 3](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20proposal.md#L3).

如果由于进一步的提交，该链接的表达式不再在文件的该行中，则您仍然可以在文件中搜索该查询. 在这种情况下，请更新文档以确保其链接到文件的最新版本.

Navigation

指示通过 UI 导航的步骤：

  • 使用界面中显示的确切字词，包括所有大写字母.
  • 使用粗体文本显示导航项，并使用字符”大于”（ > ）作为分隔符（例如， Navigate to your project's **Settings > CI/CD** ）.
  • 如果有任何可展开的菜单，请确保提及用户需要展开选项卡以找到您要引用的设置（例如， Navigate to your project's **Settings > CI/CD** and expand **General pipelines** ）.

Images

图像（包括屏幕截图）可以帮助读者更好地理解概念. 但是，它们可能难以维护，应谨慎使用.

在文档中包括图片之前，请确保它为读者提供了价值.

Capture the image

使用图像可以帮助读者了解它们在过程中的位置，或与应用程序进行交互的方式.

截屏时：

  • 捕获页面中最相关的区域. 不要包含不必要的空白或页面区域，以免说明您的观点. 另外，如果不需要，不要包括整个页面，而且还要确保图像包含足够的信息以允许用户确定事物的位置.
  • 始终如一. 找到适合您的浏览器窗口大小，该窗口大小还会显示产品的所有区域，包括左侧导航栏（通常> 1200 像素宽）. 为了保持一致，请通过安装用于将窗口设置为特定大小的浏览器扩展程序（例如，用于 Google Chrome 的Window Resizer ），将此浏览器窗口大小用于屏幕截图.

Save the image

  • 用一个小写的文件名保存该图像，该文件名描述了图像中的功能或概念. 如果该图像属于 GitLab 界面，则根据以下格式将 GitLab 版本附加到文件名： image_name_vX_Y.png . 例如，对于从 GitLab 11.1 的管道页面中截取的屏幕截图，有效名称为pipelines_v11_1.png . 如果要添加的插图不包含用户界面的各个部分，请添加与添加图像的版本相对应的版本号； 对于添加到 11.1 里程碑中的 MR，插图的有效名称是devops_diagram_v11_1.png .
  • 将图像放置在名为img/的单独目录中，该目录与您正在使用的.md文档所在的目录相同.
  • 考虑使用 PNG 图像而不是 JPEG.
  • Compress all PNG images.
  • 使用https://ezgif.com/optimize或类似工具压缩 gif.
  • 应该使用图像（仅在必要时使用）来说明过程说明，而不是替代过程.
  • 图片大小上限：100KB（含 Gif）.
  • 另请参阅如何链接和嵌入视频以说明文档.

Add the image link to content

用于在文档中包含图像的 Markdown 代码为： ![Image description which will be the alt tag](img/document_image_title_vX_Y.png)

图像描述是 docs 网站上渲染图像的替代文本. 对于可访问性和 SEO，请使用以下描述 ：

  • 准确，简洁且独特.
  • 请勿使用…的图像或…的 图形来描述图像.

另外，如果标题紧随图像之后，请确保在图像和标题之间添加三个破折号（ --- ）.

Remove image shadow

默认情况下，在GitLab 文档站点上显示的所有图像都有一个阴影框. 要删除框阴影，请使用直接应用于 HTML img标签的图像类.image-noshadow ：

  1. <img src="path/to/image.jpg" alt="Alt text (required)" class="image-noshadow">

Compress images

您应该始终压缩添加到文档中的任何新图像. 一种已知的工具是pngquant ，它是跨平台和开源的. 通过访问官方网站并按照您的操作系统说明进行安装.

GitLab 有一个Rake 任务 ，可用于自动执行该过程. 在本地https://gitlab.com/gitlab-org/gitlab副本的根目录中，在终端中运行：

  • 压缩之前，如果需要，请检查是否已压缩所有文档 PNG 图像：

    1. bundle exec rake pngquant:lint

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

    1. bundle exec rake pngquant:compress

唯一需要注意的是，该任务将在doc/下的所有图像上运行，而不仅仅是您可能包含在合并请求中的图像. 在这种情况下，您可以运行 compress 任务，仅提交与合并请求相关的图像.

Videos

强烈建议将 GitLab 的现有 YouTube 视频教程添加到文档中，除非该视频已过时. 视频不应取代文档，而应补充或说明文档. 如果视频中的内容是功能及其关键用例的基础，但是文档中没有对此进行充分介绍，请将此详细信息添加到文档文本中，或者创建问题以查看视频并这样做.

不要将视频上传到产品存储库. 链接或嵌入它们.

Link to video

要链接到视频，请添加 YouTube 图标，以便读者在阅读之前可以快速轻松地扫描页面上的视频：

  1. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
  2. For an overview, see [Video Title](link-to-video).

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

Embed videos

在 GitLab 12.1 中引入 .

GitLab Docs 网站支持嵌入式视频.

您只能嵌入来自GitLab 的官方 YouTube 帐户的视频 . 对于其他来源的视频，请链接它们.

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

要嵌入视频，请按照以下说明进行操作，并确保您的 MR 已得到技术作家的审查和批准.

  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.com/embed/VIDEO-ID ），然后粘贴它，替换iframe标记中src字段的内容.
  1. leave a blank line here
  2. <div class="video-fallback">
  3.   See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>.
  4. </div>
  5. <figure class="video-container">
  6.   <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe>
  7. </figure>
  8. leave a blank line here

它是如何在 GitLab Docs 网站上呈现的：

观看视频： 什么是 GitLab .

Notes:

  • figure标记是语义 SEO 所必需的，而video_container类是必需的，以确保视频能够响应并在不同的移动设备上很好地显示.
  • <div class="video-fallback">是 GitLab 的/help必需的后备，因为 GitLab 的 Markdown 处理器不支持 iframe. 它隐藏在 docs 网站上，但将显示在 GitLab 的/help .

Code blocks

  • 始终将添加到句子的代码包装在内联代码块（ `` ）中. 例如.gitlab-ci.yml，git add .，CODEOWNERS或only: [master]` . 文件名，命令，条目以及任何涉及代码的内容都应添加到代码块中. 为了使用户更轻松，请始终为可复制和粘贴的内容添加完整的代码块，因为他们可以使用代码块上的按钮轻松进行操作.
  • 在代码块的上方和下方添加一个空行.
  • 提供 shell 命令及其输出时，请在 shell 命令前加上$前缀，并在命令和输出之间留空行.
  • 提供无输出的命令时，请不要在 shell 命令前加上$前缀.
  • 如果需要在代码块中包括三个反引号，则对代码块围栏使用四个反引号，而不是三个.

  • 对于常规的受保护代码块，请始终使用与该语言对应的突出显示类，以提高可读性. 例子：

    1. ```ruby Ruby code

    ```javascript JavaScript code

    2. ```markdown [Markdown code example](example.md)

    plaintext Code or text for which no specific highlighting class is available. ```

加到 GitLab 文档中的受防护代码块要求突出显示语法. 有关最常用的语言类别，请参考下表，或查看可用语言类别的完整列表 .

首选语言标签 语言别名和注释
asciidoc
dockerfile Alias: docker.
elixir
erb
golang Alias: go.
graphql
haml
html
ini 对于一些非 TOML 格式的简单配置文件.
javascript Alias js.
json
markdown Alias: md.
mermaid
nginx
perl
php
plaintext 没有定义语言的示例，例如 shell 命令或 API 调用的输出. 如果代码块没有语言，则默认为plaintext . 别名： text .
prometheus Prometheus 配置示例.
python
ruby Alias: rb.
shell Aliases: bash or sh.
sql
toml Runner 配置示例以及其他 TOML 格式的配置文件.
typescript Alias: ts.
xml
yaml Alias: yml.

有关代码块的完整参考，请参阅《 Kramdown 指南》 .

GitLab SVG icons

在 GitLab 12.7 中引入 .

您可以直接在文档中使用来自GitLab SVG 库的图标.

This way, you can achieve a consistent look when writing about interacting with GitLab UI elements.

用法示例：

  • 默认尺寸（16 像素）的**{icon-name}** ： **{icon-name}**

    示例： **{tanuki}**呈现为： .

  • 具有自定义尺寸的**{icon-name, size}** ： **{icon-name, size}**

    可用尺寸（以像素为单位）：8、10、12、14、16、18、24、32、48 和 72

    示例： **{tanuki, 24}**呈现为： .

  • 具有自定义尺寸和类别的**{icon-name, size, class-name}** ： **{icon-name, size, class-name}** .

    您可以在 GitLab 文档 CSS 中访问此元素可用的任何类.

    带有float-right示例， Bootstrap 实用程序类 ： **{tanuki, 32, float-right}**呈现为：

Use GitLab SVGs to describe UI elements

使用 GitLab SVG 描述屏幕元素时，还应包括该元素的名称或工具提示作为文本.

例如，对于”管理区”的引用：

  • Correct: **{admin}** **Admin Area > Settings** ( 管理区域>设置)
  • Incorrect: **{admin}** **> Settings** ( >设定)

这将确保源 Markdown 保持可读性，并应有助于辅助功能.

以下是菜单项的源 Markdown 示例及其发布的输出：

  1. 1. Go to **{home}** **Project overview > Details**
  2. 1. Go to **{doc-text}** **Repository > Branches**
  3. 1. Go to **{issues}** **Issues > List**
  4. 1. Go to **{merge-request}** **Merge Requests**
  5. 1. Go to **{rocket}** **CI/CD > Pipelines**
  6. 1. Go to **{shield}** **Security & Compliance > Configuration**
  7. 1. Go to **{cloud-gear}** **Operations > Metrics**
  8. 1. Go to **{package}** **Packages > Container Registry**
  9. 1. Go to **{chart}** **Project Analytics > Code Review**
  10. 1. Go to **{book}** **Wiki**
  11. 1. Go to **{snippet}** **Snippets**
  12. 1. Go to **{users}** **Members**
  13. 1. Select the **More actions** **{ellipsis_v}** icon  > **Hide stage**
  1. 去 项目概述>详细信息
  2. Go to 资料库>分支机构
  3. 去 问题>清单
  4. 去 合并请求
  5. 去 CI / CD>管道
  6. 去 安全与合规>配置
  7. 去 操作>指标
  8. 去 包>容器注册表
  9. 去 项目分析>代码审查
  10. 去 维基
  11. 去 片段
  12. 去 会员
  13. 选择更多操作 图标> 隐藏舞台

Alert boxes

每当您需要特别注意特定句子时，请使用以下标记突出显示.

请注意，警报框仅适用于一个段落. 多个段落，列表，标题等将无法正确呈现. 对于多行，请改用blockquotes .

警报框仅在 GitLab Docs 网站（ https://docs.gitlab.com ）上呈现. 在 GitLab 本身中，它们将显示为纯 Markdown 文本（如下面呈现的版本上方的示例）.

Note

注释引起了大多数读者的注意，因此应谨慎使用. 在大多数情况下，应考虑为便笺考虑的内容：

  • 仅作为上一段或最相关段落中的另一句话.
  • 作为其自己的独立段落.
  • 作为介绍该主题的新子标题下的内容，使它更明显/更容易找到.

When to use

当出于某种原因，大多数或所有浏览本节的读者都应看到内容时，请使用注释. 就是说，如果错过了它，可能会给少数用户造成重大麻烦，或者对大多数用户造成重大麻烦.

权衡分散内容无关用户的成本与丢失内容（如果未表示为注释）的用户成本.

  1. NOTE: **Note:**
  2. This is something to note.

它如何在 GitLab Docs 网站上呈现：

注意：这是要注意的事情.

Tip

  1. TIP: **Tip:**
  2. This is a tip.

它如何在 GitLab Docs 网站上呈现：

提示：这是一个提示.

Caution

  1. CAUTION: **Caution:**
  2. This is something to be cautious about.

它如何在 GitLab Docs 网站上呈现：

注意：这是要谨慎的事情.

Danger

  1. DANGER: **Danger:**
  2. This is a breaking change, a bug, or something very important to note.

它如何在 GitLab Docs 网站上呈现：

危险：这是一个重大更改，错误或要注意的重要事项.

Blockquotes

要突出显示蓝色方框引号内的文本，请使用以下格式：

  1. > This is a blockquote.

在GitLab 文档网站上显示为：

这是一个大引用.

如果文本跨多行，则可以拆分行.

对于多个段落，请在每行之前使用符号> ：

  1. > This is the first paragraph.
  2. >
  3. > This is the second paragraph.
  4. >
  5. > - This is a list item
  6. > - Second item in the list

导致：

这是第一段.

这是第二段.

  • 这是一个清单项目
  • 列表中的第二项

Terms

为了通过 GitLab 文档保持一致性，以下内容将指导文档作者了解一致的样式和术语的用法.

Merge Requests (MRs)

合并请求使您可以交换对源代码所做的更改，并与同一项目中的其他人进行协作. 您将看到此术语以下列方式使用：

  • 如果您要使用此功能，请使用合并请求 .
  • 在任何其他上下文中，请使用merge request .

如我们公司的《 写作风格指南》所述 ，如果您使用MR首字母缩写词，请在每个文档页面上至少展开一次. 例如，第一次指定 MR 时，请指定Merge Request（MR）或merge request（MR） .

Examples:

  • “我们更喜欢 GitLab 合并请求”.
  • “打开合并请求以修复断开的链接”.
  • “打开合并请求（MR）后，将您的 MR 提交以供审核和批准”.

Describe UI elements

以下是在屏幕上描述 UI 元素时要遵循的样式：

  • 对于带有可见标签的元素，请使用带有匹配大小写的粗体标签. 例如， the **Cancel** button .
  • 对于带有工具提示或悬停标签的元素，请使用带有匹配大小写的粗体标签. 例如， the **Add status emoji** button .

Verbs for UI elements

以下是建议用于 UI 元素的特定动词：

Recommended 用于 Replaces
click 按钮，链接，菜单项 “点击”，”按”，”选择”
select or clear checkboxes “启用”，”单击”，”按”
select dropdowns “pick”
expand expandable sections “open”

Other Verbs

Recommended 用于 Replaces
去 使浏览器定位 “导航至”，”打开”

GitLab versions and tiers

标记和发布版本的 GitLab 文档可用：

引入新功能的版本已添加到文档主题的顶部，以提供有关该功能开发方式的有用链接.

Text for documentation requiring version text

  • For features that need to declare the GitLab version that the feature was introduced. Text similar to the following should be added immediately below the heading as a blockquote:
    • > Introduced in GitLab 11.3..
  • 只要有可能，版本文本都应具有指向已完成的发行，合并请求或引入了该功能的史诗的链接. 问题优先于合并请求，而合并请求优先于史诗. 例如：
    • > [Introduced](<link-to-issue>) in GitLab 11.3. .
  • 如果该功能仅在 GitLab 企业版中可用，请提及该功能在以下位置的付费层 ：
    • > [Introduced](<link-to-issue>) in [GitLab Starter](https://about.gitlab.com/pricing/) 11.3. .

  • 如果随着功能的发展列出了多个版本的信息，请将该信息添加到带引号的项目符号列表中. 例如：

    1. > - [Introduced](<link-to-issue>) in GitLab 11.3.
    2. > - Enabled by default in GitLab 11.4.

  • 如果功能已移至另一层：

    1. > - [Introduced](<link-to-issue>) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5.
    2. > - [Moved](<link-to-issue>) to [GitLab Starter](https://about.gitlab.com/pricing/) in 11.8.
    3. > - [Moved](<link-to-issue>) to GitLab Core in 12.0.

  • 如果不推荐使用某个功能，请提供替换链接（如果有）：

    1. > - [Deprecated](<link-to-issue>) in GitLab 11.3\. Replaced by [meaningful text](<link-to-appropriate-documentation>).

    如果可以的话，也可以在周围的文字中描述替换内容.

    如果现有文本中的弃用不明显，则可能需要添加警告，例如：

    1.  CAUTION: **Warning:**
    2.  This feature was [deprecated](link-to-issue) in GitLab 12.3
    3.  and replaced by [Feature name](link-to-feature-documentation).

注意：版本文本必须在其单独的行上并由空白行包围才能正确呈现.

Versions in the past or future

描述过去或将来版本中可用的功能时，请使用：

  • 较早的 ，不早 于之前的 .
  • 后来 ，并没有新的或之后 .

例如：

  • 在 GitLab 12.3 和更早版本中可用.
  • 在 GitLab 12.4 和更高版本中可用.
  • 如果使用 GitLab 11.4 或更早版本，…
  • 如果使用 GitLab 10.6 或更高版本，…

Importance of referencing GitLab versions and tiers

提及 GitLab 版本和层对所有用户和贡献者来说很重要，以便他们能够快速访问引入变更的发行或合并请求以供参考. 此外，鉴于该注释包含一些关键信息，他们可以轻松了解其 GitLab 实例和版本中具有哪些功能.

[Introduced](link-to-issue) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7链接到引入该功能的问题，说它属于哪个 GitLab 层，GitLab 说该版本可用的版本，并链接到定价页面，以防用户想要升级到付费层以使用该功能.

例如，如果您是普通用户，并且正在查看以前从未使用过的功能的文档，则可以立即查看该功能是否可用. 另外，如果您长期使用某项功能并且以某种方式进行了更改，那么重要的是要能够发现更改的时间以及该功能的新增功能.

这一点更为重要，因为我们没有一个完美的文档发布流程. 不幸的是，我们仍然看到没有文档的功能和没有功能的文档. 因此，就目前而言，我们不能 100％依赖 docs 网站版本.

随着时间的推移，版本文本将引用 GitLab 的逐渐老版本. 如果版本文本引用了 GitLab 的四个或更多个主要版本，您可以考虑删除不相关或令人困惑的文本.

例如，如果当前的主要版本是 12.x，则在需要更清晰或更干净的文档时，需要引用引用 GitLab 8.x 和更早版本的版本文本.

Products and features

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

Avoid line breaks in names

输入包含空格（例如 GitLab 社区版）或什至其他公司产品（例如 Amazon Web Services）的产品或功能名称时，请确保不要在插入了换行符的行之间拆分产品或功能名称. 跨行拆分产品或功能名称会使搜索这些项目更加困难，并且如果名称更改则可能导致问题.

例如，以下 Markdown 内容的格式不正确：

  1. When entering a product or feature name that includes a space (such as GitLab
  2. Community Edition), don't split the product or feature name across lines.

而是，它应类似于以下内容：

  1. When entering a product or feature name that includes a space (such as
  2. GitLab Community Edition), don't split the product or feature name across lines.

Product badges

当仅 EE 层中有功能可用时，请根据功能可用性添加相应的层：

  • 对于 GitLab Core 和 GitLab.com 免费： **(CORE)** .
  • 对于 GitLab Starter 和 GitLab.com 铜牌： **(STARTER)** .
  • 对于 GitLab Premium 和 GitLab.com 银牌： **(PREMIUM)** .
  • 对于 GitLab Ultimate 和 GitLab.com Gold： **(ULTIMATE)** .

要排除 GitLab.com 层（当该功能在 GitLab.com 中不可用时），请添加关键字” only”：

  • 对于 GitLab Core： **(CORE ONLY)** .
  • 对于 GitLab Starter： **(STARTER ONLY)**适用于**(STARTER ONLY)** .
  • 对于 GitLab Premium： **(PREMIUM ONLY)** .
  • 对于 GitLab Ultimate： **(ULTIMATE ONLY)** .

对于 GitLab.com 仅适用于层（当该功能不适用于自我管理实例时）：

  • 对于 GitLab 免费和更高级别： **(FREE ONLY)** .
  • 对于 GitLab 青铜级和更高级别： **(BRONZE ONLY)**铜级**(BRONZE ONLY)** .
  • 对于 GitLab Silver 和更高级别： **(SILVER ONLY)** .
  • 对于 GitLab Gold： **(GOLD ONLY)** .

理想情况下，应将该层添加到标题中，以便显示完整的徽标. 但是，也可以从段落，列表项和表格单元格中提及. 对于这些情况，层级提及将由橙色的信息图标（信息）表示，该图标将显示悬停时的层级.

即使页面上存在较高级别的层，也应使用页面级别的最低层. 例如，您可能有一个页面标记为 Starter，而一个部分标记为 Premium.

例如：

  • **(STARTER)**呈现为
  • **(STARTER ONLY)**呈现为
  • **(SILVER ONLY)**呈现为

没有提及层意味着该功能可在 GitLab Core，GitLab.com Free 和所有更高层使用.

How it works

由！244引入的特殊标记**(STARTER)**将生成一个span元素，以触发徽章和工具提示（ <span class="badge-trigger starter"> ）. 添加关键字” only”时，将不会显示相应的 GitLab.com 徽章.

Specific sections

某些样式应应用于特定部分. 下面概述了特定部分的样式.

GitLab restart

在许多情况下，需要重新启动/重新配置 GitLab. 为避免重复，请链接到可以在doc/administration/restart_gitlab.md找到的特殊文档. 通常，文本显示如下：

  1. Save the file and [reconfigure GitLab](../../administration/restart_gitlab.md)
  2. for the changes to take effect.

如果您正在编辑的文档位于 GitLab CE / EE doc/目录之外的其他位置，请使用完整路径，而不是相对链接： https://docs.gitlab.com/ce/administration/restart_gitlab.html : https://docs.gitlab.com/ce/administration/restart_gitlab.html . 在适当的地方，将reconfigure替换为reconfigure restart .

Installation guide

Ruby：在安装指南的第 2 步中 ，我们从源代码安装 Ruby. 每当有新版本需要更新时，请记住在整个代码块中进行更改，并替换 sha256sum（可在 Ruby 网站的下载页面中找到）.

Configuration documentation for source and Omnibus installations

GitLab currently officially supports two installation methods: installations from source and Omnibus packages installations.

只要有两种安装方法都可以配置的设置，就最好在 CE 文档中进行记录以避免重复.

配置设置包括：

  1. 触及config/配置文件的设置.
  2. NGINX 设置和lib/support/中的设置通常.

如果有要执行的步骤列表，通常需要编辑配置文件并重新配置/重新启动 GitLab. 在这种情况下，请按照以下样式作为指导：

  1. **For Omnibus installations**
  2.  1. Edit `/etc/gitlab/gitlab.rb`:
  4.    ```ruby
  5.    external_url "https://gitlab.example.com"

1. Save the file and reconfigure GitLab for the changes to take effect.

For installations from source

  1. Edit config/gitlab.yml:

    1. gitlab:
    2.  host: "gitlab.example.com"
  2. Save the file and restart GitLab for the changes to take effect. ```

在这种情况下：

  • 在每个步骤列表之前，安装方法以粗体声明.
  • 三个破折号（ --- ）用于创建水平线并将两种方法分开.
  • 代码块在列表项下缩进一个或多个空格以正确呈现.
  • 代码块中的每个配置使用不同的突出显示语言.
  • GitLab 重新启动部分用于说明 GitLab 所需的重新启动/重新配置.

Troubleshooting

对于疑难解答部分，您应该提供尽可能多的上下文，以便用户可以识别自己面临的问题并自行解决. 您可以通过确保故障排除内容解决以下问题来简化此操作：

  1. 用户需要解决的问题.
  2. 用户如何确认他们有问题.
  3. 用户可以采取的解决问题的步骤.

如果可以将所有类别的内容汇总在一行中，并且不需要步骤列表，请考虑设置一个带有” 问题 |标题”的表 . 原因 解决方案 （或解决方法（如果此修复程序是临时的））或错误消息 | 解决方法 .

Feature flags

了解如何记录标记后部署的功能 . 有关使用功能标记开发 GitLab 的指导，请参阅GitLab 开发中的功能标记 .

API

这是必备物品清单. 按照本文档中出现的确切顺序使用它们. 下面给出进一步的解释.

  • Every method must have the REST API request. For example:

    1. GET /projects/:id/repository/branches

  • 每个方法都必须对参数进行详细说明 .

  • 每个方法都必须有一个 cURL 示例.
  • 每个方法都必须具有响应主体（JSON 格式）.

API topic template

以下内容可以用作入门模板：

  1. ## Descriptive title
  3. One or two sentence description of what endpoint does.
  5. ```plaintext METHOD /endpoint
Attribute Type Required Description
attribute datatype yes/no Detailed description.
attribute datatype yes/no Detailed description.

Example request:

```shell curl —header “PRIVATE-TOKEN: “ ‘https://gitlab.example.com/api/v4/endpoint?parameters‘

  2. Example response:
  4. ```json [  {  }  ]
  2. ### Fake user information[](#fake-user-information "Permalink")
  4. 您可能需要演示包含用户名和电子邮件地址的 API 调用或 cURL 命令. 不要在 API 调用中使用真实的用户信息：
  6. *   **电子邮件地址** ：使用以`example.com`结尾的电子邮件地址.
  7. *   **名称** ：使用`Example Username` **名之类的**字符串. 或者，使用具有常用姓氏的各种或非性别名称，例如`Sidney Jones` ， `Zhang Wei` . 或`Maria Garcia` .
  9. ### Fake URLs[](#fake-urls "Permalink")
  11. 在文档中包含示例 URL 时，请使用：
  13. *   域名通用时为`example.com` .
  14. *   `gitlab.example.com`指 GitLab 的自我管理的实例时.
  16. ### Fake tokens[](#fake-tokens "Permalink")
  18. 有时可能需要令牌来证明使用 cURL 或 CI 中使用的变量进行 API 调用. 强烈建议不要在文档中使用真实令牌，即使令牌被利用的可能性很低.
  20. 您可以使用以下伪造的令牌作为示例.
  22. | 代币类型 | 代币价值 |
  23. | --- | --- |
  24. | 私人用户令牌 | `<your_access_token>` |
  25. | 个人访问令牌 | `n671WNGecHugsdEDPsyo` |
  26. | 申请编号 | `2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6` |
  27. | 应用机密 | `04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df` |
  28. | 可变 CI / CD | `Li8j-mLUVA3eZYjPfd_H` |
  29. | 特定跑步者令牌 | `yrnZW46BrtBFqM7xDzE7dddd` |
  30. | 共享亚军令牌 | `6Vk7ZsosqQyfreAxXTZr` |
  31. | 触发令牌 | `be20d8dcc028677c931e04f3871a9b` |
  32. | Webhook 秘密令牌 | `6XhDroRcYPM5by_h-HLY` |
  33. | 健康检查令牌 | `Tu7BgjR9qeZTEyRzGG2P` |
  34. | 请求个人资料令牌 | `7VgpS4Ax5utVD2esNstz` |
  36. ### Method description[](#method-description "Permalink")
  38. 使用下表标题来描述方法. 属性应始终位于使用反引号（ ``` ）的代码块中.
Attribute Type Required Description 
  2. 渲染示例：
  4. | Attribute | Type | Required | Description |
  5. | --- | --- | --- | --- |
  6. | `user` | string | yes | GitLab 用户名 |
  8. ### cURL commands[](#curl-commands "Permalink")
  10. *   使用`https://gitlab.example.com/api/v4/`作为端点.
  11. *   在需要的地方使用此个人访问令牌： `<your_access_token>` .
  12. *   始终将请求放在第一位. `GET`是默认设置，因此您不必包含它.
  13. *   将该网址用双引号（ `"` ）引起来.
  14. *   最好使用使用个人访问令牌的示例，并且不要传递用户名和密码的数据.
  16. | Methods | Description |
  17. | --- | --- |
  18. | `--header "PRIVATE-TOKEN: <your_access_token>"` | 每当需要身份验证时，请按原样使用此方法 |
  19. | `--request POST` | 创建新对象时使用此方法 |
  20. | `--request PUT` | 更新现有对象时使用此方法 |
  21. | `--request DELETE` | 删除现有对象时使用此方法 |
  23. ### cURL Examples[](#curl-examples "Permalink")
  25. 以下是一组可以在 API 文档中使用的[cURL](https://curl.haxx.se)示例.
  27. #### Simple cURL command[](#simple-curl-command "Permalink")
  29. 获取组的详细信息：

curl —header “PRIVATE-TOKEN: “ https://gitlab.example.com/api/v4/groups/gitlab-org 

  2. #### cURL example with parameters passed in the URL[](#curl-example-with-parameters-passed-in-the-url "Permalink")
  4. 在经过身份验证的用户的名称空间下创建一个新项目：

curl —request POST —header “PRIVATE-TOKEN: “ “https://gitlab.example.com/api/v4/projects?name=foo“ 

  2. #### Post data using cURL’s `--data`[](#post-data-using-curls---data "Permalink")
  4. 您可以使用 cURL 的`--data`选项，而不是使用`--request POST`并将参数附加到 URI. 下面的示例将在经过身份验证的用户的名称空间下创建一个新项目`foo` .

curl —data “name=foo” —header “PRIVATE-TOKEN: “ “https://gitlab.example.com/api/v4/projects“ 

  2. #### Post data using JSON content[](#post-data-using-json-content "Permalink")
  4. > **注意：**在此示例中，我们创建一个新组. 仔细观察单引号和双引号.

curl —request POST —header “PRIVATE-TOKEN: “ —header “Content-Type: application/json” —data ‘{“path”: “my-group”, “name”: “My group”}’ https://gitlab.example.com/api/v4/groups 

  2. #### Post data using form-data[](#post-data-using-form-data "Permalink")
  4. 除了使用 JSON 或 urlencode 外，您还可以使用 multipart / form-data 来正确处理数据编码：

curl —request POST —header “PRIVATE-TOKEN: “ —form “title=ssh-key” —form “key=ssh-rsa AAAAB3NzaC1yc2EA…” https://gitlab.example.com/api/v4/users/25/keys 

  2. 上面的示例由管理员运行，并将向用户帐户添加名为`ssh-key`的 SSH 公共密钥，其 ID 为 25.
  4. #### Escape special characters[](#escape-special-characters "Permalink")
  6. 空格或斜杠（ `/` ）有时可能会导致错误，因此建议在可能的情况下转义它们. 在下面的示例中，我们创建了一个新问题，该问题的标题中包含空格. 观察如何使用 ASCII 代码对空格进行转义.

curl —request POST —header “PRIVATE-TOKEN: “ “https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude“ 

  2. 将`/`用作斜杠（ `/` ）.
  4. #### Pass arrays to API calls[](#pass-arrays-to-api-calls "Permalink")
  6. GitLab API 有时会接受字符串或整数数组. 例如，要在请求项目用户列表时排除特定用户，您可以执行以下操作：

curl —request PUT —header “PRIVATE-TOKEN: “ —data “skip_users[]=“ —data “skip_users[]=“ https://gitlab.example.com/api/v4/projects//users ```