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

AsciiDoc

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

GitLab 使用 Asciidoctor gem 将 AsciiDoc 内容转换为 HTML5。 完整的 Asciidoctor 参考请查阅 Asciidoctor 用户手册。

你可以在以下区域使用 AsciiDoc：

  • Wiki 页面
  • 仓库中的 AsciiDoc 文档（.adoc 或 .asciidoc）

段落

这是一个普通段落。
换行符不会被保留。

以 // 开头的行注释会被跳过：

// 这是一个注释

空行分隔段落。

带有 [%hardbreaks] 选项的段落会保留换行符：

[%hardbreaks]
这个段落带有 `hardbreaks` 选项。
注意换行符现在被保留了。

缩进（字面）段落会禁用文本格式化， 保留空格和换行符，并以 等宽字体显示：

 这个字面段落缩进了一个空格。
 因此，*文本格式化*、空格
 和换行符都会被保留。

注意段落会吸引读者的注意力：

  • NOTE: 这是一个简短参考，完整文档请访问 https://asciidoctor.org/docs/。
  • TIP: 列表可以缩进。前导空格没有意义。

文本格式化

  • 受限（应用于词边界）：

    *重要强调*（即粗体）
_斜体强调_（即斜体）
`等宽字体`（即打字机文本）
"`双引号`" 和 '`单引号`' 引号
+直通文本+（禁用替换）
`+字面文本+`（禁用替换的等宽字体）

  • 不受限（应用于任何位置）：

    **C**reate+**R**ead+**U**pdate+**D**elete
fan__freakin__tastic
``mono``culture

  • 替换：

    很久很久以前，在遥远的银河系...
(C) 1976 Arty Artisan
我想我应该——不，实际上我不会。

  • 宏：

    // 其中 c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements
欧洲图标:flag[role=blue] 是蓝色的 & 包含 pass:[************] 以 icon:circle-o[role=yellow] 排列。
pass:c[->] 操作符通常被称为刺入式 lambda。
由于 `pass:[++]` 在 AsciiDoc 中具有强优先级，你可以重写 pass:c,a,r[C++ => C{pp}]。
// 通过在文档头部添加 `:stem:` 启用 stem 支持
stem:[sqrt(4) = 2]

链接

https://example.org/page[一个网页]
link:../path/to/file.txt[一个本地文件]
xref:document.adoc[一个同级文档]
mailto:hello@example.org[发送问候的邮件！]

锚点

[[idname,参考文本]]
// 或者使用常规块属性写成 `[#idname,reftext=参考文本]`
一个带有锚点（即 ID）和参考文本的段落（或任何块）。

参见 <<idname>> 或 <<idname,内部链接的可选文本>>。

xref:document.adoc#idname[跳转到另一个文档中的锚点]。

这个段落有一个脚注。footnote:[这是脚注的文本。]

列表

无序列表

* 第 1 级
** 第 2 级
*** 第 3 级
**** 第 4 级
***** 第 5 级
* 回到第 1 级
+
使用列表延续符（可以包含在开放块中）将块或段落附加到列表项。

. 一些作者
[circle]
- Edgar Allen Poe
- Sheri S. Tepper
- Bill Bryson

有序列表

. 步骤 1
. 步骤 2
.. 步骤 2a
.. 步骤 2b
. 步骤 3

. 还记得罗马数字吗？
[upperroman]
. 是一
. 是二
. 是三

检查清单

* [x] 已勾选
* [ ] 未勾选

标注

// 通过在文档头部添加 `:icons: font` 启用标注气泡
[,ruby]
----
puts 'Hello, World!' # <1>
----
<1> 在控制台打印 `Hello, World!`。

描述列表

第一个术语:: 第一个术语的描述
第二个术语::
第二个术语的描述

标题

= 文档标题
作者名称 <author@example.org>
v1.0, 2019-01-01

章节

= 文档标题（第 0 级）
== 第 1 级
=== 第 2 级
==== 第 3 级
===== 第 4 级
====== 第 5 级
== 回到第 1 级

包含

使用 AsciiDoc 格式创建的 Wiki 页面 会以 .asciidoc 文件扩展名保存。 在使用 AsciiDoc Wiki 页面时，将文件名从 .adoc 更改为 .asciidoc。

include::basics.adoc[]
// 你也可以包含仓库中的其他文件
[,language]
----
include::my_code_file.language[]
----

为保证良好的系统性能并防止恶意文档造成问题， GitLab 对任何单个文档中处理的包含指令数量设置了最大限制。 默认情况下，一个文档最多可以有 32 个包含指令，这包括传递依赖。 要自定义处理的包含指令数量，使用 应用设置 API 更改应用设置 asciidoc_max_includes。

asciidoc_max_includes 当前允许的最大值是 64。 如果值过高，在某些情况下可能会导致性能问题。

要使用来自单独页面或外部 URL 的包含，在 应用设置 中启用 allow-uri-read。

// 将应用设置 allow-uri-read 定义为 true 以允许从 URI 读取内容
include::https://example.org/installation.adoc[]

属性

用户定义

// 在文档头部定义属性
:name: 值
:url-gem: https://rubygems.org/gems/asciidoctor

你可以从 {url-gem} 下载并安装 Asciidoctor {asciidoctor-version}。
C{pp} 不是必需的，只需要 Ruby。
使用反斜杠输出包含在花括号中的单词，如 \{name}。

环境属性

GitLab 设置以下环境属性：

