Asciidoctor 语法

文档架构

标题

=文档标题 (书)

在文档标题和一级标题之间的段落为摘要。

== 一级标题 (章)

=== 二级标题 (节)

==== 三级标题

===== 四级标题
====== 五级标题

如果标题不纳入 ToC 则在标题前加入分离 [discrete],有该关键字时,标题可以跳级。

=== 二级标题 (节)

[discrete]
===== 四级标题

[discrete]
==== 三级标题

include


= 我的文档

<<< (1)

include::mydoc/demo.adoc[leveloffset=1] (2)

<<<

include::mydoc/about.adoc[leveloffset=1]


[source,java]
----
include::mydoc/Hello.java[]
----
1 <<< 为 PDF 分页符号。
2 leveloffset=1 表示将 demo.adoc 的标题降 1 级,如为 -1 则为升 1 级。

水平分隔线 (Horizontal Rules)

---
- - -
***
* * *

推荐使用 - - -* * *

输出结果:


文本样式

引号替换 (Quotes Substitutions)

* *粗体* _斜体_ [line-through]#删除线# [underline]#加底线# [overline]#上标线# #高亮度#
* [yellow]#黄色# [red yellow-background]#红色黄底#  (1)
* [big]#加大# 正常 [small]#缩小# ^上标^ ~下标~
* Hello world (正常)
* `Hello world (等宽)` (2)
* "`双弯引号`" '`单弯引号`'
1 颜色可由 .css 找出 class 不适用于 PDF。
2 在输入「等宽」内容时,往往会忽略 等宽 也会有 文本样式 的功能,参阅 等宽范例

输出结果:

  • 粗体 斜体 删除线 加底线 上标线 高亮度

  • 黄色 红色黄底

  • 加大 正常 缩小 上标 下标

  • Hello world (正常)

  • Hello world (等宽)

  • “双弯引号” ‘单弯引号’


替换符若 (前后其一) 没有「字符串边界」 (字符串边界: 字符串间有非文本的字符;如空白,中英的逗号、句号、括号 …​),必须采用两个替换符。在大部份的情况前后应该会有「字符串边界」那么只需要一个替换字符。不过在某些情况需要两个替换符,如字符串第一个字或最后一个字为空白字符时,需要二个替换字符 (就算前后有「字符串边界」也一样)。

这不是*粗体*字,这也不是*粗体*(前面没有边界),这是 *粗体*(前后有边界)。
这是**粗体**字,这也是**粗体**。
**粗体** __斜体__ ##高亮度## 建议固定采用二个替换符。

符号替换 (Replacements Substitutions)

