AsciiDoc

原文：https://docs.gitlab.com/ee/user/asciidoc.html

AsciiDoc

GitLab 使用Asciidoctor gem 将 AsciiDoc 内容转换为 HTML5. 有关完整的 Asciidoctor 参考，请查阅《 Asciidoctor 用户手册 》.

Syntax

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

Paragraphs

  1. A normal paragraph.
  2. Line breaks are not preserved.

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

  1. // this is a comment

空白行分隔段落.

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

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

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

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

一条警告段落引起了读者的注意：

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

Text Formatting

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

  1. *strong importance* (aka bold)
  2. _stress emphasis_ (aka italic)
  3. `monospaced` (aka typewriter text)
  4. "`double`" and '`single`' typographic quotes
  5. +passthrough text+ (substitutions disabled)
  6. `+literal text+` (monospaced with substitutions disabled)

不受限制（适用于任何地方）

  1. **C**reate+**R**ead+**U**pdate+**D**elete
  2. fan__freakin__tastic
  3. ``mono``culture

Replacements

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

Macros

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

Attributes

用户定义的属性

  1. // define attributes in the document header
  2. :name: value
  1. :url-gem: https://rubygems.org/gems/asciidoctor
  3. You can download and install Asciidoctor {asciidoctor-version} from {url-gem}.
  4. C{pp} is not required, only Ruby.
  5. Use a leading backslash to output a word enclosed in curly braces, like \{name}.

环境属性

GitLab 设置以下环境属性：

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

Links

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

Anchors

  1. [[idname,reference text]]
  2. // or written using normal block attributes as `[#idname,reftext=reference text]`
  3. A paragraph (or any block) with an anchor (aka ID) and reftext.
  5. See <<idname>> or <<idname,optional text of internal link>>.
  7. xref:document.adoc#idname[Jumps to anchor in another document].
  9. This paragraph has a footnote.footnote:[This is the text of the footnote.]

Lists

Unordered

  1. * level 1
  2. ** level 2
  3. *** level 3
  4. **** level 4
  5. ***** etc.
  6. * back at level 1
  7. +
  8. Attach a block or paragraph to a list item using a list continuation (which you can enclose in an open block).
  10. .Some Authors
  11. [circle]
  12. - Edgar Allen Poe
  13. - Sheri S. Tepper
  14. - Bill Bryson

Ordered

  1. . Step 1
  2. . Step 2
  3. .. Step 2a
  4. .. Step 2b
  5. . Step 3
  7. .Remember your Roman numerals?
  8. [upperroman]
  9. . is one
  10. . is two
  11. . is three

Checklist

  1. * [x] checked
  2. * [ ] not checked

Callout

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

Description

  1. first term:: description of first term
  2. second term::
  3. description of second term

Document Structure

Header

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

Sections

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

Includes

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

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

Blocks

  1. --
  2. open - a general-purpose content wrapper; useful for enclosing content to attach to a list item
  3. --
  1. // recognized types include CAUTION, IMPORTANT, NOTE, TIP, and WARNING
  2. // enable admonition icons by setting `:icons: font` in the document header
  3. [NOTE]
  4. ====
  5. admonition - a notice for the reader, ranging in severity from a tip to an alert
  6. ====
  1. ====
  2. example - a demonstration of the concept being documented
  3. ====
  1. .Toggle Me
  2. [%collapsible]
  3. ====
  4. collapsible - these details are revealed by clicking the title
  5. ====
  1. ****
  2. sidebar - auxiliary content that can be read independently of the main content
  3. ****
  1. ....
  2. literal - an exhibit that features program output
  3. ....
  1. ----
  2. listing - an exhibit that features program input, source code, or the contents of a file
  3. ----
  1. [,language]
  2. ----
  3. source - a listing that is embellished with (colorized) syntax highlighting
  4. ----
  1. \```language
  2. fenced code - a shorthand syntax for the source block
  3. \

[,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 ////

  2. ### 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 |===

  2. ### 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]

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

// thematic break (aka horizontal rule)

// page break <<< ```