# AsciiDoc

> 原文：[https://docs.gitlab.com/ee/user/asciidoc.html](https://docs.gitlab.com/ee/user/asciidoc.html)

*   [Syntax](#syntax)
    *   [Paragraphs](#paragraphs)
    *   [Text Formatting](#text-formatting)
    *   [Attributes](#attributes)
    *   [Links](#links)
    *   [Anchors](#anchors)
    *   [Lists](#lists)
        *   [Unordered](#unordered)
        *   [Ordered](#ordered)
        *   [Checklist](#checklist)
        *   [Callout](#callout)
        *   [Description](#description)
    *   [Document Structure](#document-structure)
        *   [Header](#header)
        *   [Sections](#sections)
        *   [Includes](#includes)
    *   [Blocks](#blocks)
    *   [Tables](#tables)
    *   [Multimedia](#multimedia)
    *   [Breaks](#breaks)

# AsciiDoc[](#asciidoc "Permalink")

GitLab 使用[Asciidoctor](https://asciidoctor.org) gem 将 AsciiDoc 内容转换为 HTML5\. 有关完整的 Asciidoctor 参考，请查阅《 [Asciidoctor 用户手册](https://asciidoctor.org/docs/user-manual/) 》.

## Syntax[](#syntax "Permalink")

这是最常用的 AsciiDoc 语法的简要参考. 您可以在[https://asciidoctor.org/docs/上](https://asciidoctor.org/docs/)找到有关 AsciiDoc 语法的完整文档.

### Paragraphs[](#paragraphs "Permalink")

```
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.
```

### Text Formatting[](#text-formatting "Permalink")

**受约束的（应用于单词边界）**

```
*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
```

**Replacements**

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

**Macros**

```
// where c=specialchars, q=quotes, a=attributes, r=replacements, m=macros, p=post_replacements, etc.
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]
```

### Attributes[](#attributes "Permalink")

**用户定义的属性**

```
// 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 设置以下环境属性：

| Attribute | Description |
| --- | --- |
| `docname` | 源文档的根名称（无前导路径或文件扩展名）. |
| `outfilesuffix` | 对应于后端输出的文件扩展名（默认为`.adoc`以使文档间的交叉引用起作用）. |

### Links[](#links "Permalink")

```
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!]
```

### Anchors[](#anchors "Permalink")

```
[[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.]
```

### Lists[](#lists "Permalink")

#### Unordered[](#unordered "Permalink")

```
* level 1
** level 2
*** level 3
**** level 4
***** etc.
* 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
```

#### Ordered[](#ordered "Permalink")

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

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

#### Checklist[](#checklist "Permalink")

```
* [x] checked
* [ ] not checked
```

#### Callout[](#callout "Permalink")

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

#### Description[](#description "Permalink")

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

### Document Structure[](#document-structure "Permalink")

#### Header[](#header "Permalink")

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

#### Sections[](#sections "Permalink")

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

#### Includes[](#includes "Permalink")

```
include::basics.adoc[]

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

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

### Blocks[](#blocks "Permalink")

```
--
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[](#tables "Permalink")

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

### Multimedia[](#multimedia "Permalink")

```
image::screenshot.png[block image,800,450]

Press image:reload.svg[reload,16,opts=interactive] to reload the page.

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

video::aHjpOzsQ9YI[youtube]

video::300817511[vimeo]
```

### Breaks[](#breaks "Permalink")

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

```
// page break
<<<
```