* <= 左双箭头 <- 左箭头 破折号 -- 右箭头 -> 右双箭头 =>
* 版权(C) 注册商标(R) 商标(TM) 省略号 ...
* We couldn't find Olaf's keyboard since the `'60s.

输出结果:

  • ⇐ 左双箭头 ← 左箭头 破折号 — 右箭头 → 右双箭头 ⇒

  • 版权© 注册商标® 商标™ 省略号 …​

  • We couldn’t find Olaf’s keyboard since the ’60s.

在标题中指定锚点 (ID)

[[link,label]] (1)
== 链接
1 其中的 label 为选项功能,不设置时为标题名称。设置时,则会影响 连接 的名称,本例是设置为 Link-Label

亦可采用下列格式

[#link]
== 链接

连接至内部或其他文档锚点 (宏替换 Macros Substitutions),语法如下:

<<锚点ID,标题名称>>

在不同的文档中,锚点ID 必须前置文档名称如 adoc-syntax#link。如果是本文档则锚点为 锚点ID#锚点ID 都可以。不指定 标题名称 则为缺省的名称。
注:原始语法就需要两个小于 (<<) 及两个大于 (>>),跟防替代没有关系。

link:锚点ID[标题名称]

其中的标题名称若不设置,则会显示成「锚点ID」。

链接范例
<<link>>
<<#link>>
<<adoc-syntax#link>> + (1)
<<#link, 我的链接>>

link:#link[Alias]] +
link:#link[]
1 加号 + 为换行替换 (Post Replacement Substitutions)。

连接至外部网址

https://asciidoctor.org/docs/user-manual/#url[URLs | Asciidoctor User Manual icon:external-link[set=fas]^]

[ 链接文本 ] 内的尾端加入 ^ (脱字符) 将以新分页打开链接。
另外 Icon 在 Font Awesome 4.x 为 external-link[set=fas];5.x 为 external-link-alt[set=fas]

用户接口宏

宏替换 (Macros Substitutions)

:experimental: (1)
选取菜单 menu:View[Zoom > Reset] + (2)
按下按钮 btn:[OK] + (3)
按下键盘 kbd:[F11] 以键盘宏来显示按钮 kbd:[OK] (4)

键盘左右键可用「符号替换」 +
kbd:[Ctrl , <-],kbd:[Ctrl + ->] (5)

键盘上下键可用 Unicode +
kbd:[Ctrl,↑],kbd:[Ctrl,↓]
1 文档中需设置 :experimental: 属性,才能激活本功能。
2 菜单宏。注:后面的加号 (+) 是换行符。
3 按钮宏
4 键盘宏
5 键盘宏,中间的分隔可采用 ,(逗号) 或 (加号)。
  • Ctrl++ (kbd:[Ctrl,+])

  • Ctrl+, (kbd:[Ctrl+,])

选取菜单 View  Zoom  Reset
按下按钮 OK
按下键盘 F11 以键盘宏来显示按钮 OK

键盘左右键可用「符号替换」
Ctrl+Ctrl+

键盘上下键可用 Unicode
Ctrl+Ctrl+

Ctrl+,Ctrl++

键盘上下左右键

一般::
kbd:[Ctrl,↑],kbd:[Ctrl,↓],kbd:[Ctrl,<-],kbd:[Ctrl,->]

:big-arrow-up: pass:q[[big]#↑#]
:big-arrow-down: pass:q[[big]#↓#]
:big-arrow-left: pass:q[[big]#←#]
:big-arrow-right: pass:q[[big]#→#]

big::
kbd:[Ctrl,{big-arrow-up}],kbd:[Ctrl,{big-arrow-down}],kbd:[Ctrl,{big-arrow-left}],kbd:[Ctrl,{big-arrow-right}]

Font Awesome `long-arrow-alt` (V5):: (1)
kbd:[Ctrl,icon:long-arrow-alt-up[\]],kbd:[Ctrl,icon:long-arrow-alt-down[\]],kbd:[Ctrl,icon:long-arrow-alt-left[\]],kbd:[Ctrl,icon:long-arrow-alt-right[\]]

Font Awesome `arrow`::
kbd:[Ctrl,icon:arrow-up[\]],kbd:[Ctrl,icon:arrow-down[\]],kbd:[Ctrl,icon:arrow-left[\]],kbd:[Ctrl,icon:arrow-right[\]]
1 long-arrow-alt 为 Fontawesome V5, V4 要改为 long-arrow
一般

Ctrl+Ctrl+Ctrl+Ctrl+

big

Ctrl+Ctrl+Ctrl+Ctrl+

Font Awesome long-arrow-alt (V5)

Ctrl+Ctrl+Ctrl+Ctrl+

Font Awesome arrow

Ctrl+Ctrl+Ctrl+Ctrl+

命令键 (Command key)

// Define unicode for Apple Command key.
:commandkey: &#8984;
kbd:[{commandkey} + A] (1)

// Define unicode for Windows Command key.
:commandkey: &#10070;
kbd:[{commandkey} + A]

:commandkey: &#8862;
kbd:[{commandkey} + A]
1 可采用 Unicode 字符,比较简单。

+A

+A

+A PDF 不支持,因为超出字集。

防止替换

由于 Asciidoctor 定义各式特殊字符,当需要正确显示特殊字符时,需要「防止替换」。
如刚好是 #abc# 则在字符串的前后加上 ++ 或者采用在字符串前面采用 \ (反斜线) 转译。

  • 采用 \ (反斜线) 转译,某些情况必须采用两个反斜线。

  • 字符串前后加一个加号 (+) (如没有「字符串边界」则要两个加号),或两个钱号 ($$) (不推荐使用)。

  • 字符串前后加上三个加号 (+++),行内透通 (Inline Passthroughs) 可直接输出 HTML。
    采用 pass:[] 宏,跟上述一样,缺省为透通。
    不适用于 PDF,参阅: Passthrough Content | Asciidoctor Docs

上述为 宏替换 (Macros Substitutions)

  • 等宽字体时,采用 `+TEXT+` 的特殊格式,将防止替换文本以双封套包围 (外框需要「字符串边界」),反引号包围加号再包围文本。

加号 (+) 防止替换有三种方式,一、二、三个加号的框都可以,建议固定采用二个加号框 ++防止替换++
防止替换范例
网址为 \https://asciidoctor.org/docs/user-manual/ + (1)
`+**星星**+`。 + (2)
+**星星**+ 。 + (3)
pass:[**星星**]。 +
+++<u>underline me</u>+++ + (4)
pass:[<u>underline me</u>] (4)
1 PDF 查看器可能将网址转成连接,别误判。
2 采用 `+TEXT+` 外框需要「字符串边界」。
3 单加一个加号需要「字符串边界」。
4 本例同等于 [underline]#underline me#
注:透通不适用于 PDF。
防止替换结果

网址为 https://asciidoctor.org/docs/user-manual/
**星星**
**星星** 。
**星星**。
underline me
underline me

等宽情况

「等宽」一般情况大部份是输入关键字,但往往会忽略 等宽 的内容也会有 文本样式 的功能,如下

等宽范例
input `*TEXT*` + (1)
input `+*TEXT*+` (2)
1 后面的加号 (+) 是换行符,不是防止替换。
2 防止替换等宽内容。
等宽结果

input TEXT
input *TEXT*

列表 (List)

无序、串行列表

Unordered list
* deep 1
** deep 2
*** deep 3
**** deep 4
***** deep 5
* deep 1
  • deep 1

    • deep 2

      • deep 3

        • deep 4

          • deep 5

  • deep 1

Unordered list 显示成 square
[square]
* one
* two
* three
[square]
  • one

  • two

  • three

[circle]
  • one

[disc]
  • one

[none]
  • one

[no-bullet]
  • one

Ordered list
. Order 1
. Order 2
.. Order 2a
.. Order 2b
. Order 3
  1. Order 1

  2. Order 2

    1. Order 2a

    2. Order 2b

  3. Order 3

[start=开始数值]
. Order 1

[start=3]
. Order 3
. Order 4
  1. Order 1

  1. Order 3

  2. Order 4

反转列表 [%reversed] 数值反排列
[%reversed]
. Order 3
. Order 2
. Order 1
  1. Order 3

  2. Order 2

  3. Order 1

检查清单

Checked list
- [*] checked
- [x] checked
- [ ] unchecked
-     normal

如果是行内的 icon:check-square-o[] checked 可采用 `+icon:check-square-o[] checked+`, +
icon:square-o[] unchecked 则为 `+icon:square-o[] unchecked+`。

[options="interactive"]
.[options="interactive"]
* [x] Milk 请按我取消打勾
* [*] Chocolate
* [ ] Sugar
  • checked

  • checked

  • unchecked

  • normal

如果是行内的 checked 可采用 icon:check-square-o[] checked
unchecked 则为 icon:square-o[] unchecked

[options="interactive"]
  • Milk 请按我取消打勾

  • Chocolate

  • Sugar

描述列表 (Description)

一个或多个术语描述,可采用描述列表:

CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.

缺省每个项目的内容都显示在描述下方,以下是此列表的呈现方式:

CPU

The brain of the computer.

Hard drive

Permanent storage for operating system and/or user files.

要使描述和内容显示在同一行上,则加入水平样式 [horizontal]

[horizontal]
CPU:: The brain of the computer.
Hard drive:: Permanent storage for operating system and/or user files.
CPU

The brain of the computer.

Hard drive

Permanent storage for operating system and/or user files.

描述阶层及混合三种列表类型

Operating Systems::
  Linux:::
    . Fedora
      * Desktop
    . Ubuntu
      * Desktop
      * Server
  BSD:::
    . FreeBSD
    . NetBSD
Operating Systems
Linux
  1. Fedora

    • Desktop

  2. Ubuntu

    • Desktop

    • Server

BSD
  1. FreeBSD

  2. NetBSD


描述列表问题

原代码区块的标注 (Callouts) 之后如果有「描述列表」,如果要分开「描述列表」,增加空行及注解来解决。 事实上,不只区块会有非预期合并的情况,「水平分隔线」也可能合并,需要增加空行及注解来分开。

----
Callouts <1>
----
<1> Callouts

接续的描述列表:: 本段会接续 Callouts,空行并无作用。

//
分开的描述列表:: 如果要分开,增加空行及注解来解决。

描述列表问题结果:

Callouts (1)
1 Callouts
接续的描述列表

本段会接续 Callouts,空行并无作用。

分开的描述列表

如果要分开,增加空行及注解来解决。


Q&A

[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

区块 (Block)

原代码区块

含标注 (callouts) 的原代码区块

[source,ruby]
----
require 'sinatra' <1>

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

get '/hi' do  (2) (3)
  "Hello World!"
end
1 Library import
2 URL mapping
3 Response block

原代码区块 (Listing block) 缺省为自动换行 (prewrap 可修改默认值),若要取消自动换行,可采用 source%nowrap。如:

[source%nowrap,ruby]
----
----

原代码区块替换样式

原代码区块的 Substitutions (替换) 为 Verbatim,只支持 Special characters

原代码区块语法
[source,语言高亮度,subs="增减替换[, 增减替换]"]
增减替换
引号替换范例
[source, java, subs="+quotes"]
----
System.out.println("Hello *bold* text").
----
HTML 输出结果
System.out.println("Hello bold text").
PDF 输出异常
Asciidoctor-pdf 无法同时处理具有「语法高亮度」及「替换样式」的情况,PDF 输出如下:
System.out.println("Hello <strong>bold</strong> text").
[subs="+quotes"] 不采用语法高亮度 PDF 跟 HTML 一致
System.out.println("Hello bold text").
替换 (Substitutions) 顺序说明
:extlink: icon:external-link-alt[set=fas]^
[subs="+attributes,+macros"] (1)
----
连接到 https://www.google.com[www.google.com {extlink}]
----

[subs="+macros,+attributes"] (2)
----
连接到 https://www.google.com[www.google.com {extlink} ^]
----
1 先替换 attributes 即为替换变量 {extlink} 再替换 macros (「连接」为宏替换)。
2 先替换 macros 再替换 attributes 显然不正确。

Pass 宏

原代码已经有不少的替换字符,若再设置 subs="+quotes" 无法保证正确。
注:PDF 不支持 Pass 宏。

echo "s/pattern<'[a-z]\+'>/pattern<'change'>/"

将 Block 设置为 subs="+macros" 激活 宏替换

[source,bash,subs="+macros"]
----
echo ++"s/pattern<'[a-z]++pass:q[#\+#]++'>/pattern<'change'>/"++
----
echo "s/pattern<'[a-z]\+'>/pattern<'change'>/"
Pass 语法
pass:q[] (1)
pass:quotes[] (1)
pass:a,c,q[] (2)
pass:[] (3)
1 这二个相等
2 使用多个「替换」。
3 未使用任何「替换」直接透通输出。
Pass 替换选项可采用缩写
  • c = Special characters (只能用缩写,其他可用单字)

  • q = quotes

  • a = attributes

  • r = replacements

  • m = macros

  • p = post_replacements (只能用缩写,其他可用单字)

  • v = verbatim

  • n = normal

范例区块

.Title (这是范例)
====
Example
====

以下为输出结果:

Title (这是范例)

Example

.Title (这是范例)
****
Sidebar
****

以下为输出结果:

Title (这是范例)

Sidebar

提示 (Admonition)

简单提示

.NOTE, TIP, WARNING, CAUTION, IMPORTANT

Admonition demo

NOTE: Note

TIP: Tip

WARNING: Warning

CAUTION: Caution

IMPORTANT: Important

以下为输出结果:

NOTE, TIP, WARNING, CAUTION, IMPORTANT

Admonition demo

Note
Tip
Warning
Caution
Important

提示加入标题

.Title
TIP: Tip

以下为输出结果:

Title
Tip

范例区块提示,配合 [<LABEL>] 属性加入标签或图标,可采用 ==== 作为范围。

.Title
[TIP]
====
Tip1 +
Tip2
====

以下为输出结果:

Title

Tip1
Tip2

引言 (Quote)

[quote, 作者 (选项), 出处 (选项)]
____
行1
行2
____

以下为输出结果:

行1 行2

— 作者 (选项)
出处 (选项)

诗句 (Verse)

.诗句 (Verse)
[verse, 作者 (选项), 出处 (选项)]
____
行1 (1)
行2
____
1 不需要换行符 (+)。

以下为输出结果:

诗句 (Verse)
行1
行2
— 作者 (选项)
出处 (选项)

参考 Asciidoctor User Manual : Admonition | Asciidoctor User Manual

区块运用

提示 (Admonition) 可加上外框。
注:Asciidoctor 样式主题中的 Admonition 必须透明,如 Asciidoctor 主题。

NOTE: 无外框

====
NOTE: 外框为范例区块
====

****
NOTE: 外框为花絮区块
****

以下为输出结果:

无外框
外框为范例区块
外框为花絮区块

嵌套区块

==== (1)
第一层
===== (2)
第二层
===== (2)

**** (1)
花絮区块 (第二层)
***** (2)
花絮区块 (第三层)
***** (2)
**** (1)

---- (1)
原代码区块
----- (2)
原代码区块,不支持多层。
----- (2)
---- (1)
====
1 四个字
2 五个字

以下为输出结果:

第一层

第二层

花絮区块 (第二层)

花絮区块 (第三层)

原代码区块
-----
原代码区块,不支持多层。
-----

透通区块

文本内容直接输出,可直接输出 HTML。不适用于 PDF,参阅: Passthrough Content | Asciidoctor Docs

应用于 CSS 的范例
= Doc Title (1)
ifndef::backend-pdf[]
++++
<style>
h1, h2, h3 {
  background-color: red;
}
</style>
++++
endif::[]
1 位置只能在 Doc Title 下面,否则会有非预期错误,如 @asciidoctor/core 出错: asciidoctor: ERROR: adoc-syntax.adoc: line 38: level 0 sections can only be used when doctype is book。
Browsers 会先取 CSS 再处理 HTML,CSS 在 Doc Title 之后,并不会有问题。
应用于 HTML 直接输出的范例
++++
<u>underline me</u> is underlined.
++++

内置区块总结 (Built-in blocks summary)

Built-in blocks summary 的定义如下:

区块
Block

区块名称
Block Name

边界符
Delimiter

目的
Purpose

替换
Substitutions

Admonition

[<LABEL>]

====

Aside content that demands special attention; often labeled with a tag or icon

Normal

Comment

N/A

////

Private notes that are not displayed in the output
不会输出的注解 (Comment) 区块

None

Example

[example]

====

Designates example content or defines an admonition block
范例 (example) 区块或提示 (admonition) 区块

Normal

Fenced

N/A

```

