AsciiDoc 语法快速参考

AsciiDoc 是一种轻量级标记语言,它可以让我们以纯文本的形式来书写笔记、文章、文档、书籍、网页、幻灯片和 man 帮助。 本指南是常用的 AsciiDoc 文档和文字格式化标记的快速参考。

这些例子主要关注生成的 HTML 后端。 AsciiDoc 生成 PDF、EPUB 和 DocBook 时,它们之间是互补的。

很多标注着 仅 _Asciidoctor 可用 的特性通过 Asciidoctor 项目提供的 AsciiDoc 配置文件 也可以在传统的 AsciiDoc Python 处理器中使用。

段落

正常
Paragraphs don't require any special markup in AsciiDoc.
A paragraph is just one or more lines of consecutive text.

To begin a new paragraph, separate it by at least one blank line.

Paragraphs don’t require any special markup in AsciiDoc. A paragraph is just one or more lines of consecutive text.

To begin a new paragraph, separate it by at least one blank line.

换行
Rubies are red, +
Topazes are blue.

[%hardbreaks]
Ruby is red.
Java is black.

Rubies are red,
Topazes are blue.

Ruby is red.
Java is black.

文字
A normal paragraph.

 A sequence of lines that begin with at least one space is a literal paragraph.
 Literal paragraphs are treated as preformatted text.
 The text is shown in a fixed-width font
 and endlines are preserved.

Another normal paragraph.

A normal paragraph.

A sequence of lines that begin with at least one space is a literal paragraph.
Literal paragraphs are treated as preformatted text.
The text is shown in a fixed-width font
and endlines are preserved.

Another normal paragraph.

警告
NOTE: An admonition paragraph draws the reader's attention to
auxiliary information.
Its purpose is determined by the label
at the beginning of the paragraph.

Here are the other built-in admonition types:

TIP: Pro tip...

IMPORTANT: Don't forget...

WARNING: Watch out for...

CAUTION: Ensure that...
An admonition paragraph draws the reader’s attention to auxiliary information. Its purpose is determined by the label at the beginning of the paragraph.

Here are the other built-in admonition types:

Pro tip…​
Don’t forget…​
Watch out for…​
Ensure that…​
你也可以创建 警示块.
概要段落
[.lead]
This text will be styled as a lead paragraph (i.e., larger font).

This text will be styled as a lead paragraph (i.e., larger font).

默认的 Asciidoctor 样式会自动将序文的第一段作为摘要段落。
更多段落、警告和文字块示例

在 Asciidoctor 用户手册中的这些章节中,有更多的信息以及示例。

格式化文本

加粗、斜体和等宽字体
_italic phrase_

__i__talic le__tt__ers

*bold phrase*

**b**old le**tt**ers

*_bold italic phrase_*

**__b__**old italic le**__tt__**ers

`monospace phrase` and le``tt``ers

`_monospace italic phrase_` and le``__tt__``ers

`*monospace bold phrase*` and le``**tt**``ers

`*_monospace bold italic phrase_*` and le``**__tt__**``ers

italic phrase

italic letters

bold phrase

bold letters

bold italic phrase

bold italic letters

monospace phrase and letters

monospace italic phrase and letters

monospace bold phrase and letters

monospace bold italic phrase and letters

自定义样式
Werewolves are #allergic to cinnamon#.

Do werewolves believe in [small]#small print#?

[big]##O##nce upon an infinite loop.

Werewolves are allergic to cinnamon.

Do werewolves believe in small print?

Once upon an infinite loop.

上角标 和 脚注
^super^script phrase

~sub~script phrase

superscript phrase

subscript phrase

引号
'`single curved quotes`'

"`double curved quotes`"

Olaf's desk was a mess.

All of the werewolves`' desks were a mess.

Olaf had been with the company since the `'60s.

‘single curved quotes’

“double curved quotes”

Olaf’s desk was a mess.

All of the werewolves’ desks were a mess.

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

更多文本格式化示例

在 Asciidoctor 用户手册的这些章节中,更多的信息以及示例。

文档标题

标题是可选的。
标题不能包含空号,并且下面必须紧跟至少一个空行。
标题
= My Document's Title

My document provides...
标题以及作者行
= My Document's Title
Doc Writer <doc.writer@asciidoctor.org>

My document provides...
Asciidoctor 允许在作者行中出现多位作者,使用分号来分割开来。
标题、作者行以及版本行
= My Document's Title
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2014-01-01

My document provides...
你不能只写版本行而不写作者行!
带属性的文档标题
= My Document's Title
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2014-01-01
:toc:
:imagesdir: assets/images
:homepage: http://asciidoctor.org

