文档风格指南

文档风格指南定义了GitLab文档中使用的标记结构。检查文档的指导方针一般开发说明。

查看GitLab手册中的写作风格指南。

文本

将长行分开(换行文本)，这使得审查和编辑更容易。中只有双换行符显示为全换行符GitLab减价。80-100个字符是一个很好的行长度
确保文档以正确的方式添加目录并且有一个有用的链接
不要重复信息
简洁明了
除非有合理的理由，否则请按字母顺序添加文档
用美式英语写作
使用单独的空间而不是双空格
在不同的标记之间跳转一行(例如，在每个段落、标题、列表等之后)
在GitLab中大写“G”和“L”
将功能、产品和方法名称大写。例如:GitLab Runner、Geo、Issue Boards、Git、Prometheus、Continuous Integration。

格式化

使用破折号(-)表示无序列表，而不是星号(*）
使用数字1 (1)用于有序列表
使用下划线(＿)用斜体标记单词或文本
使用双星号(**)用粗体标记一个单词或文本
当使用列表时，最好不要以句号结束每一项。如果有多个句子，你可以使用它们，只保留最后一个句子，不带句号

标题

在每个文档中只添加一个H1标题＃在它的开始(当使用降价)。对于副标题，使用# #，# # #等等......
避免在标题中使用数字。数字移动，因此文档锚链接也移动，最终导致死链接。如果你认为在标题中添加数字很有吸引力，请确保至少与合并请求中的人讨论一下
避免使用符号和特殊字符在头。只要有可能，它们应该是简单和简短的文本。
避免添加显示短暂状态的内容。例如，如果一个功能被认为是测试版或实验性的，那么就把这些信息放在注释中，而不是放在标题中。
在介绍新文档时，要注意标题在语法和句法上是否正确。提到以下一个或所有的GitLab成员进行审查:@axil或@marcia。这是为了确保没有错误标题的文档在没有审计的情况下运行，从而防止在纠正后出现死链接和重定向问题
在标题后只留下一个换行符

链接

使用常规的内联链接标记[文本](https://example.com)。它更容易阅读、审查和维护。
如果在同一文档中存在重复多次的链接，则可以使用[文本](标识符)在该部分或文件的底部加上:(标识符):https://example.com，在这种情况下，我们鼓励你也添加替代文本:[标识符]:https://example.com "替代文本"将鼠标悬停在链接上时显示的。
要链接到内部文档，请使用相对链接，而不是完整的url。使用. . /要导航tp高级目录，并始终添加文件名file.md在链接的末尾加上。海事扩展,而不是. html。例如:代替[文本](. . / . . / merge_requests /),使用[文本](. . / . . / merge_requests / index.md)或者,[文本](. . / . . / ci / README.md)，或者，对于锚链接，[文本](. . / . . / ci / README.md #例子)。使用降价扩展是必要的/帮助部分。
要从CE链接到EE-only文档，请使用EE-only文档完整URL。
使用有意义的锚文本。例如，而不是写这样的东西阅读更多关于GitLab问题板的信息[在这里](链接),写阅读更多关于[GitLab Issue Boards](链接)。

图片

将图像放置在名为img /在同一个目录中。海事你正在处理的文件已经定位了。总是在他们的名字前加上他们将要包含在的文档的名字。例如，如果有一个文档名为twitter.md，那么有效的图像名称可以是twitter_login_screen.png。［异常: images for文章应该放在一个叫img下面/ / article_title / img /文章，因此，不需要在文件名前加上文档名称。
图像应该有一个特定的、非通用的名称来区分它们。
所有的文件名都要用小写。
考虑使用PNG图像而不是JPEG。
使用https://tinypng.com/或者类似的工具。
压缩gifhttps://ezgif.com/optimize或者类似的工具。
应该使用映像(仅在必要时)来说明描述一个过程，不是为了取代它。

文档内部:

在文档中使用图像的Markdown方法是:[正确描述图片内容](img/document_image_title.png)
对于图片的内容，一定要使用恰当的描述。这样，当浏览器无法显示图像时，将使用此文本作为替代描述
如果是连续的图片，中间没有多少文字，总是加三个破折号(---)在图像和文本之间创建一条水平线，以获得更好的清晰度
如果标题放在图片的后面，一定要加上三个破折号(---)在图像和标题之间

笔记

注释应该和单词一起引用注意:是大胆的。使用这个表格:
```
> * *注意:* *这是值得注意的。
```
这导致:

注意:这是值得注意的。

如果音符跨越多行，可以将这一行分开。

具体章节和条款

要在GitLab中提及和/或引用特定术语，请遵循以下样式。

GitLab版本和层

每个带有新特性的文档都应该声明该特性引入的GitLab版本。在标题的正下方加注:
```
在GitLab 8.3中引入。
```
如果可能的话，每个特性都应该有一个链接到介绍它的MR、issue或史诗。然后将上述注释转换为:
```
>[引入][ce-1242]在GitLab 8.3
```
，其中链接标识符以存储库(CE)和MR编号命名。
如果该特性只在GitLab企业版中可用，不要忘记提到支付层该功能在:
```
>[引入][ee-1234]在[GitLab Starter](https://about.gitlab.com/products/) 8.3。
```
否则，不要提及这一点。

产品徽章

当某个特性在EE-only层中可用时，根据该特性的可用性添加相应的层:

对于GitLab Starter和GitLab.com Bronze:* * * *(启动)
GitLab高级版和GitLab.com银版:* *(溢价)* *
对于GitLab Ultimate和GitLab.com Gold:* *[最终]* *
对于GitLab核心和GitLab.com免费:* * * *(核心)

要排除GitLab.com的层级(当该功能在GitLab.com中不可用时)，添加关键字“only”:

对于GitLab初学者:* *(起动器只)* *
对于GitLab高级版:* *(只溢价)* *
对于GitLab Ultimate:* *(最终只)* *
对于GitLab Core:* *(核心只有)* *

理想情况下，应该将该层添加到标题中，以便显示完整的徽章。但它也可以从段落、列表项和表格单元格中提到。对于这些情况，提到的层级将用一个橙色问号表示。例如,* * * *(启动)呈现(启动)，* *(起动器只)* *呈现(只起动器)。

没有提到层级意味着该功能在GitLab Core、GitLab.com Free和更高的层级中可用。

它是如何工作的

引入的244年!，特殊标记* * * *(启动)会产生一个跨度元素来触发徽章和工具提示()。当添加关键字“only”时，将不显示相应的GitLab.com徽章。

GitLab重启

在许多情况下，需要重新启动/重新配置GitLab。为避免重复，请链接到可在中找到的特殊文件doc /政府/ restart_gitlab.md。通常文本是这样的:

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

如果您正在编辑的文档驻留在GitLab CE/EE以外的地方文档/目录，而不是相对链接，使用完整路径:http://docs.gitlab.com/ce/administration/restart_gitlab.html。取代重新配置与重新启动在适当的地方。

安装指南

Ruby:在安装指南步骤2，我们从源代码安装Ruby。每当有需要更新的新版本时，请记住在整个代码块中更改它，并替换sha256sum(可以在下载页面(Ruby网站)。

源代码和Omnibus安装的配置文档

GitLab目前正式支持两种安装方法:从源代码安装和Omnibus包安装。

当存在两种安装方法都可配置的设置时，最好将其记录在CE文档中，以避免重复。

配置设置包括:

中的配置文件的设置配置/
NGINX的设置和设置lib /支持/在一般情况下

当需要执行一系列步骤时，通常需要编辑配置文件并重新配置/重启GitLab。在这种情况下，遵循下面的样式作为指导:

**用于综合装置**1.编辑“/ etc / gitlab / gitlab.rb”：““鲁比external_url“https://gitlab.example.com”' ' '1.保存文件并［重新配置]GitLab，使更改生效。---**从源代码**安装1.编辑“配置/ gitlab.yml”：“‘yamlgitlab:主持人:“gitlab.example.com”' ' '1.保存文件并［重新启动]GitLab，使更改生效。［重新配置]：/ /政府/ restart_gitlab.md # omnibus-gitlab-reconfigure路径［重新启动]：/ /政府/ restart_gitlab.md # installations-from-source路径

在这种情况下:

在每个步骤列表之前，以粗体声明安装方法
三个破折号(---)用于创建一条水平线并将两个方法分开
代码块在列表项下缩进一个或多个空格以正确呈现
代码块中的每个配置使用不同的高亮显示语言
的参考文献向导用于重新配置/重启

假令牌

有时可能需要一个令牌来演示使用cURL或CI中使用的秘密变量的API调用。强烈建议不要在文档中使用真正的令牌，即使令牌被利用的可能性很低。

您可以使用以下伪令牌作为示例。

令牌类型	令牌值
私有用户令牌	`9 koxpg98eahejpvbs5tk`
个人访问令牌	`n671WNGecHugsdEDPsyo`
应用程序ID	`2 fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6`
应用程序的秘密	`04 f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df`
秘密CI变量	`Li8j-mLUVA3eZYjPfd_H`
特定的Runner令牌	`yrnZW46BrtBFqM7xDzE7dddd`
共享跑者令牌	`6 vk7zsosqqyfreaxxtzr`
触发令牌	`be20d8dcc028677c931e04f3871a9b`
Webhook秘密令牌	`6 xhdrorcypm5by_h-hly`
健康检查令牌	`Tu7BgjR9qeZTEyRzGG2P`
请求配置文件令牌	`7 vgps4ax5utvd2esnstz`

API

以下是必备物品清单。按照本文档中显示的顺序使用它们。下文将作进一步解释。

每个方法都必须有REST API请求。例如:
```
/项目/:id /仓库/分支机构
```
每一种方法都必须有详细的参数说明。
每个方法都必须有一个cURL示例。
每个方法都必须有一个响应体(JSON格式)。

方法描述

使用下面的表头来描述这些方法。属性应该总是在代码块中使用反引号(｀)。

|属性|类型|必选|描述|| --------- | ---- | -------- | ----------- |

呈现的例子:

属性	类型	要求	描述
`用户`	字符串	是的	GitLab用户名

cURL命令

使用https://gitlab.example.com/api/v4/作为终点。
在任何需要的地方使用这个个人访问令牌:9 koxpg98eahejpvbs5tk。
永远把要求放在第一位。得到是默认值，因此您不必包含它。
当URL包含其他参数时，请对其使用双引号。
更喜欢使用使用个人访问令牌的示例，不要传递用户名和密码的数据。

方法	描述
`-H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK"`	只要需要身份验证，就按原样使用此方法
`- x的帖子`	在创建新对象时使用此方法
`- x将`	在更新现有对象时使用此方法
`- x删除`	在删除现有对象时使用此方法

旋度的例子

下面是一组旋度您可以在API文档中使用的示例。

简单cURL命令

获取组的详细信息:

旋度——头“PRIVATE-TOKEN: 9 koxpg98eahejpvbs5tk”https://gitlab.example.com/api/v4/groups/gitlab-org

cURL示例，在URL中传递参数

在认证用户的命名空间下创建一个新项目:

旋度——请求帖子——头“PRIVATE-TOKEN: 9 koxpg98eahejpvbs5tk”“https://gitlab.example.com/api/v4/projects?name=foo”

使用cURL的——data发布数据

而不是使用- x的帖子并将参数附加到URI中，您可以使用cURL的——数据选择。下面的示例将创建一个新项目喷火在经过身份验证的用户的名称空间下。

旋度——数据“name = foo”——头“PRIVATE-TOKEN: 9 koxpg98eahejpvbs5tk”“https://gitlab.example.com/api/v4/projects”

使用JSON内容发布数据

注意:在本例中，我们创建一个新组。仔细观察单引号和双引号。

旋度——请求帖子——头“PRIVATE-TOKEN: 9 koxpg98eahejpvbs5tk”——头“application / json内容类型:——数据'{"path": "My -group"， "name": "My group"}'https://gitlab.example.com/api/v4/groups

使用表单数据发布数据

而不是使用JSON或urlencode，你可以使用multipart/form-data正确处理数据编码:

旋度——请求帖子——头“PRIVATE-TOKEN: 9 koxpg98eahejpvbs5tk”——形式“标题= ssh密钥”——形式“关键=将AAAAB3NzaC1yc2EA……”https://gitlab.example.com/api/v4/users/25/keys

上面的示例由一个管理员运行，它将向id为25的用户帐户添加一个名为SSH -key的SSH公钥。

转义特殊字符

空格或斜杠(/)有时可能导致错误，因此建议在可能的情况下对它们进行转义。在下面的示例中，我们创建了一个标题中包含空格的新问题。观察空格是如何使用% 20ASCII代码。

旋度——请求帖子——头“PRIVATE-TOKEN: 9 koxpg98eahejpvbs5tk”“https://gitlab.example.com/api/v4/projects/42/issues?title=Hello%20Dude”

使用% 2 f对于斜杠(/)。

将数组传递给API调用

GitLab API有时接受字符串或整数数组。例如，将GitLab实例的注册电子邮件域限制为* .example.com和example.net，你会这样做:

旋度——请求把——头“PRIVATE-TOKEN: 9 koxpg98eahejpvbs5tk”——数据“domain_whitelist [] = * .example.com "——数据“domain_whitelist [] = example.net”https://gitlab.example.com/api/v4/application/settings