Source code or keyboard input is displayed as entered
原代码或文本内容输出

Verbatim

Listing

[listing]

----

Source code or keyboard input is displayed as entered
同上

Verbatim

Literal

[literal]

....

Output text is displayed exactly as entered
文本内容输出

Verbatim

Open

Most block names

--

Anonymous block that can act as any block except passthrough or table blocks
开放区块,除了 passthroughtable 区块之外,配合 [Block Name] 属性可以充当各种区块。

Varies
可变

Passthrough

[pass]

++++

Unprocessed content that is sent directly to the output
透通区块,内容直接 (透通) 输出,可输出 HTML。

None

Quote

[quote]

____

A quotation with optional attribution
可选属性的引言

Normal

Sidebar

[sidebar]

****

Aside text and content displayed outside the flow of the document
文档流程之外的花絮内容

Normal

Source

[source]

----

Source code or keyboard input to be displayed as entered. Will be colorized by the source highlighter, if enabled on the document.
原代码或文本内容输出,支持语法高亮度。

Verbatim

Stem

[stem]

++++

Unprocessed content that is sent directly to an interpreter (such as AsciiMath or LaTeX math)
内容直接 (透通) 输出,可输出 HTML。

None

Table

N/A

|===

Displays tabular content
配合 表格样式 (Style) 可设置为一般替换或 Literal 区块。