My document provides...

章节标题

文章标题类型
= Document Title (Level 0)

== Level 1 Section Title

=== Level 2 Section Title

==== Level 3 Section Title

===== Level 4 Section Title

====== Level 5 Section Title

== Another Level 1 Section Title

Document Title (Level 0)

Level 1 Section Title

Level 2 Section Title

Level 3 Section Title

Level 4 Section Title
Level 5 Section Title

Another Level 1 Section Title

当使用文章标题类型时,默认只能有一个级别为0的文章标题(也就是文档标题),并且必须在文档头部。
等号的数量与输出的 HTML 标题级别想匹配。 例如,Section Level 1 将会转化为 <h2> 标题。
书籍标题类型
= Document Title (Level 0)

== Section Level 1

=== Section Level 2

==== Section Level 3

===== Section Level 4

====== Section Level 5

= Section Level 0

Document Title (Level 0)

Section Level 1

Section Level 2

Section Level 3

Section Level 4
Section Level 5

Section Level 0

指定 ID
[[primitives-nulls]]
== Primitive types and null values
章节锚点以及链接 (仅 Asciidoctor 支持)
sectanchors

当设置该文档属性后,章节的锚点图标就会出现在章节标题前面。

sectlinks

当设置该文档属性后,章节标题就变成自链接。 这使得读者可以书签标记这个章节。

章节标题锚点依赖默认 Asciidoctor 样式的正确渲染。

包含文件

文档分块
= Reference Documentation
Lead Developer

This is documentation for project X.

include::basics.adoc[]

include::installation.adoc[]

include::example.adoc[]
Asciidoctor does not insert blank lines between adjacent include statements to keep the content separated. Be sure to add a blank line in the source document to avoid unexpected results, such as a section title being swallowed.
从一个 URI 中含内容
:asciidoctor-source: https://raw.githubusercontent.com/asciidoctor/asciidoctor/master

include::{asciidoctor-source}/README.adoc[]
Including content from a URI is potentially dangerous, so it’s disabled if the safe mode is SECURE or greater. Assuming the safe mode is less than SECURE, you must also set the allow-uri-read attribute to permit Asciidoctor to read content from a URI.

水平线和分页符

