本文翻译自 AsciiDoc Syntax Quick Reference

段落

段落
段落在 AsciiDoc 中不需要任何特殊标记。
段落就是一段或多行连续的文本。

要开始一个新的段落,至少用一个空行隔开它。
查看效果 段落

段落在 AsciiDoc 中不需要任何特殊标记。 段落就是一段或多行连续的文本。

要开始一个新的段落,至少用一个空行隔开它。

文字段落
一个正常的段落。

 一个文字段落。
 可以单行或连续多行,至少有一个空格缩进。

 文本以等宽字体(通常为 monospace)显示。
 行被预格式化(即:在源代码中格式化)
 空 格 和 换行符,
 就像这句话,
 将被保留。
查看效果 文字段落

一个正常的段落。

一个文字段落。
可以单行或连续多行,至少有一个空格缩进。
文本以等宽字体(通常为 monospace)显示。
行被预格式化(即:在源代码中格式化)
空 格 和 换行符,
就像这句话,
将被保留。
硬换行符
玫瑰是红色的, +
紫罗兰是蓝色的。

[%hardbreaks]
Ruby 是红的。
Java 是黑的。
查看效果 硬换行符

玫瑰是红色的,
紫罗兰是蓝色的。

Ruby 是红的。
Java 是黑的。

导语
[.lead]
这段文字将作为开头段落(即,更大的字体)。

这段文字不会。
查看效果 导语

这段文字将作为开头段落(即,更大的字体)。

这段文字不会。

如果在序言的第一段上没有指定任何角色,默认的 Asciidoctor 样式表会自动将该段作为导语。

文本格式

有约束的粗体、斜体、等宽字体
它对我有 *很强* 的意义。

这一点我再 _强调_ 也不为过。

键入 `OK` 以接受

那 *_真的_* 必须走。

不能选择一个?让我们 `*_都_*` 用上。
查看效果 有约束的粗体、斜体、等宽字体

它对我有 很强 的意义。

这一点我再 强调 也不为过。

键入 OK 以接受

真的 必须走。

不能选择一个?让我们 用上。

无约束的粗体、斜体、等宽字体
**C**reate, **R**ead, **U**pdate, and **D**elete (CRUD)

That's fan__freakin__tastic!

Don't pass generic ``Object``s to methods that accept ``String``s!

It was Beatle**__mania__**!
查看效果 无约束的粗体、斜体、等宽字体

Create, Read, Update, and Delete (CRUD)

That’s fanfreakintastic!

Don’t pass generic Objects to methods that accept Strings!

It was Beatlemania!

高亮、下划线、删除线、自定义角色
狼人对 #肉桂# 过敏。

##Mark##up refers to text that contains formatting ##mark##s.

所有的 [.underline]#核心# 都去了哪里?

我们需要 [.line-through]#十个# 二十个虚拟机。

主题必须实现 [.myrole]#自定义角色# 。
查看效果 高亮、下划线、删除线、自定义角色

狼人对 肉桂 过敏。

Markup refers to text that contains formatting marks.

所有的 核心 都去了哪里?

我们需要 十个 二十个虚拟机。

主题必须实现 自定义角色

上标与下标
^上^标短语

~下~标短语
查看效果 上标与下标

标短语

标短语

智能引号和撇号
"`双引号`"

'`单引号`'

Olaf's desk was a mess.

A ``std::vector```'s size is the number of items it contains.

All of the werewolves`' desks were a mess.