Varies

Verse

[verse]

____

A verse with optional attribution
可选属性的诗句,换行时不需要换行符。

Normal

区块样式可由下列来决定
  • 由 边界符 (Delimiter) 来决定。

  • 区块名称 (Block Name);区块范围可由开放边界符 (--) 来设置。

原代码 (source) 区块范例
----
Source block

line3
----

[source] (1)
--
Source block

line3
--

[source] (1)
Source block

line3 (2)
1 开放区块由区块名称 (Block Name) 来决定样式,如 [source][quote][sidebar] …​
2 没有开放边界符 (--),不在区块范围之内。

替换 (Substitutions)

Substitution groups
Group Special characters Quotes Attributes Replacements Macros Post replacements

Header

None

Normal

Pass

Verbatim

subs 区块替换
subs 区块替换可将 Normal 的区块加入 (或取消) 替换,但如果该区块为 Normal,无法以 subs 取消替换。
Special characters 特殊字符替换

除了 PassthroughComment 区块之外,将特殊字符的三个字符 < > & 替换成 &lt; &gt; &amp; 能看到这三个字符 < > & 表示特殊字符替换已运作,无法让它不运作否则会产生不合法的 HTML。
另外输出成 HTML 代码 <strong>粗体</strong>,这些代码也是需要特殊字符替换。

Quotes 引号替换

参阅:引号替换

Attributes 属性替换

引用变量 (属性),如变量 {VAR}

Macros 宏替换

包含 Pass 宏用户接口宏连接防止替换及图片。

Replacements 符号替换

参阅:符号替换

Post replacements 换行替换

替换 换行字符 +。Block 设置为 subs="post_replacements"

Callouts 标注替换

除了 passthroughtable 区块之外,缺省会处理 Callouts 替换,使用 subs="-callouts" 取消替换。
Incremental Substitutions | Asciidoctor User Manual

特殊字符替换说明

以 pass 宏输出 HTML 代码。

[subs="macros"]
----
pass:q,c[*粗体* _斜体_]
----
输出结果
<strong>粗体</strong> <em>斜体</em>

pass (透通) 输出 HTML

