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
开放区块,除了 passthrough 或 table 区块之外,配合 [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 特殊字符替换

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

Quotes 引号替换

参阅:引号替换。

Attributes 属性替换

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

Macros 宏替换

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

Replacements 符号替换

参阅:符号替换。

Post replacements 换行替换

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

Callouts 标注替换

除了 passthrough 或 table 区块之外,缺省会处理 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 可为 header、footer、breakable、unbreakable、autowidth、autowidth.stretch、rotate

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

  • cols

  • width

  • grid, frame grid= all | rows | cols | none,frame= 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*

* U 在 a 显示成无序列表,在 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|R1C1,h|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 设置表格单元格的边框,可选值为 rows、cols 或 none。

[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 设置表格边框,可选值为 topbot、sides 或 none。

[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

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

icon-set

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

source-highlighter

语法高亮度处理可选 coderay、highlight.js、pygments、rouge。
注: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::[] 显示目录。