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/.
  2. 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
  2. You can download and install Asciidoctor {asciidoctor-version} from {url-gem}.
  3. C{pp} is not required, only Ruby.
  4. 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.
  4. See <<idname>> or <<idname,optional text of internal link>>.
  5. xref:document.adoc#idname[Jumps to anchor in another document].
  6. 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).
  9. .Some Authors
  10. [circle]
  11. - Edgar Allen Poe
  12. - Sheri S. Tepper
  13. - Bill Bryson

Ordered

  1. . Step 1
  2. . Step 2
  3. .. Step 2a
  4. .. Step 2b
  5. . Step 3
  6. .Remember your Roman numerals?
  7. [upperroman]
  8. . is one
  9. . is two
  10. . 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[]
  2. // define -a allow-uri-read to allow content to be read from URI
  3. 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 ////

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

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

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

// thematic break (aka horizontal rule)

// page break <<< ```