[subs="macros"]
----
pass:[<strong>粗体</strong>]
pass:[&lt; &gt; &amp;]
----
输出结果 (你看到的是可视字符)
粗体
< > &

测试 pass (透通)
注:仅限测试 HTML,若输出 docbook 则会出错。

[subs="macros"]
----
pass:[> < &]
----
输出结果 (不会变成不合法的 HTML)
> < &

区块可采用 subs="verbatim" 输出 HTML 代码。
将区块内的文本先经过「引号替换 (quotes)」转换成 HTML 代码,再以「特殊字符替换 (verbatim)」输出为可视字符。

[subs="quotes,verbatim"] (1)
----
*粗体* _斜体_
----
1 替换 (Substitution) 并没有前置加号 (+),如果有加号表示附加,则不会输出 HTML 代码。
输出结果
<strong>粗体</strong> <em>斜体</em>

字符属性 (变量) 替换

如采用 {blank} (Attributes 属性替换) 将列表填入空值。

. {blank} +
Line1
. {blank} +
Line2

. {blank}
+
----
print("one")
----
. {blank}
+
----
print("one")
----

  1. Line1


  2. Line2

  3. print("one")
  4. print("one")

当表格中需要 | 字符时,需以字符属性 {vbar} 来替换。

|====
| 以 +{vbar}+ 来显示出 {vbar}
|====

以 {vbar} 来显示 |

表格 (Table)

表格语法范例
[width=75%, cols="1,1,3"]
|===
|R1C1 |R1C2 |R1C3
|R2C1 |R2C2 |R2C3
|===
整体宽度占页面 75%,栏宽的百分比为 20% 20% 60%。

R1C1

R1C2

R1C3

R2C1

R2C2

R2C3

表格属性:
  • options
    选项=选项值 可以简化成 %选项值,如 [options="header"],可简化成 [%header];若为「简化选项」,属性位置需放置在前面。 options 可为 headerfooterbreakableunbreakableautowidthautowidth.stretchrotate

  • stripes 表格阴影 stripes= none | odd | eve | al | hover

  • cols

  • width

  • grid, frame grid= all | rows | cols | noneframe= all | topbot | sides | none

  • format format= psv | dsv | csv | tsv

  • align align= left | center | right

  • halign hlign= left | center | right

  • valign valign= top | middle | bottom

  • orientation orientation=landscape

  • float float= left | right

表头表尾 (options)

[options="header"] 将第一行设为表头

[options="header"]
R1C1 R1C2

R2C1

R2C2

在表头下面加入一行,效果一样,不需要 options="header"。

|===
|R1C1 |R1C2

|R2C1 |R2C2
|===

另外 options="header" 可以简化成 %header,如下述的 options="footer" 简化成 %footer[%footer] 将最后行设为表尾 (没有粗体)。

[%footer]

R1C1

R1C2

R2C1

R2C2

表格阴影 (stripes)

指定 stripes 来设置阴影,如:
  • stripes=none
    不做阴影处理 (Asciidoctor >= 2.0 默认值)
    注: 文档设置属性方式为 :table-stripes: even

  • stripes=odd
    偶数行加阴影 (Asciidoctor < 2.0 默认值)

  • stripes=even
    奇数行加阴影

  • stripes=all
    所有行均加阴影

  • stripes=hover
    鼠标行阴影 (仅HTML)

[stripes=even]
Title1 Title2

R1C1

R1C2

R2C1

R2C2

R3C1

R3C2

[stripes=hover]

R1C1

R1C2

R2C1

R2C2

R3C1

R3C2

栏属性 (cols)

Asciidoctor 提供 cols 栏属性应用于整栏,栏属性可包含以下:
  1. 对齐方式 (align)

  2. 宽度 (width)

  3. 样式 (style) (只能设一种「样式」,不支持多个「样式」。)

同时有对齐、宽度、样式需注意顺序,如 cols="^1h"
^:对齐 1:宽度 h:样式。

每个字段以逗号 , 区分,每个字段至少要有一种属性,当多个字段有相同的属性时采用乘号(*),如 cols="5,3*m",表示第一个字段宽度倍率 5,再来三个相同的字段 (3*) 其样式为 m,共 4 个字段。

[cols="5,3*m"]
|===
|Column 1 |Column 2 |Column 3 |Column 4

|Cell in column 1
|Cell in column 2
|Cell in column 3
|Cell in column 4
|===
Column 1 Column 2 Column 3 Column 4

Cell in column 1

Cell in column 2

Cell in column 3

Cell in column 4

单元格对齐

水平对齐方式
[cols="<,^,>"]
|===

靠左

水平居中

靠右

垂直对齐方式
[cols=", .<, .^, .>"] (1)
1 点 (.) 之后为垂直对齐,点 (.) 之前为水平对齐 (本例没有指定,缺省为靠左)。
注:逗号 (,) 为分栏 (混在一起看起来有点乱)。

第一栏
有两行

靠上

垂直居中

靠下

单元格对齐范例
[cols=4*]
|===
| 第一栏 +
有两行 (R1)
<.<|左上方 ^.<|居中靠上 >.<|右上方
| 第一栏 +
有两行 (R2)
<.^|居中靠左 ^.^|水平及垂直居中 >.^|居中靠右
| 第一栏 +
有两行 (R3)
<.>|左下方 ^.>|居中靠下 >.>|右下方
|===

第一栏
有两行 (R1)

左上方

居中靠上

右上方

第一栏
有两行 (R2)

居中靠左

水平及垂直居中

居中靠右

第一栏
有两行 (R3)

左下方

居中靠下

右下方

表格宽度

[width=75%] (width) 表格整体宽度占页面 75%

[width=75%]

Cell in row 1, column 1

R1C2

R1C3

[%autowidth] (options) 单元格宽度根据内容决定

[%autowidth]