Olaf had been with the company since the `'00s.
查看效果 智能引号和撇号

“双引号”

‘单引号’

Olaf’s desk was a mess.

A std::vector’s size is the number of items it contains.

All of the werewolves’ desks were a mess.

Olaf had been with the company since the ’00s.

链接

自动链接、 URL 宏、 mailto 宏
https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]
请参阅 <<_段落>> 了解如何编写段落。

了解如何将文档组织为多个 <<section-titles, 章节>> 。

devel@discuss.example.org

mailto:devel@discuss.example.org[Discuss]

mailto:join@discuss.example.org[Subscribe,Subscribe me,I want to join!]
查看效果 自动链接、 URL 宏、 mailto 宏

Asciidoctor 请参阅 段落 了解如何编写段落。

了解如何将文档组织为多个 章节

带属性的 URL 宏
https://discuss.asciidoctor.org[Discuss Asciidoctor,role=external,window=_blank]

https://discuss.asciidoctor.org[Discuss Asciidoctor^]
查看效果 带属性的 URL 宏
当目标以类似 https: 的 URL 方案开头时,link: 宏前缀不是必须的。 URL 方案充当隐式宏前缀。
如果链接文本包含逗号,并且文本后跟一个或多个命名属性,则必须将文本括在双引号中。 否则,文本将在逗号上切断(其余文本将被拉入属性解析)。
带空格和特殊字符的 URL
link:++https://example.org/?q=[a b]++[URL with special characters]

https://example.org/?q=%5Ba%20b%5D[URL with special characters]
链接到相关文件
link:index.html[Docs]
使用 Windows UNC 路径链接
link:\\server\share\whitepaper.pdf[Whitepaper]
内联锚点
[[bookmark-a]]内联锚点使任意内容可引用。

[#bookmark-b]#内联锚点可以应用于这样的短语。#

anchor:bookmark-c[]使用交叉引用链接到此位置。

[[bookmark-d,最后一段]]xreflabel 属性将用作交叉参考链接中的链接文本。
交叉引用
https://asciidoctor.org - automatic!

https://asciidoctor.org[Asciidoctor]
请参阅 <<_段落>> 了解如何编写段落。

了解如何将文档组织为多个 <<section-titles, 章节>> 。
查看效果 交叉引用

Asciidoctor 请参阅 段落 了解如何编写段落。

了解如何将文档组织为多个 章节

文档间交叉引用
有关更多信息,请参阅 xref:document-b.adoc#section-b[Section B of Document B] 。

如果你从不返回 xref:document-b.adoc[Document B],我们会发送帮助。

文档页眉

文档页眉 是可选的。 页眉不能包含任何空行,且必须用至少一个空行将内容分隔开。

标题
= 文档标题

本文档提供……
标题与作者行
= 文档标题
作者名 <author@email.org>; 作者名 <author@email.org>

本文档提供……
标题、作者行、版次行
= 文档标题
作者名 <author@email.org>
v2.0, 2019-03-22

本文档提供……
没有 作者行 就没有 版次行
带属性的文档页眉
= 文档标题
作者名 <author@email.org>
v2.0, 2019-03-22
:toc:
:homepage: https://example.org

This document provides...

章节标题

当文档类型为 article (默认)时,该文档只能具有一个 0 级标题(=),即章节标题(即,doctitle)。

文章的章节等级
= 文档标题(零级)

== 一级章节标题

=== 二级章节标题

==== 三级章节标题

===== 四级章节标题

====== 五级章节标题

== 另一个一级章节标题
= 参考文档
开发项目负责人

这是项目 X 的文档。

include::basics.adoc[]

include::installation.adoc[]

include::example.adoc[]
查看效果 文章的章节等级

Asciidoctor 请参阅 段落 了解如何编写段落。

了解如何将文档组织为多个 章节

book 类型的文档可以有额外的 0 级章节标题,它们被解释为 。 至少有一部的存在会隐式地使文档成为具有多部的书。

书的章节等级
= 文档标题(零级)

== 一级章节标题

= 零级章节标题(部)

== 一级章节标题

=== 二级章节标题

==== 三级章节标题

===== 四级章节标题

====== 五级章节标题

= 另一个零级章节标题(部)
离散标题(不是章节)
[discrete]
=== 这是一个独立的页眉!

自动 TOC

激活文档的目录
= 文档标题
文档作者 <doc.writer@email.org>
:toc:

可以自定义目录 标题显示章节深度位置

包含

在文档中包含“部”
= 文档标题(零级)

== 一级章节标题

=== 二级章节标题

==== 三级章节标题

===== 四级章节标题

====== 五级章节标题

== 另一个一级章节标题
= 参考文档
开发项目负责人

这是项目 X 的文档。

include::basics.adoc[]

include::installation.adoc[]

include::example.adoc[]
通过 TAG 或行号包含内容
include::filename.txt[tag=definition]

include::filename.txt[lines=5..10]
通过 URL 包含内容

包含来自 URL 的内容有潜在的危险,因此如果安全模式为 SECURE 或更高,将禁用该功能。 假设安全模式小于 SECURE,那么还必须设置 allow-uri-read 属性以允许 AsciiDoc 处理器从 URL 读取内容。

列表

无序列表
* 列表项
** 嵌套列表项
*** 嵌套列表项
* 列表项
** 另一个嵌套列表项
* 列表项
查看效果 无序列表
  • 列表项

    • 嵌套列表项

      • 嵌套列表项

  • 列表项

    • 另一个嵌套列表项

  • 列表项

在列表之前和之后,需要一个空行才能将其与其他块分开。 可以通过在第二个列表上方添加一个空属性列表(即 [])或通过插入空行,然后在第一个列表之后插入注释行来强制分隔两个相邻列表。 如果使用注释行,惯例是使用 //- 向其他作者提供提示,即它是列表分隔线。
无序列表最大级别嵌套
* 一级列表项
** 二级列表项
*** 三级列表项
**** 四级列表项
***** 五级列表项
* 一级列表项
查看效果 无序列表最大级别嵌套
  • 一级列表项

    • 二级列表项

      • 三级列表项

        • 四级列表项

          • 五级列表项

  • 一级列表项

可以使用列表样式(例如:square)更改 无序的列表标记

有序列表
. Step 1
. Step 2
.. Step 2a
.. Step 2b
. Step 3
查看效果 有序列表
  1. Step 1

  2. Step 2

    1. Step 2a

    2. Step 2b

  3. Step 3

Ordered list max level nesting
* 一级列表项
** 二级列表项
*** 三级列表项
**** 四级列表项
***** 五级列表项
* 一级列表项
查看效果 Ordered list max level nesting
  • 一级列表项

    • 二级列表项

      • 三级列表项

        • 四级列表项

          • 五级列表项

  • 一级列表项

Ordered lists support numeration styles such as lowergreek and decimal-leading-zero.

Checklist
link:lists:example$checklist.adoc[tag=check]
查看效果 Checklist
Description list
link:lists:example$description.adoc[tag=qr-base]
查看效果 Description list
Question and answer list
link:lists:example$description.adoc[tag=qa]
查看效果 Question and answer list
Mixed
link:lists:example$description.adoc[tag=3-mix]
查看效果 Mixed
Lists can be indented. Leading whitespace is not significant.
Complex content in outline lists
link:lists:example$complex.adoc[tag=b-complex]
查看效果 Complex content in outline lists

Images

You can use the imagesdir attribute to avoid hard coding the common path to your images in every image macro. The value of this attribute can be an absolute path, relative path, or base URL. If the image target is a relative path, the attribute’s value is prepended (i.e., it’s resolved relative to the value of the imagesdir attribute). If the image target is a URL or absolute path, the attribute’s value is not prepended.

Block image macro
link:macros:example$image.adoc[tag=base]

link:macros:example$image.adoc[tag=alt]

link:macros:example$image.adoc[tag=attr]

link:macros:example$image.adoc[tag=ab-url]
查看效果 Block image macro

Two colons following the image keyword in the macro (i.e., image::) indicates a block image (aka figure), whereas one colon following the image keyword (i.e., image:) indicates an inline image. (All macros follow this pattern). You use an inline image when you need to place the image in a line of text. Otherwise, you should prefer the block form.

Inline image macro
link:macros:example$image.adoc[tag=inline]
查看效果 Inline image macro
Inline image macro with positioning role
link:macros:example$image.adoc[tag=in-role]
查看效果 Inline image macro with positioning role
Embedded
link:macros:example$image.adoc[tag=data]

When the data-uri attribute is set, all images in the document—​including admonition icons—​are embedded into the document as {url-data-uri}[data URIs]. You can also pass it as a command line argument using -a data-uri.

Audio

Block audio macro
link:macros:example$audio.adoc[tag=basic]

link:macros:example$audio.adoc[tag=attrs]

You can control the audio settings using additional attributes and options on the macro.

Videos

Block video macro
link:macros:example$video.adoc[tag=base]

link:macros:example$video.adoc[tag=attr]
Embedded YouTube video
link:macros:example$video.adoc[tag=youtube]
Embedded Vimeo video
link:macros:example$video.adoc[tag=vimeo]

You can control the video settings using additional attributes and options on the macro.

Keyboard, button, and menu macros

You must set the experimental attribute in the document header to enable these macros.
Keyboard macro
link:macros:example$ui.adoc[tag=qr-key]
查看效果 Keyboard macro
Menu macro
link:macros:example$ui.adoc[tag=menu]
查看效果 Menu macro
Button macro
link:macros:example$ui.adoc[tag=button]
查看效果 Button macro

Literals and source code

Inline literal monospace
link:pass:example$pass.adoc[tag=backtick-plus]
查看效果 Inline literal monospace
Literal paragraph
link:verbatim:example$literal.adoc[tag=b-imp-code]
查看效果 Literal paragraph
Literal block
link:verbatim:example$literal.adoc[tag=b-block]
查看效果 Literal block
Listing block with title
link:verbatim:example$listing.adoc[tag=qr-listing]
查看效果 Listing block with title
link:verbatim:example$listing.adoc[tag=qr-listing]
Source block with title and syntax highlighting
.Some Ruby code
link:verbatim:example$source.adoc[tag=src-base]
查看效果 Source block with title and syntax highlighting

You must enable source highlighting by setting the source-highlighter attribute in the document header, CLI, or API.

:source-highlighter: rouge

See asciidoctor:syntax-highlighting:index.html to learn which values are accepted when using Asciidoctor.

Source block with callouts
link:verbatim:example$callout.adoc[tag=b-src]
查看效果 Source block with callouts
Make callouts non-selectable
link:verbatim:example$callout.adoc[tag=b-nonselect]
查看效果 Make callouts non-selectable
Source block content included from a file
link:verbatim:example$source.adoc[tag=src-inc]
Source block content included from file relative to source directory
link:verbatim:example$source.adoc[tag=rel]
Strip leading indentation from partial file content
link:verbatim:example$source.adoc[tag=ind]

The indent attribute is frequently used when including source code by tagged region or lines. It can be specified on the include directive itself or the enclosing literal, listing, or source block.

When indent is 0, the leading block indent is stripped.

When indent is greater than 0, the leading block indent is first stripped, then a block is indented by the number of columns equal to this value.

Source paragraph (no empty lines)
link:verbatim:example$source.adoc[tag=src-para]
查看效果 Source paragraph (no empty lines)

Admonitions

Admonition paragraph
link:blocks:example$admonition.adoc[tag=b-para]
查看效果 Admonition paragraph
Admonition block
link:blocks:example$admonition.adoc[tag=b-bl]
查看效果 Admonition block

More delimited blocks

Any block can have a title, positioned above the block. A block title is a line of text that starts with a dot. The dot cannot be followed by a space.

Sidebar block
link:blocks:example$sidebar.adoc[tag=delimited]
查看效果 Sidebar block
Example block
link:blocks:example$example.adoc[tag=base]
查看效果 Example block
Blockquotes
link:blocks:example$quote.adoc[tag=bl]

link:blocks:example$quote.adoc[tag=para]

link:blocks:example$quote.adoc[tag=no-cite]

link:blocks:example$quote.adoc[tag=link-text]

link:blocks:example$quote.adoc[tag=abbr]
查看效果 Blockquotes
Open blocks
link:blocks:example$open.adoc[tag=base]

link:blocks:example$open.adoc[tag=src]
查看效果 Open blocks
Passthrough block
link:pass:example$pass.adoc[tag=b-bl]
查看效果 Passthrough block
Customize block substitutions
查看效果 Customize block substitutions

Tables

Table with a title, two columns, a header row, and two rows of content
link:tables:example$table.adoc[tag=b-base-h-co]
1 Unless the cols attribute is specified, the number of columns is equal to the number of cell separators on the first (non-empty) line.
2 When an empty line immediately follows a non-empty line at the start of the table, the cells in the first line get promoted to the table header.
查看效果 Table with a title, two columns, a header row, and two rows of content
Table with two columns, a header row, and two rows of content
link:tables:example$table.adoc[tag=b-col-h-co]
1 The * in the cols attribute is the repeat operator. It means repeat the column specification across the remaining columns. In this case, we are repeating the default formatting across 2 columns. When the cells in the header are not defined on a single line, you must use the cols attribute to set the number of columns in the table and the %header option (or options=header attribute) to promote the first row to the table header.
查看效果 Table with two columns, a header row, and two rows of content
Table with three columns, a header row, and two rows of content
link:tables:example$table.adoc[tag=b-col-indv-co]
1 In this example, the cols attribute has two functions. It specifies that this table has three columns, and it sets their relative widths.
查看效果 Table with three columns, a header row, and two rows of content
Table with column containing AsciiDoc content
link:tables:example$table.adoc[tag=b-col-a]
查看效果 Table with column containing AsciiDoc content
Table from CSV data using shorthand
link:tables:example$data.adoc[tag=s-csv]
查看效果 Table from CSV data using shorthand
Table from CSV data
link:tables:example$data.adoc[tag=csv]
查看效果 Table from CSV data
Table from CSV data in file
link:tables:example$data.adoc[tag=i-csv]
Table from DSV data using shorthand
link:tables:example$data.adoc[tag=s-dsv]
查看效果 Table from DSV data using shorthand
Table with formatted, aligned and merged cells
link:tables:example$cell.adoc[tag=b-spec]
查看效果 Table with formatted, aligned and merged cells

IDs, roles, and options

Shorthand method for assigning block ID (anchor) and role
[#goals.incremental]
* Goal 1
* Goal 2
  • To specify multiple roles using the shorthand syntax, delimit them by dots.

  • The order of id and role values in the shorthand syntax does not matter.

Formal method for assigning block ID (anchor) and role
[id="goals",role="incremental"]
* Goal 1
* Goal 2
Explicit section ID (anchor)
[#null-values]
== Primitive types and null values
Assign ID (anchor) and role to inline formatted text
[#id-name.role-name]`monospace text`

[#free-world.goals]*free the world*
Shorthand method for assigning block options
[%header%footer%autowidth]
|===
|Header A |Header B
|Footer A |Footer B
|===
Formal method for assigning block options
[options="header,footer,autowidth"]
|===
|Header A |Header B
|Footer A |Footer B
|===

// options can be shorted to opts
[opts="header,footer,autowidth"]
|===
|Header A |Header B
|Footer A |Footer B
|===

Comments

Line and block comments
// A single-line comment

////
A multi-line comment.

Notice it's a delimited block.
////

Breaks

Thematic break (aka horizontal rule)
before

'''

after
查看效果 Thematic break (aka horizontal rule)

before


after

Page break
<<<

Attributes and substitutions

Attribute declaration and usage
:url-home: https://asciidoctor.org
:link-docs: https://asciidoctor.org/docs[documentation]
:summary: AsciiDoc is a mature, plain-text document format for \
       writing notes, articles, documentation, books, and more. \
       It's also a text processor & toolchain for translating \
       documents into various output formats (i.e., backends), \
       including HTML, DocBook, PDF and ePub.
:checkedbox: pass:normal[{startsb}&#10004;{endsb}]

Check out {url-home}[Asciidoctor]!

{summary}

Be sure to read the {link-docs} too!

{checkedbox} That's done!
查看效果 Attribute declaration and usage

Check out Asciidoctor!

AsciiDoc is a mature, plain-text document format for writing notes, articles, documentation, books, and more. It’s also a text processor & toolchain for translating documents into various output formats (i.e., backends), including HTML, DocBook, PDF and ePub.

Be sure to read the documentation too!

[✔] That’s done!

To learn more about the available attributes and substitution groups see:

Counter attributes
link:attributes:example$counter.adoc[tag=base]
查看效果 Counter attributes

Text replacements

Any named, numeric or hexadecimal {url-char-xml}[XML character reference^] is supported.

Escaping substitutions

Backslash
link:subs:example$subs.adoc[tag=backslash]
查看效果 Backslash
Single and double plus inline passthroughs
link:pass:example$pass.adoc[tag=plus]
查看效果 Single and double plus inline passthroughs
Triple plus inline passthrough and inline pass macro
link:pass:example$pass.adoc[tag=b-3p-macro]
查看效果 Triple plus inline passthrough and inline pass macro

Bibliography

Bibliography with inbound references
link:sections:example$bibliography.adoc[tag=base]
查看效果 Bibliography with inbound references

Footnotes

Normal and reusable footnotes
link:macros:example$footnote.adoc[tag=base]
查看效果 Normal and reusable footnotes

Markdown compatibility

Markdown compatible syntax is an optional feature of the AsciiDoc language and is currently only available when using Asciidoctor.

Markdown-style headings

查看效果 Markdown-style headings
Fenced code block with syntax highlighting
link:verbatim:example$source.adoc[tag=fence]
查看效果 Fenced code block with syntax highlighting
Markdown-style blockquote
link:blocks:example$quote.adoc[tag=md]
查看效果 Markdown-style blockquote
Markdown-style blockquote with block content
link:blocks:example$quote.adoc[tag=md-alt]
查看效果 Markdown-style blockquote with block content
Markdown-style thematic breaks
---

- - -

***

* * *
查看效果 Markdown-style thematic breaks