属性名 描述
docname 源文档的根名称（无前导路径或文件扩展名）。
outfilesuffix 对应后端输出的文件扩展名（默认为 .adoc 以使文档间交叉引用正常工作）。

块

--
开放块 - 一个通用内容包装器；适合包含要附加到列表项的内容
--
// 识别的类型包括 CAUTION, IMPORTANT, NOTE, TIP, 和 WARNING
// 通过在文档头部设置 `:icons: font` 启用注意图标
[NOTE]
====
注意 - 给读者的通知，严重程度从提示到警告不等
====
====
示例 - 所记录概念的演示
====
切换我
[%collapsible]
====
可折叠 - 点击标题会显示这些详细信息
====
****
侧边栏 - 可以独立于主要内容阅读的辅助内容
****
....
字面块 - 展示程序输出的展示块
....
----
列表 - 展示程序输入、源代码或文件内容的展示块
----
[,language]
----
源代码 - 带有（彩色）语法高亮的列表
----
围栏代码块 - 源块的一种简写语法
[,attribution,citetitle]
____
引用 - 引用或摘录；来源的归属和标题是可选的
____
[verse,attribution,citetitle]
____
诗歌 - 文学摘录，通常是诗歌；来源的归属和标题是可选的
____
++++
直通 - 直接传递到输出文档的内容；通常是原始 HTML
++++
// 通过在文档头部添加 `:stem:` 启用 stem 支持
[stem]
++++
x = y^2
++++
////
注释 - 不包含在输出文档中的内容
////

表格

.表格属性
[cols=>1h;2d,width=50%,frame=topbot]
|===
| 属性名 | 值

| options
| header,footer,autowidth

| cols
| colspec[;colspec;...]

| grid
| all \| cols \| rows \| none

| frame
| all \| sides \| topbot \| none

| stripes
| all \| even \| odd \| none

| width
| (0%..100%)

| format
| psv {vbar} csv {vbar} dsv
|===

颜色

可以用 HEX、RGB 或 HSL 格式编写颜色，并带有颜色指示器进行渲染。 支持的格式（不支持命名颜色）：

  • HEX: `#RGB[A]` 或 `#RRGGBB[AA]`
  • RGB: `RGB[A](R, G, B[, A])`
  • HSL: `HSL[A](H, S, L[, A])`

反引号内的颜色后面会跟一个颜色"芯片"：

- `#F00`
- `#F00A`
- `#FF0000`
- `#FF0000AA`
- `RGB(0,255,0)`
- `RGB(0%,100%,0%)`
- `RGBA(0,255,0,0.3)`
- `HSL(540,70%,50%)`
- `HSLA(540,70%,50%,0.3)`

方程和公式

如果需要包含科学、技术、工程和数学（STEM）表达式， 在文档头部将 stem 属性设置为 latexmath。 方程和公式使用 KaTeX 渲染：

:stem: latexmath

latexmath:[C = \alpha + \beta Y^{\gamma} + \epsilon]

[stem]
++++
sqrt(4) = 2
++++

矩阵可以写成 stem:[[[a,b\],[c,d\]\]((n),(k))].

图表和流程图

可以在 GitLab 中使用 Mermaid 或 PlantUML 从文本生成图表和流程图。

Mermaid

更多详细信息请访问 官方页面。 如果你刚开始使用 Mermaid 或需要帮助识别 Mermaid 代码中的问题， Mermaid Live Editor 是一个创建和解决 Mermaid 图形问题的有用工具。

要生成图表或流程图，在 mermaid 块中输入你的文本：

[mermaid]
----
graph LR
    A[方形矩形] -- 链接文本 --> B((圆形))
    A --> C(圆角矩形)
    B --> D{菱形}
    C --> D
----

Kroki

Kroki 支持十多种图表库。 要在 GitLab 中启用 Kroki，GitLab 管理员需要先启用它。 更多信息请参阅 Kroki 集成 页面。

启用 Kroki 后，你可以在 AsciiDoc 和 Markdown 文档中创建图表。 这是一个使用 GraphViz 图表的示例：

  • AsciiDoc：

    [graphviz]
....
digraph G {
  Hello->World
}
....

  • Markdown：

    ```graphviz
digraph G {
  Hello->World
}
```

PlantUML

PlantUML 集成已在 GitLab.com 上启用。 要在 GitLab 自托管版本中启用 PlantUML，GitLab 管理员 必须启用它。

启用 PlantUML 后，在 plantuml 块中输入你的文本：

[plantuml]
----
Bob -> Alice : hello
----

要包含存储在单独文件中的 PlantUML 图表：

[plantuml, format="png", id="myDiagram", width="200px"]
----
include::diagram.puml[]
----

多媒体

image::screenshot.png[块图像,800,450]

按 image:reload.svg[重新加载,16,opts=interactive] 重新加载页面。

video::movie.mp4[width=640,start=60,end=140,options=autoplay]

GitLab 不支持在 AsciiDoc 内容中嵌入 YouTube 和 Vimeo 视频。 使用标准 AsciiDoc 链接：

https://www.youtube.com/watch?v=BlaZ65-b7y0[视频的链接文本]

分隔符

// 主题分隔符（即水平线）
---
// 分页符
<<<

目录

= 文档标题（第 0 级）
:toc:
:toclevels: 3
:toc-title: 目录

== 第 1 级
=== 第 2 级
==== 第 3 级
===== 第 4 级
====== 第 5 级
== 回到第 1 级

:toc-class:、:toc: left 和 :toc: right 属性不受支持。