Cell in row 1, column 1

R1C2

R1C3

[%autowidth.stretch] (options) 表格宽度延伸 (stretch) 为页面,栏宽依据内容决定倍率。

[%autowidth.stretch]

Cell in row 1, column 1

R1C2

R1C3

注: DocBook 转换器无法识别 autowidth 属性。


[cols="1,4"] 按比例调整各栏的宽度,单元格宽度百分比为 20% 80%。

[cols="1,4"]

R1C1

R1C2

如指某栏为固定倍率,其他栏的宽度为自动宽度 (意思是不设置宽度),可指定 ~ 作为栏宽度。 在该情况宽度值被假定为百分比值 (即基于100)。

[cols="35h, ~, ~"] 设置第一栏为 35%,其他栏 (C2 C3) 不指定宽度。

[cols="35h, ~, ~"]

Cell in row 1, column 1

R1C2

R1C3

跟 [cols="35h, 32, 33"] 类似 (因为 65 无法整除 2)

[cols="35h, 32, 33"]

Cell in row 1, column 1

R1C2

R1C3

在产生 PDF 时,可能会因为栏宽比例无法分配,造成错误,不会产生表格。

在 Asciidoctor PDF 2.3.4 会显示 asciidoctor: ERROR: cannot fit contents of table cell into specified column width

