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