水平线
'''

分页
<<<

列表

基本无序列表
* Edgar Allen Poe
* Sheri S. Tepper
* Bill Bryson
  • Edgar Allen Poe

  • Sheri S. Tepper

  • Bill Bryson

NOTE:列表前后的空行是必须的。

你可以通过在列表中间放一行注释来将其分成两个列表,就像上面的演示示例一样。 注释中的文字(例如 ^)是可选的,但是可以个作为给其他作者的一个提示,来说明改行是列表的结束行。
无序嵌套列表
* level 1
** level 2
*** level 3
**** level 4
***** level 5
* level 1
  • level 1

    • level 2

      • level 3

        • level 4

          • level 5

  • level 1

可以通过 块样式 来改变无序列表的标识类型。
清单
- [*] checked
- [x] also checked
- [ ] not checked
-     normal list item
  • checked

  • also checked

  • not checked

  • normal list item

清单可以使用 字体图标,还可互动
基本有序列表
. Step 1
. Step 2
. Step 3
  1. Step 1

  2. Step 2

  3. Step 3

有序嵌套列表
. 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

有序最大嵌套列表
. level 1
.. level 2
... level 3
.... level 4
..... level 5
. level 1
  1. level 1

    1. level 2

      1. level 3

        1. level 4

          1. level 5

  2. level 1

对于有序列表,Asciidoctor 支持不同的 数字样式,例如 lowergreekdecimal-leading-zero
单行标签列表
first term:: definition of first term
section term:: definition of second term
first term

definition of first term

section term

definition of second term

多行标签列表
first term::
definition of first term
section term::
definition of second term
first term

definition of first term

section term

definition of second term

常见问题以及解答
[qanda]
What is Asciidoctor?::
  An implementation of the AsciiDoc processor in Ruby.
What is the answer to the Ultimate Question?:: 42
  1. What is Asciidoctor?

    An implementation of the AsciiDoc processor in Ruby.

  2. What is the answer to the Ultimate Question?

    42

混合样式列表
Operating Systems::
  Linux:::
    . Fedora
      * Desktop
    . Ubuntu
      * Desktop
      * Server
  BSD:::
    . FreeBSD
    . NetBSD

Cloud Providers::
  PaaS:::
    . OpenShift
    . CloudBees
  IaaS:::
    . Amazon EC2
    . Rackspace
Operating Systems
Linux
  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD
  1. FreeBSD

  2. NetBSD

Cloud Providers
PaaS
  1. OpenShift

  2. CloudBees

IaaS
  1. Amazon EC2

  2. Rackspace

列表可以缩进。 开头空白不需要显示指定。
复杂内容列表
* Every list item has at least one paragraph of content,
  which may be wrapped, even using a hanging indent.
+
Additional paragraphs or blocks are adjoined by putting
a list continuation on a line adjacent to both blocks.
+
list continuation:: a plus sign (`{plus}`) on a line by itself

* A literal paragraph does not require a list continuation.

 $ gem install asciidoctor

* AsciiDoc lists may contain any complex content.
+
[cols="2", options="header"]
|===
|Application
|Language

|AsciiDoc
|Python

|Asciidoctor
|Ruby
|===
  • Every list item has at least one paragraph of content, which may be wrapped, even using a hanging indent.

    Additional paragraphs or blocks are adjoined by putting a list continuation on a line adjacent to both blocks.

    list continuation

    a plus sign (+) on a line by itself

  • A literal paragraph does not require a list continuation.

    $ gem install asciidoctor
  • AsciiDoc lists may contain any complex content.

    Application Language

    AsciiDoc

    Python

    Asciidoctor

    Ruby

外部链接
http://asciidoctor.org - automatic!

http://asciidoctor.org[Asciidoctor]

https://github.com/asciidoctor[Asciidoctor @ *GitHub*]
带空格以及特殊字符
link:++http://example.org/?q=[a b]++[URL with special characters]

link:http://example.org/?q=%5Ba%20b%5D[URL with special characters]
Windows 路径
link:\\server\share\whitepaper.pdf[Whitepaper]
相对路径
link:index.html[Docs]
电子邮件和 IRC
devel@discuss.arquillian.org

mailto:devel@discuss.arquillian.org[Discuss Arquillian]

mailto:devel-join@discuss.arquillian.org[Subscribe, Subscribe me, I want to join!]

irc://irc.freenode.org/#asciidoctor
带属性的链接(仅 Asciidoctor 支持)
http://discuss.asciidoctor.org[Discuss Asciidoctor, role="external", window="_blank"]

http://discuss.asciidoctor.org[Discuss Asciidoctor^]

http://example.org["Google, Yahoo, Bing^", role="teal"]
带属性的链接(包含 mailto 链接的主题和正文)是唯有 Asciidoctor 支持的特性。 为了启用这个特性,必须在文档中设置 linkattrs 属性。 当启用这个特性时,如果链接内容包含逗号,则必须用引号将链接文本括起来。
行内锚点
[[bookmark-a]]Inline anchors make arbitrary content referenceable.

anchor:bookmark-b[]Use a cross reference to link to this location.

[[bookmark-c,last paragraph]]The xreflabel attribute will be used as link text in the cross-reference link.

Inline anchors make arbitrary content referenceable.

Use a cross reference to link to this location.

The xreflabel attribute will be used as link text in the cross-reference link.

内部交叉引用
See <<paragraphs>> to learn how to write paragraphs.

Learn how to organize the document into <<section-titles,sections>>.

See 段落 to learn how to write paragraphs.

Learn how to organize the document into sections.

文档间的交叉引用(仅 Asciidoctor 支持)
Refer to <<document-b.adoc#section-b,Section B>> for more information.

See you when you get back from <<document-b#section-b,Section B>>!

图片

image::sunset.jpg[]

image::sunset.jpg[Sunset]

[[img-sunset]]
image::sunset.jpg[caption="Figure 1: ", title="A mountain sunset", alt="Sunset", width="300", height="200", link="http://www.flickr.com/photos/javh/5448336655"]

image::http://asciidoctor.org/images/octocat.jpg[GitHub mascot]
sunset
Sunset
Sunset
Figure 1: A mountain sunset
GitHub mascot
图片路径会被解析成一个相对于 imagesdir 文档属性 的一个值,默认是一个空字符串。 imagesdir 属性可以是绝对路径、相对路径或者是基本 URL。 如果图片的目标(target)是一个 URL 或者绝对路径,则 imagesdir 前缀就不会被添加。
应该使用 imagesdir 属性来避免在每一个图片宏中硬编码分享路径。
使用位置信息的图片宏
image:sunset.jpg[Sunset,150,150,role="right"] What a beautiful sunset!

Sunset What a beautiful sunset!

图片的位置和帧 中,有很多很多可用的属性。
行内
Click image:icons/play.png[Play, title="Play"] to get the party started.

Click image:icons/pause.png[title="Pause"] when you need a break.

Click Play to get the party started.

Click pause when you need a break.

嵌入式
= Document Title
:data-uri:
data-uri 属性被设置时,文档中的所有图片,包含警告图标,都会作为 数据 URI 嵌入到文档中。
除了在文档中声明 data-uri 属性,你还可以将 -a data-uri 参数传递给命令行。

视频

video::video_file.mp4[]

video::video_file.mp4[width=640, start=60, end=140, options=autoplay]
嵌入 Youtube 视频
video::rPQoq7ThGAU[youtube]
嵌入 Vimeo 视频
video::67480300[vimeo]
可以在宏中使用 附加属性及选项 来控制视频设置。

源码

行内代码
Reference code like `types` or `methods` inline.

Reference code like types or methods inline.

代码行
 Indent the line one space to insert a code snippet
Indent the line one space to insert a code snippet
代码块
....
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
....
error: The requested operation returned error: 1954 Forbidden search for defensive operations manual
absolutely fatal: operation initiation lost in the dodecahedron of doom
would you like to die again? y/n
带标题的代码块,没有语法高亮
.Gemfile.lock
----
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (0.1.4)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 0.1.4)
----
Gemfile.lock
GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (0.1.4)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 0.1.4)
加标题和语法高亮代码块
[[app-listing]]
[source,ruby]
.app.rb
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----
app.rb
require 'sinatra'

get '/hi' do
  "Hello World!"
end
加注标的代码块
[source,ruby]
----
require 'sinatra' // <1>

get '/hi' do // <2>
  "Hello World!" // <3>
end
----
<1> Library import
<2> URL mapping
<3> HTTP response body
require 'sinatra' (1)

get '/hi' do (2)
  "Hello World!" (3)
end
1 Library import
2 URL mapping
3 HTTP response body
加非选择性标注的代码块
----
line of code  // <1>
line of code  # <2>
line of code  ;; <3>
----
<1> A callout behind a line comment for C-style languages.
<2> A callout behind a line comment for Ruby, Python, Perl, etc.
<3> A callout behind a line comment for Clojure.
line of code  (1)
line of code  (2)
line of code  (3)
1 A callout behind a line comment for C-style languages.
2 A callout behind a line comment for Ruby, Python, Perl, etc.
3 A callout behind a line comment for Clojure.
加非选择性标注的 XML 代码块
[source,xml]
----
<section>
  <title>Section Title</title> <!--1-->
</section>
----
<1> The section title is required.
<section>
  <title>Section Title</title> (1)
</section>
1 The section title is required.
从文件中引入的代码块
[source,ruby]
----
include::app.rb[]
----
从相对路径中文件引入的代码块
:sourcedir: src/main/java

[source,java]
----
include::{sourcedir}/org/asciidoctor/Asciidoctor.java[]
----
Strip leading indentation from source
[source,ruby,indent=0]
----
include::lib/document.rb[lines=5..10]
----
  • When indent is 0, the leading block indent is stripped (tabs are replaced with 4 spaces).

  • When indent is > 0, the leading block indent is first stripped (tabs are replaced with 4 spaces), then a block is indented by the number of columns equal to this value.

不需要分隔符的代码块(没有空白行)
[source,xml]
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

This is normal content.
<meta name="viewport"
  content="width=device-width, initial-scale=1.0">

This is normal content.

启用语法高亮

启用语法高亮可以在文档头部设置 source-highlighter 属性或者将其作为一个参数传递给命令行工具。

:source-highlighter: pygments

可用选项有: coderayhighlightjsprettifypygments

更多分隔块

侧边栏
.AsciiDoc history
****
AsciiDoc was first released in Nov 2002 by Stuart Rackham.
It was designed from the start to be a shorthand syntax
for producing professional documents like DocBook and LaTeX.
****
AsciiDoc history

AsciiDoc was first released in Nov 2002 by Stuart Rackham. It was designed from the start to be a shorthand syntax for producing professional documents like DocBook and LaTeX.

任何块可以在块上面定义标题。 块标题是一行以点号开头的文字。 点号后面不能有空白。
示例
.Sample document
====
Here's a sample AsciiDoc document:

[listing]
....
= Title of Document
Doc Writer
:toc:

This guide provides...
....

The document header is useful, but not required.
====
Sample document

Here’s a sample AsciiDoc document:

= Title of Document
Doc Writer
:toc:

This guide provides...

The document header is useful, but not required.

警告
[NOTE]
====
An admonition block may contain complex content.

.A list
- one
- two
- three

Another paragraph.
====

An admonition block may contain complex content.

A list
  • one

  • two

  • three

Another paragraph.

警告和注标图标

Asciidoctor 可以使用 Font Awesome 和 CSS “描绘” 图标。

将文档属性 icons 的值设置为 font 来启用该特性。 Asciidoctor 会在文档中添加 HTML 标记,通过这些标记来从 Font Awesome 字体为每一个警告块选择一个合适的字符来展示。

图标还可以使用 inlinestyled

引用块
[quote, Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg]
____
Four score and seven years ago our fathers brought forth
on this continent a new nation...
____

[quote, Albert Einstein]
A person who never made a mistake never tried anything new.

____
A person who never made a mistake never tried anything new.
____

[quote, Charles Lutwidge Dodgson, 'Mathematician and author, also known as http://en.wikipedia.org/wiki/Lewis_Carroll[Lewis Carroll]']
____
If you don't know where you are going, any road will get you there.
____

Four score and seven years ago our fathers brought forth on this continent a new nation…​

— Abraham Lincoln
Address delivered at the dedication of the Cemetery at Gettysburg
A person who never made a mistake never tried anything new.
— Albert Einstein

A person who never made a mistake never tried anything new.

简略引用块(仅 Asciidoctor 支持)
"I hold it that a little rebellion now and then is a good thing,
and as necessary in the political world as storms in the physical."
-- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11
I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.
— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11
Air quotes: the best thing since fenced code blocks (Asciidoctor only)
[, Richard M. Nixon]
""
When the President does it, that means that it's not illegal.
""

When the President does it, that means that it’s not illegal.

— Richard M. Nixon
Pass 宏
++++
<p>
Content in a passthrough block is passed to the output unprocessed.
That means you can include raw HTML, like this embedded Gist:
</p>

<script src="http://gist.github.com/mojavelinux/5333524.js">
</script>
++++

Content in a passthrough block is passed to the output unprocessed. That means you can include raw HTML, like this embedded Gist:

Open
--
An open block can be an anonymous container,
or it can masquerade as any other block.
--

[source]
--
puts "I'm a source block!"
--

An open block can be an anonymous container, or it can masquerade as any other block.

puts "I'm a source block!"
自定义代换
:version: 0.1.4

[source,xml,subs="verbatim,attributes"]
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>{version}</version>
</dependency>
----
<dependency>
  <groupId>org.asciidoctor</groupId>
  <artifactId>asciidoctor-java-integration</artifactId>
  <version>0.1.4</version>
</dependency>

块ID,角色和选项

为块添加 ID 和角色的传统标记方法
[[goals]]
[role="incremental"]
* Goal 1
* Goal 2
为块添加 ID 和角色的简略标记方法(仅 Asciidoctor 支持)
[#goals.incremental]
* Goal 1
* Goal 2
  • 在简略语法中,可以使用点号分割来指定多个角色。

  • 简略语法中 idrole 值的顺序无关紧要。

为引用文本添加锚点和角色的传统标记方法
[[free_the_world]][big goal]_free the world_
为引用文本添加锚点和角色的简略标记方法(仅 Asciidoctor 支持)
[#free_the_world.big.goal]_free the world_
为反引号包括的文本添加角色
[rolename]`monospace text`
为块添加选项的传统标记方法
[options="header,footer,autowidth"]
|===
|Cell A |Cell B
|===
为块添加选项的简略标记方法(仅 Asciidoctor 支持)
[%header%footer%autowidth]
|===
|Cell A |Cell B
|===

评论

单行
// A single-line comment.
单行注释可以用于划分元素,例如两个相邻的清单。
注释块
////
A multi-line comment.

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

表格

带标题的三行二列表格
.Table Title
|===
|Name of Column 1 |Name of Column 2 |Name of Column 3 (1)
(2)
|Cell in column 1, row 1
|Cell in column 2, row 1
|Cell in column 3, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|Cell in column 3, row 2
|===
1 除非设置 cols 属性,否则行数就等于块区域中第一非空白行中竖线的数量。
2 当列开头下面紧跟一空白行时,列开头会自动渲染成列标题的样式。
Table Title
Name of Column 1 Name of Column 2 Name of Column 3

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 3, row 1

Cell in column 1, row 2

Cell in column 2, row 2

Cell in column 3, row 2

表格,列标题,两行两列内容
[cols="2*", options="header"] (1)
|===
|Name of Column 1
|Name of Column 2

|Cell in column 1, row 1
|Cell in column 2, row 1

|Cell in column 1, row 2
|Cell in column 2, row 2
|===
1 cols 属性值中的 * 是复制符,用来按现有列的格式复制剩余部分。在这个例子中,它就代表重复默认的样式到 4 列。当标题行不是定义在一行里,就必须使用 cols 属性来设置列数,并使用 options 属性来将第一行设置成标题。
Name of Column 1 Name of Column 2

Cell in column 1, row 1

Cell in column 2, row 1

Cell in column 1, row 2

Cell in column 2, row 2

表格,带列标题,两行三列内容
[cols="1,1,2", options="header"] (1)
.Applications
|===
|Name
|Category
|Description

|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.
It's designed for standards compliance,
performance, portability.

|Arquillian
|Testing
|An innovative and highly extensible testing platform.
Empowers developers to easily create real, automated tests.
|===
1 在这个例子中,cols 属性有两个功能:设置表格的列数及列之间相对的宽度。
Applications
Name Category Description

Firefox

Browser

Mozilla Firefox is an open-source web browser. It’s designed for standards compliance, performance, portability.

Arquillian

Testing

An innovative and highly extensible testing platform. Empowers developers to easily create real, automated tests.

Table with column containing AsciiDoc content
[cols="2,2,5a"]
|===
|Firefox
|Browser
|Mozilla Firefox is an open-source web browser.

It's designed for:

* standards compliance
* performance
* portability

http://getfirefox.com[Get Firefox]!
|===

Firefox

Browser

Mozilla Firefox is an open-source web browser.

It’s designed for:

  • standards compliance

  • performance

  • portability

CSV 数据格式的表格
[format="csv", options="header"]
|===
Artist,Track,Genre
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===
Artist Track Genre

Baauer

Harlem Shake

Hip Hop

The Lumineers

Ho Hey

Folk Rock

CSV 数据表格的简写形式(仅 Asciidoctor 支持)
,===
Artist,Track,Genre

Baauer,Harlem Shake,Hip Hop
,===
Artist Track Genre

Baauer

Harlem Shake

Hip Hop

文件中CSV 数据的表格
|===
include::customers.csv[]
|===
文件中CSV 数据的表格的简写形式(仅 Asciidoctor 支持)
:===
Artist:Track:Genre

Robyn:Indestructable:Dance
:===
Artist Track Genre

Robyn

Indestructable

Dance

表格的格式化、对齐以及合并单元格
[cols="e,m,^,>s", width="25%"]
|===
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|===

1

2

3

4

5

6

7

8

9

10

UI 宏

You must set the experimental attribute in the document header to enable these macros.
快捷键(行内 kbd 宏)
|===
|Shortcut |Purpose

|kbd:[F11]
|Toggle fullscreen

|kbd:[Ctrl+T]
|Open a new tab

|kbd:[Ctrl+Shift+N]
|New incognito window

|kbd:[Ctrl + +]
|Increase zoom
|===
Shortcut Purpose

F11

Toggle fullscreen

Ctrl+T

Open a new tab

Ctrl+Shift+N

New incognito window

Ctrl++

Increase zoom

菜单选项(行内 menu 宏)
To save the file, select menu:File[Save].

Select menu:View[Zoom > Reset] to reset the zoom level to the default setting.

To save the file, select File ▸ Save.

Select View ▸ Zoom ▸ Reset to reset the zoom level to the default setting.

按钮(行内 btn 宏)
Press the btn:[OK] button when you are finished.

Select a file in the file navigator and click btn:[Open].

Press the OK button when you are finished.

Select a file in the file navigator and click Open.

属性与代换

属性的声明及使用
:homepage: http://asciidoctor.org
:docslink: http://asciidoctor.org/docs[Asciidoctor's Docs]
:summary: Asciidoctor 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 {homepage}[Asciidoctor]!

{summary}

Check out {docslink} too!

{checkedbox} That's done!

Check out Asciidoctor!

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

Check out Asciidoctor’s Docs too!

[✔] That’s done!

属性赋值优先级(从高到低)
  • 传递给 API 或者 命令行且不以 @ 结尾的属性

  • 在文档中定义的属性

  • 传递给 API 或者 命令行且以 @ 结尾的属性

  • 内置属性值(默认值)

为了使传递给 API 或者 命令行的属性有一个比文档中定义的属性有更低的优先级,则可以在属性值的末尾追加一个 @ 符号。
Predefined attributes for character replacements [1][2][3]
Attribute name Replacement text Appearance
blank
nothing
empty
nothing
sp
single space
nbsp
&#160;

 

zwsp[4]
&#8203;

wj[5]
&#8288;

apos
&#39;

'

quot
&#34;

"

lsquo
&#8216;

rsquo
&#8217;

ldquo
&#8220;

rdquo
&#8221;

deg
&#176;

°

plus
&#43;

+

brvbar
&#166;

¦

vbar
|

|

amp
&

&

lt
<

<

gt
>

>

startsb
[

[

endsb
]

]

caret
^

^

asterisk
*

*

tilde
~

~

backslash
\

\

backtick
`

`

two-colons
::

::

two-semicolons
;;

;;

cpp
C++

C++

[1] Some replacements are Unicode characters, whereas others are numeric character references. The character references (e.g., &#34;) are used whenever the use of the Unicode character could interfere with the AsciiDoc syntax or confuse the renderer (i.e., the browser). It’s up to the converter to transform the reference into something the renderer understands (something both the manpage and PDF converter handle).

[2] Asciidoctor does not prevent you from reassigning predefined attributes. However, it’s best to treat them as read-only unless the output format requires the use of a different encoding scheme. These attributes are an effective tool for decoupling content and presentation.

[3] Asciidoctor allows you to use any of the named character references (aka named entities) defined in HTML (e.g., &euro; resolves to €). However, using named character references can cause problems when generating non-HTML output such as PDF because the lookup table needed to resolve these names may not be defined. Our recommendation is avoid using named character references—​with the exception of those defined in XML (i.e., lt, gt, amp, quot and apos). Instead, use numeric character references (e.g., &#8364;).

[4] The Zero Width Space (ZWSP) is a code point in Unicode that shows where a long word can be split if necessary.

[5] The word joiner (WJ) is a code point in Unicode prevents a line break at its position.

Environment attributes
Attribute Description Example Value

asciidoctor

Set if the current processor is Asciidoctor.

asciidoctor-version

Asciidoctor version.

1.5.4

backend

Backend used to create the output file.

html5

basebackend

The backend value minus any trailing numbers. For example, if the backend is docbook5, the basebackend is docbook.

html

docdate

Last modified date of the source document.[1,2]

2015-01-04

docdatetime

Last modified date and time of the source document.[1,2]

2015-01-04 19:26:06 GMT+0000

docdir

Full path of the directory that contains the source document.

/home/user/docs

docfile

Full path of the source document.

/home/user/docs/userguide.adoc

docname

Root name of the source document (no leading path or file extension).

userguide

doctime

Last modified time of the source document.[1,2]

19:26:06 GMT+0000

doctype

Document type (article, book or manpage).

article

embedded

Set if content is being converted to an embeddable document (body only).

filetype

File extension of the output file name (without leading period).

html

htmlsyntax

Syntax used when generating the HTML output (html or xhtml).

html

localdate

Date when converted.[2]

2016-02-17

localdatetime

Date and time when converted.[2]

2016-02-17 19:31:05 GMT+0000

localtime

Time when converted.[2]

19:31:05 GMT+0000

outdir

Full path of the output directory.

/home/user/docs/dist

outfile

Full path of the output file.

/home/user/docs/dist/userguide.html

outfilesuffix

Default file extension of output file (not the file extension of the specified output file). Value depends on backend (.html for html, .xml for docbook, etc). Safe to modify.

.html

safe-mode-level

Numeric value of the safe mode setting. (UNSAFE=0, SAFE=10, SERVER=10, SECURE=20).

20

safe-mode-name

Textual value of the safe mode setting.

SERVER

safe-mode-unsafe

Set if the safe mode is UNSAFE.

safe-mode-safe

Set if the safe mode is SAFE.

safe-mode-server

Set if the safe mode is SERVER.

safe-mode-secure

Set if the safe mode is SECURE.

user-home

Home directory of the current user. Resolves to . if the safe mode is SERVER or greater.

/home/user

Named substitutions
none

Disables substitutions

normal

Performs all substitutions except for callouts

verbatim

Replaces special characters and processes callouts

specialchars, specialcharacters

Replaces <, >, and & with their corresponding entities

quotes

Applies text formatting

attributes

Replaces attribute references

replacements

Substitutes textual and character reference replacements

macros

Processes macros

post_replacements

Replaces the line break character (+)

Counter attributes
[caption=""]
.Parts{counter2:index:0}
|===
|Part Id |Description

|PX-{counter:index}
|Description of PX-{index}

|PX-{counter:index}
|Description of PX-{index}
|===
Parts
Part Id Description

PX-1

Description of PX-1

PX-2

Description of PX-2

文本替换

Textual symbol replacements
Name Syntax Unicode Replacement Rendered Notes

Copyright

(C)
&#169;

©

Registered

(R)
&#174;

®

Trademark

(TM)
&#8482;

Em dash

--
&#8212;

 — 

Only replaced if it is a word, i.e. surrounded by white space, line start, or line end.

When white space characters are detected on both sides of the em dash, they are replaced by thin spaces (&#8201;).

ellipses

...
&#8230;

…​

right single arrow

->
&#8594;

right double arrow

=>
&#8658;

left single arrow

<-
&#8592;

left double arrow

<=
&#8656;

apostrophe

Sam's
Sam&#8217;s

Sam’s

The vertical form apostrophe is replaced with the curved form apostrophe.

任意命名的,数值或十六进制的 XML 实体引用 都支持。

文字转义

反斜线
\*Stars* is not rendered as bold text.
The asterisks around the word are preserved.

\{author} is not resolved to the author name.
The curly brackets around the word are preserved.

The backslash character is automatically removed.

*Stars* is not rendered as bold text. The asterisks around the word are preserved.

{author} is not resolved to the author name. The curly brackets around the word are preserved.

The backslash character is automatically removed.

三个加号和行内 Pass 宏
+++<u>underline me</u>+++ renders as underlined text.

pass:[<u>underline me</u>] also renders as underlined text.

underline me renders as underlined text.

underline me also renders as underlined text.

目录

文档目录
= AsciiDoc Writer's Guide
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2013-08-01
:toc:
位于右侧的目录
= AsciiDoc Writer's Guide
Doc Writer <doc.writer@asciidoctor.org>
v1.0, 2014-08-01
:toc: right
参考 目录的标题、级别和位置 可以自定义目录。

参考书目

参考资料
_The Pragmatic Programmer_ <<prag>> should be required reading for
all developers.

[bibliography]
- [[[prag]]] Andy Hunt & Dave Thomas. The Pragmatic Programmer:
  From Journeyman to Master. Addison-Wesley. 1999.
- [[[seam]]] Dan Allen. Seam in Action. Manning Publications.
  2008.

The Pragmatic Programmer [prag] should be required reading for all developers.

  • [prag] Andy Hunt & Dave Thomas. The Pragmatic Programmer: From Journeyman to Master. Addison-Wesley. 1999.

  • [seam] Dan Allen. Seam in Action. Manning Publications. 2008.

脚注

正常可重用的脚注
A statement.footnote:[Clarification about this statement.]

A bold statement.footnoteref:[disclaimer,Opinions are my own.]

Another bold statement.footnoteref:[disclaimer]

A statement.[1]

A bold statement.[2]

Another bold statement.[2]


1. Clarification about this statement.
2. Opinions are my own.

Markdown 兼容性

Markdown 可兼容语法只有在使用 Asciidoctor 可用。

Markdown 风格的标题
# Document Title (Level 0)

## Section Level 1

### Section Level 2

#### Section Level 3

##### Section Level 4

###### Section Level 5

Document Title (Level 0)

Section Level 1

Section Level 2

Section Level 3

Section Level 4
Section Level 5
带语法高亮的代码块
```ruby
require 'sinatra'

get '/hi' do
  "Hello World!"
end
```
require 'sinatra'

get '/hi' do
  "Hello World!"
end
Markdown 风格的引用
> I hold it that a little rebellion now and then is a good thing,
> and as necessary in the political world as storms in the physical.
> -- Thomas Jefferson, Papers of Thomas Jefferson: Volume 11

I hold it that a little rebellion now and then is a good thing, and as necessary in the political world as storms in the physical.

— Thomas Jefferson
Papers of Thomas Jefferson: Volume 11
Markdown 风格的带块内容的引用
> > What's new?
>
> I've got Markdown in my AsciiDoc!
>
> > Like what?
>
> * Blockquotes
> * Headings
> * Fenced code blocks
>
> > Is there more?
>
> Yep. AsciiDoc and Markdown share a lot of common syntax already.

What’s new?

I’ve got Markdown in my AsciiDoc!

Like what?

  • Blockquotes

  • Headings

  • Fenced code blocks

Is there more?

Yep. AsciiDoc and Markdown share a lot of common syntax already.

Markdown 风格的水平分割线
---

- - -

***

* * *




用户手册以及帮助

想了解更多的 Asciidoctor 及功能,请查看其他 Asciidoctor 指南 和它的 用户手册。 同时,别忘记加入 Asciidoctor 邮件列表,在这里,你可以提问题,还可以留言评论。