而 Asciidoctor PDF 2.0.0.dev 则会错误 82: from /home/user/bin/asciidoctor-pdf:23:in `<main>'

表格样式 (Style)

样式名称 描述

AsciiDoc

a

几乎支持全部替换的功能。

Emphasis (强调)

e

斜体 (实际上斜体反向) Default

Header (表头)

h

应用于栏表头 Default

Literal (文本)

l

内容视为在 Literal 区块,不做文本替换。

Monospaced (等宽)

m

等宽字体 Default

None (缺省))

d

文本的处理方式跟普通段落一样 Default

Strong (粗体)

s

粗体 (实际上粗体反向) Default

Verse (诗句)

v

内容视为在诗句区块 Default

Default:文本的处理方式跟普通段落一样。

(表格)栏样式范例

以下第二行内容全部为 * U *粗* _斜_ N `L` <<link>> {VAR} pass:[#] \*B*
注: {VAR} 是由 :VAR: 变量测试 来设置成 变量测试

[cols="a,e,h,l"]

a

e (斜体)

h (栏表头)

l (Literal 区块)

* U N L Link-Label 变量测试 # *B*

* U N Link-Label 变量测试 #

* U *粗* _斜_ N `L` <<link>> {VAR} pass:[#] \*B*

* Ua 显示成无序列表,在 HTML 字体比 d (缺省) 大一些。

[cols="m,d,s,v"]

m (等宽)

d (缺省)

s (粗体)

v (诗句区块)

* U N L Link-Label 变量测试 # *B*

* U N L Link-Label 变量测试 # *B*

* U N L Link-Label 变量测试 # *B*

* U N L Link-Label 变量测试 # *B*

测试反斜线转译 \|===

[cols="h,l,m,d"]

h

l

m

d

|===

|===

|===

|===

注:a 无法转译 \|=== 无法表现。

栏样式 (Style)

[cols="^1h,4"] (^ 为水平置中)

R1C1

R1C2

R2C1

R2C2

单元格样式 (Style)

指定单元格为「表头」,h|R1C1h|R2C2 为「表头」

|===
h|R1C1 |R1C2
|R2C1 h|R2C2
|===

R1C1

R1C2

R2C1

R2C2

单元格跨行、跨栏及重复栏

[cols=3*]
|===
2+|跨栏 (R1C1~R1C2) (1)
|R1C3
.2+|跨行 (R2C1~R3C1) (2)
|R2C2 |R2C3
|R3C2 |R3C3
2.2+|跨行跨栏 (R4C1~R5C2) (3)
|R4C3
|R5C3
3*^m|重复栏 (R6) (4)
|===
1 2+ 加号 (+) 前的数字表示这个单元格跨越多栏。
2 .2+ 点 (.) 之后的数字指定要跨越的行数,加号 (+) 指示此单元格跨越多行,本例实际上是 .2+^.^ 加上水平及垂直居中。
3 2.2+ 可将「栏」及「行」的数字结合起来,点 (.) 之前的数字是要跨越的栏数,点 (.) 之后的数字是要跨越的行数,本例实际上 2.2+^.^ 加上水平及垂直居中。
4 3*^m 重复 3 栏并设成水平置中及等宽字体 (注意顺序)。

跨栏 (R1C1~R1C2)

R1C3

跨行 (R2C1~R3C1)

R2C2

R2C3

R3C2

R3C3

跨行跨栏 (R4C1~R5C2)

R4C3

R5C3

重复栏 (R6)

重复栏 (R6)

重复栏 (R6)

表格边框线 (grid, frame)

grid 设置表格单元格的边框,可选值为 rowscolsnone

[grid=rows]

R1C1

R1C2

R1C3

R2C1

R2C2

R2C3

[grid=cols]

R1C1

R1C2

R1C3

R2C1

R2C2

R2C3

[grid=none]

R1C1

R1C2

R1C3

R2C1

R2C2

R2C3

Frame 设置表格边框,可选值为 topbotsidesnone

[frame=topbot, grid=none]

R1C1

R1C2

R1C3

R2C1

R2C2

R2C3

[frame=sides, grid=none]

R1C1

R1C2

R1C3

R2C1

R2C2

R2C3

[frame=none, grid=none]

R1C1

R1C2

R1C3

R2C1

R2C2

R2C3

Table format

format= psv | dsv | csv | tsv

CSV 格式
[format=csv]
|===
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

嵌套 (Nested) Tables

表格样式 a 可嵌入嵌套表格,为了区分嵌套表格需要区分字符 !===,缺省的区分字符是 !

[cols="1,2a"]
|===
| R1C1 | R1C1
| R2C1 |
[cols="2,1"]
!===
! R1C1 ! R1C2
! R2C1 ! R2C1
!===
|===
A nested table

R1C1

R1C1

R2C1

R1C1

R1C2

R2C1

R2C1

表格运用

把「表格」当做「区块」来使用。

内容放入表格及表格位移
.The print command
[cols="a",frame="none",grid="none"]
|===
|
Print text to screen.

.print example
----
print "Hello World"
----
|===

[cols="2,~a",frame="none",grid="none"]
|===
||
.Another method
----
print 'Hello World'
----
|===
The print command

Print text to screen.

print example
print "Hello World"
Another method
print 'Hello World'
图像放入表格
|====
|image:images/winlin/sunset.jpg[]
|image:images/winlin/sunset.jpg[]
<.^|Sunset pictures
^|Left |Center |
|====

sunset

sunset

Sunset pictures

Left

Center

CSS class

区块可套用 (任何的) CSS Class,以套用现有的对齐 Class 为例, 指定对齐 Class [.text-left][.text-center][.text-right]。(不适用于 PDF)

[.text-center]
====
对齐中间
====

对齐中间

指定浮动对齐 (float) class [.left][.right],若要显示在同一个段落,可在浮动范围中使用浮动组。(不适用于 PDF)

====
[.float-group]
--
[.left]
left

[.right]
right
--
====

左边浮动对齐

右边浮动对齐

图片

图片区分如下
  • 区块图片 (Block Image) 占据整个区块,语法为 image:: (两个冒号)

  • 行内图片 (Inline Image) 嵌入文本行中或行为像文本,语法为 image: (一个冒号)

图片对齐属性包含以下:
  • 区块图片 (Block Image) 的 align (对齐) 选项为 left, center, right。

  • 行内图片 (Inline Image) 以 role (规则) 设置位置,选项为 left, right, th(thumb), rel(related)。

  • float (浮动对齐) 的选项为 left, right,可对齐区块图片及行内图片。

区块图片范例 (注意两个冒号)
image::images/winlin/sunset.jpg[alt=sunset, width=500, height=375, align=center] (1)
image::images/winlin/sunset.jpg[sunset, 500, 375, align=center] (2)
image::images/winlin/sunset.jpg[sunset, 500, align=center]
image::images/winlin/sunset.jpg[sunset, align=center]
1 本图实际的尺寸为 500W x 375H,这四个例子完全一样。
2 可不指定 alt width height,参数顺序为 1:alt 2:宽 3:高。
sunset

区块图片 (Block Image) 对齐 (align)

区块图片 (Block Image) 对齐的 align 选项为 left, center, right

image::images/winlin/sunset.jpg[Sunset,160,align=left]
image::images/winlin/sunset.jpg[Sunset,160,align=center]
image::images/winlin/sunset.jpg[Sunset,160,align=right]
Sunset
align=left
Sunset
align=center
Sunset
align=right

三个图片为个别的区块 (div)。

行内图片 (Inline Imags) 规则 (role)

行内图片 (Inline Imags) 可以使用 role (规则) 设置位置,选项为 left, right, thumb, related.

image:images/winlin/sunset.jpg[Sunset,100, role=left, title="role=left"]
image:images/winlin/sunset.jpg[Sunset,100, role=left, title="role=left"]
image:images/winlin/sunset.jpg[Sunset,100, role=right, title="role=right"]
image:images/winlin/sunset.jpg[Sunset,100, role=right, title="role=right"]
image:images/winlin/sunset.jpg[Sunset,80, role=thumb, title="role=thumb"]
image:images/winlin/sunset.jpg[Sunset,80, role=thumb, title="role=thumb"]
image:images/winlin/sunset.jpg[Sunset,60, role=related, title="role=related"] (1)
image:images/winlin/sunset.jpg[Sunset,60, role=related, title="role=related"]
1 Asciidoctor 网站有提到 related 选项,不过 css 并没有实作。

Sunset Sunset Sunset Sunset Sunset Sunset Sunset Sunset

将鼠标移至图片上方可得知 role

图片浮动对齐 (float)

图片 float (浮动对齐) 选项为 left, right 支持 行内图片 (Inline Image) 及 区块图片 (Block Image),若要显示在同一个段落,可在浮动范围中使用浮动组。(不适用于 PDF)

[.float-group]
--
[.left]
.Image Left (Inline Image)
Left image:images/winlin/sunset.jpg[Sunset,160] Right +
Bottom

.Image Right (Block Image)
[.right]
image::images/winlin/sunset.jpg[Sunset,160]
--
Image Left (Inline Image)

Left Sunset Right
Bottom

Sunset
Image Right (Block Image)

文绕图 (Block Image Float)

[.float-group]
--
image::images/winlin/sunset.jpg[Sunset,100,float=right]
文绕图说明 ...
--

以下的实际的输出并未使用浮动组,可以看到图片超出范围,如果文本内容不足则应该加上浮动组。

Sunset

Positioning roles | Asciidoctor User Manual Roles for positioning images 表格中,提到 Float 支持区块图片 (Block Image),意思是先写 Block Image 段落之后输入说明文本,则会「文绕图」,文绕图并不适合再加入(文本)区块。

Font Awesome

文档中需设置 :icons: font 属性,激活本功能。

图标大小

图标第一个属性,设置值可为 1x (缺省 1em), 2x (2em), 3x, 4x, 5x, lg (大 1.3333em), fw (固定宽度 1.25em)。
不适用于 PDF 的尺寸:sm (小 .875em), xs (超小 .75em)。

icon:heart[2x] (1)
icon:heart[size=2x] (1)
1 上述二者相等。
图标大小范例
Do you want to drink a small icon:cocktail[] or a tall icon:beer[2x,title=pint] ?

Do you want to drink a small or a tall ?

1x lg 2x

1x (sm xs 不适用于 PDF)

图标旋转

rotate= 90 | 180 | 270 或 flip= horizontal | vertical。(不适用于 PDF)

图标旋转范例
icon:flag[rotate=90, flip=vertical]

rotate= 90 | 180 | 270

flip= horizontal | vertical

Roles

不适用于 PDF

icon:heart[role=blue]

role=green | yellow | red


Spin pulse and border

可应用 .css 内的 class,如 fa-border,去掉 fa- 为 border 即为套用值 [border]。(不适用于 PDF)

icon:cog[spin] icon:spinner[pulse] icon:cog[border] (1)
1 spin 为旋转,pulse 为一秒一次脉冲。

Asciidoctor 属性 (Attributes)

文档目录 (ToC)

toc

激活文档目录功能,设置值为 auto、left、right、macro 或 preamble。若 ToC 要在最上方则设为 auto (没有 top 的设置值)。

toclevels

ToC 的阶层,该设置值为 1 时,只会产生第 1 阶的 ToC。

toc-title

ToC 的标题文本;缺省为 Table of Contents。

章节标题

sectnums

激活标题中前置章节数字 (缺省为未激活),如 我的标题 将变成 1. 我的标题

sectnumlevels

设置章节数字阶层,如 1.1. 章节,该值设置为 1 时,则不会前置章节数字,变成只有 章节

(上述两者同时影响 ToC 的项目文本。)

sectids

章节产生 html 的 ID,缺省为激活。

sectanchors

激活时,当鼠标悬停在节标题上方时,会显示一个分节符号 (§) 链接标题 ID。

notitle

不显示 (产生) 文档标题。

标题文本

example-caption

设置 Example block (四个=) 标题文本;缺省为 Example, 可采用 example-caption! 取消标题文本。
那可以将 example-caption 设置成空值来取消?
哈!那真的只是「取消标题文本」而显示编号。

example-number

指定 Example block 开始编号,如为 10,那么下一个则为 Example 11. <Your example name>

table-caption

设置表格标题文本;缺省为 Table。

table-number

指定表格标题开始编号。

figure-caption

设置图片标题文本;缺省为 Figure。

figure-number

指定图片标题开始编号。

caption

设置所有标题文本,如在文档内设置 :caption: my title,那么 example、table、figure 的标题文本都为 my title 而且没有编号,文档内设置 :caption: (由于没有设置值) 则表示取消所有标题文本。
Document how to turn off / disable all kind of captions

last-update-label

页脚中 Last updated 标签文本。

HTML

linkcss

是否链接样式表,而不是嵌入样式表。

copycss

是否输出 CSS 文件 (Copy CSS files to output)。

iconfont-remote

是否使用 CDN 来解析图标字体。

stylesheet

设置 asciidoctor 的 CSS 文件。

一般属性 (未分类)

experimental

激活用户接口宏 (button, menu and kbd)。

prewrap

Listing block (原代码区块) 自动换行,该属性已缺省激活,采用 prewrap! 取消自动换行。

table-stripes

设置表格的底色,可设置值为 none、even、odd、all。亦可在 table 设置如 [stripes=all]

icons

设置值为 fontimagesvg,如在文档内设置 :icons: font 激活图标字体 (Font Awesome) 的功能。

icon-set

图标字体集可设置值为 fafas …​,参阅 Font and Image Icons (仅支持 asciidoctor-pdf)

source-highlighter

语法高亮度处理可选 coderayhighlight.jspygmentsrouge
注:Asciidoctor.js Live Preview 只支持 highlight.js

取消属性可在后面加上 !,如 example-caption!

设置属性,依据不同的程序其设置方式并不相同,如下范例:

设置 toc-title (目录标题) 为 My Content
激活图标字体。
取消「用户接口宏」。

  • 在文档中设置如下

    :toc-title: My Content
    :icons: font
    :experimental!:
  • asciidoctor 命令行参数

    asciidoctor -a toc-title='My Content' -a icons=font -a experimental!
  • @asciidoctor/core 选项设置

    const html = asciidoctor.convert(content,
    {
      attributes: {
        'toc-title': 'My Content',
        icons: 'font',
        experimental: false
      }
    }
    )
  • 在预览工具 Firefox / Chrome Asciidoctor.js Live Preview

     toc-title=MyContent icons=font experimental! icons=font (1)
    1 Asciidoctor.js Live Preview 已缺省 icons=font

其他

变量

在文档使用 :变量名称: 变量内容 的语法设置,引用时为 {变量名称}
:变量名称: 变量内容
{变量名称}
多行变量
:long-value: 变量内容太长时采用 \
作为换行符,引用时换行符不可见。
多行变量强制换行
:hard-line-breaks: 变量内容太长时采用 + \
强制换行

条件预处理器

判断 docbook 作为不同处理时,以 backend-docbook5 属性判断, 亦可判断文档 (自订) 属性,在文档中的变量也是文档的属性。

ifdef::backend-docbook5[]
只在编译 docbook 才有本内容。
endif::[]

ifndef::backend-docbook5[]
编译 非 docbook 的其他类型时才有本内容。
没有 else 的功能,采用两组 ifdef ifndef 来处理
endif::[]

使用 TOC 宏输出文档目录

:toc: macro (1)
:toc-title: (2)
= 我的书

== 前言
说明 ++:toc: macro++ 用法

== 我的目录
toc::[] (3)

== 第一章
1 设置 :toc: macro,可在文档中任何位置使用宏 toc::[]
2 设置 ToC 的标题文本为空白。
3 使用宏 toc::[] 显示目录。