句法
- 段落
- 文本格式
- 属性
- 链接
- 锚点
- 列表
  - 无序
  - 有序
  - 清单
  - 标注
  - 描述
- 文档结构
  - Header
  - Sections
  - Includes
- Blocks
- Tables
- Colors
- 方程式和公式（STEM）
- 图表和流程图
  - Mermaid
  - Kroki
  - PlantUML
- Breaks

AsciiDoc

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

句法

这是最常用的 AsciiDoc 语法的简要参考。您可以在 https://asciidoctor.org/docs/ 找到 AsciiDoc 语法的完整文档。

段落

A normal paragraph.
Line breaks are not preserved.

行注释，即以 // 开头的行，将被跳过：

// this is a comment

一个空行分隔段落。

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

[%hardbreaks]
This paragraph carries the `hardbreaks` option.
Notice how line breaks are now preserved.

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

 This literal paragraph is indented with one space.
 As a consequence, *text formatting*, spaces,
 and lines breaks will be preserved.

提示段落抓住了读者的注意力：

NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs/.
TIP: Lists can be indented. Leading whitespace is not significant.

文本格式

受限制（应用于单词边界）

*strong importance* (aka bold)
_stress emphasis_ (aka italic)
`monospaced` (aka typewriter text)
"`double`" and '`single`' typographic quotes
+passthrough text+ (substitutions disabled)
`+literal text+` (monospaced with substitutions disabled)

不受约束（适用于任何地方）

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

替换

A long time ago in a galaxy far, far away...
(C) 1976 Arty Artisan
I believe I shall--no, actually I won't.

宏

// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements
The European icon:flag[role=blue] is blue & contains pass:[************] arranged in a icon:circle-o[role=yellow].
The pass:c[->] operator is often referred to as the stabby lambda.
Since `pass:[++]` has strong priority in AsciiDoc, you can rewrite pass:c,a,r[C++ => C{pp}].
// activate stem support by adding `:stem:` to the document header
stem:[sqrt(4) = 2]

属性

用户定义的属性

// define attributes in the document header
:name: value

:url-gem: https://rubygems.org/gems/asciidoctor

You can download and install Asciidoctor {asciidoctor-version} from {url-gem}.
C{pp} is not required, only Ruby.
Use a leading backslash to output a word enclosed in curly braces, like \{name}.

环境属性

极狐GitLab 设置以下环境属性：

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

链接

https://example.org/page[A webpage]
link:../path/to/file.txt[A local file]
xref:document.adoc[A sibling document]
mailto:hello@example.org[Email to say hello!]

锚点

[[idname,reference text]]
// or written using normal block attributes as `[#idname,reftext=reference text]`
A paragraph (or any block) with an anchor (aka ID) and reftext.

See <<idname>> or <<idname,optional text of internal link>>.

xref:document.adoc#idname[Jumps to anchor in another document].

This paragraph has a footnote.footnote:[This is the text of the footnote.]

列表

无序

* level 1
** level 2
*** level 3
**** level 4
***** level 5
* back at level 1
+
Attach a block or paragraph to a list item using a list continuation (which you can enclose in an open block).

.Some Authors
[circle]
- Edgar Allen Poe
- Sheri S. Tepper
- Bill Bryson

有序

. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3

.Remember your Roman numerals?
[upperroman]
. is one
. is two
. is three

清单

* [x] checked
* [ ] not checked

标注

// enable callout bubbles by adding `:icons: font` to the document header
[,ruby]
----
puts 'Hello, World!' # <1>
----
<1> Prints `Hello, World!` to the console.

描述

first term:: description of first term
second term::
description of second term

文档结构

= Document Title
Author Name <author@example.org>
v1.0, 2019-01-01

Sections

= Document Title (Level 0)
== Level 1
=== Level 2
==== Level 3
===== Level 4
====== Level 5
== Back at Level 1

Includes

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

include::basics.adoc[]

// define -a allow-uri-read to allow content to be read from URI
include::https://example.org/installation.adoc[]

为了保证良好的系统性能并防止恶意文档引起问题，极狐GitLab 对任何一个文档中处理的包含指令的数量实施了最大限制。您最多可以包含 32 个文档，其中包括传递依赖项。

Blocks

--
open - a general-purpose content wrapper; useful for enclosing content to attach to a list item
--

// recognized types include CAUTION, IMPORTANT, NOTE, TIP, and WARNING
// enable admonition icons by setting `:icons: font` in the document header
[NOTE]
====
admonition - a notice for the reader, ranging in severity from a tip to an alert
====

====
example - a demonstration of the concept being documented
====

.Toggle Me
[%collapsible]
====
collapsible - these details are revealed by clicking the title
====

****
sidebar - auxiliary content that can be read independently of the main content
****

....
literal - an exhibit that features program output
....

----
listing - an exhibit that features program input, source code, or the contents of a file
----

[,language]
----
source - a listing that is embellished with (colorized) syntax highlighting
----

\```language
fenced code - a shorthand syntax for the source block
\```

[,attribution,citetitle]
____
quote - a quotation or excerpt; attribution with title of source are optional
____

[verse,attribution,citetitle]
____
verse - a literary excerpt, often a poem; attribution with title of source are optional
____

++++
pass - content passed directly to the output document; often raw HTML
++++

// activate stem support by adding `:stem:` to the document header
[stem]
++++
x = y^2
++++

////
comment - content which is not included in the output document
////

Tables

.Table Attributes
[cols=>1h;2d,width=50%,frame=topbot]
|===
| Attribute Name | Values

| 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
|===

Colors

可以使用颜色指示器呈现以 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) 表达式，请将文档标题中的 stem 属性设置为 latexmath。使用 KaTeX 呈现方程和公式：

:stem: latexmath

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

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

A matrix can be written as stem:[[[a,b\],[c,d\]\]((n),(k))].

图表和流程图

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

Mermaid

引入于 13.3 版本。

更多详情请访问官方页面。如果您不熟悉使用 Mermaid 或需要帮助识别 Mermaid 代码中的问题，Mermaid 实时编辑器是一个有用的创建工具，并解决 Mermaid 图中的问题。

要生成图表或流程图，请在 Mermaid 块中输入您的文本：

[mermaid]
----
graph LR
    A[Square Rect] -- Link text --> B((Circle))
    A --> C(Round Rect)
    B --> D{Rhombus}
    C --> D
----

Kroki

Kroki 支持十几个图表库。为了使 Kroki 在极狐GitLab 中可用，极狐GitLab 管理员需要先启用它。在 Kroki 集成页面中阅读更多内容。

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

AsciiDoc

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

Markdown

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

PlantUML

在 SaaS 上启用了 PlantUML 集成。为了使 PlantUML 在极狐GitLab 的私有化部署实例中可用，极狐GitLab 管理员必须启用它。

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

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

Breaks

// thematic break (aka horizontal rule)
---

// page break
<<<

AsciiDoc

句法

段落

文本格式

属性

链接

锚点

列表

无序

有序

清单

标注

描述

文档结构

Header

Sections

Includes

Blocks

Tables

Colors

方程式和公式（STEM）

图表和流程图

Mermaid

Kroki

PlantUML

Breaks