Asciidoctor 语法
文档架构
标题
=文档标题 (书)
在文档标题和一级标题之间的段落为摘要。
== 一级标题 (章)
=== 二级标题 (节)
==== 三级标题
===== 四级标题
====== 五级标题
如果标题不纳入 ToC 则在标题前加入分离 [discrete]
,有该关键字时,标题可以跳级。
=== 二级标题 (节)
[discrete]
===== 四级标题
[discrete]
==== 三级标题
文本样式
引号替换 (Quotes Substitutions)
* *粗体* _斜体_ [line-through]#删除线# [underline]#加底线# [overline]#上标线# #高亮度#
* [yellow]#黄色# [red yellow-background]#红色黄底# (1)
* [big]#加大# 正常 [small]#缩小# ^上标^ ~下标~
* Hello world (正常)
* `Hello world (等宽)` (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 | 键盘宏,中间的分隔可采用 , (逗号) 或 + (加号)。
|
选取菜单
按下按钮 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: ⌘
kbd:[{commandkey} + A] (1)
// Define unicode for Windows Command key.
:commandkey: ❖
kbd:[{commandkey} + A]
:commandkey: ⊞
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)
无序、串行列表
* deep 1
** deep 2
*** deep 3
**** deep 4
***** deep 5
* deep 1
-
deep 1
-
deep 2
-
deep 3
-
deep 4
-
deep 5
-
-
-
-
-
deep 1
[square]
* one
* two
* three
-
one
-
two
-
three
-
one
-
one
-
one
-
one
. Order 1
. Order 2
.. Order 2a
.. Order 2b
. Order 3
-
Order 1
-
Order 2
-
Order 2a
-
Order 2b
-
-
Order 3
. Order 1
[start=3]
. Order 3
. Order 4
-
Order 1
-
Order 3
-
Order 4
[%reversed]
. Order 3
. Order 2
. Order 1
-
Order 3
-
Order 2
-
Order 1
检查清单
- [*] 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
。
-
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
-
-
Fedora
-
Desktop
-
-
Ubuntu
-
Desktop
-
Server
-
-
- BSD
-
-
FreeBSD
-
NetBSD
-
描述列表问题
原代码区块的标注 (Callouts) 之后如果有「描述列表」,如果要分开「描述列表」,增加空行及注解来解决。 事实上,不只区块会有非预期合并的情况,「水平分隔线」也可能合并,需要增加空行及注解来分开。
----
Callouts <1>
----
<1> Callouts
接续的描述列表:: 本段会接续 Callouts,空行并无作用。
//
分开的描述列表:: 如果要分开,增加空行及注解来解决。
描述列表问题结果:
Callouts (1)
1 | Callouts
|
- 分开的描述列表
-
如果要分开,增加空行及注解来解决。
区块 (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").
----
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: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
-
提示 (Admonition)
简单提示
.NOTE, TIP, WARNING, CAUTION, IMPORTANT
Admonition demo
NOTE: Note
TIP: Tip
WARNING: Warning
CAUTION: Caution
IMPORTANT: Important
以下为输出结果:
Admonition demo
Note |
Tip |
Warning |
Caution |
Important |
提示加入标题
.Title
TIP: Tip
以下为输出结果:
Title
Tip
|
范例区块提示,配合 [<LABEL>] 属性加入标签或图标,可采用 ==== 作为范围。
.Title
[TIP]
====
Tip1 +
Tip2
====
以下为输出结果:
Title
Tip1 |
诗句 (Verse)
.诗句 (Verse)
[verse, 作者 (选项), 出处 (选项)]
____
行1 (1)
行2
____
1 | 不需要换行符 (+ )。 |
以下为输出结果:
行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
= 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 之后,并不会有问题。 |
++++
<u>underline me</u> is underlined.
++++
内置区块总结 (Built-in blocks summary)
按 Built-in blocks summary 的定义如下:
区块 |
|
|
目的 |
替换 |
Admonition |
|
|
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 |
None |
Example |
|
|
Designates example content or defines an admonition block |
Normal |
Fenced |
N/A |
|
Source code or keyboard input is displayed as entered |
Verbatim |
Listing |
|
|
Source code or keyboard input is displayed as entered |
Verbatim |
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 |
Varies |
Passthrough |
|
|
Unprocessed content that is sent directly to the output |
None |
Quote |
|
|
A quotation with optional attribution |
Normal |
Sidebar |
|
|
Aside text and content displayed outside the flow of the document |
Normal |
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 |
|
|
Unprocessed content that is sent directly to an interpreter (such as AsciiMath or LaTeX math) |
None |
Table |
N/A |
|
Displays tabular content |
Varies |
Verse |
|
|
A verse with optional attribution |
Normal |
- 区块样式可由下列来决定
-
-
由 边界符 (Delimiter) 来决定。
-
区块名称 (Block Name);区块范围可由开放边界符 (
--
) 来设置。
-
----
Source block
line3
----
[source] (1)
--
Source block
line3
--
[source] (1)
Source block
line3 (2)
1 | 开放区块由区块名称 (Block Name) 来决定样式,如 [source] 、[quote] 、[sidebar] … |
2 | 没有开放边界符 (-- ),不在区块范围之内。 |
替换 (Substitutions)
Group | Special characters | Quotes | Attributes | Replacements | Macros | Post replacements |
---|---|---|---|---|---|---|
Header |
||||||
None |
||||||
Normal |
||||||
Pass |
||||||
Verbatim |
subs 区块替换
subs 区块替换可将 非 Normal 的区块加入 (或取消) 替换,但如果该区块为 Normal,无法以 subs 取消替换。
|
- Special characters 特殊字符替换
-
除了 Passthrough 或 Comment 区块之外,将特殊字符的三个字符
<
>
&
替换成<
>
&
能看到这三个字符<
>
&
表示特殊字符替换已运作,无法让它不运作否则会产生不合法的 HTML。
另外输出成 HTML 代码<strong>粗体</strong>
,这些代码也是需要特殊字符替换。
- Quotes 引号替换
-
参阅:引号替换。
- Attributes 属性替换
-
引用变量 (属性),如变量
{VAR}
。
- 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:[< > &] ----
粗体 < > &
测试 pass (透通)
注:仅限测试 HTML,若输出 docbook 则会出错。
[subs="macros"] ---- pass:[> < &] ----
> < &
区块可采用 subs="verbatim"
输出 HTML 代码。
将区块内的文本先经过「引号替换 (quotes
)」转换成 HTML 代码,再以「特殊字符替换 (verbatim
)」输出为可视字符。
[subs="quotes,verbatim"] (1) ---- *粗体* _斜体_ ----
1 | 替换 (Substitution) 并没有前置加号 (+),如果有加号表示附加,则不会输出 HTML 代码。 |
<strong>粗体</strong> <em>斜体</em>
表格 (Table)
[width=75%, cols="1,1,3"]
|===
|R1C1 |R1C2 |R1C3
|R2C1 |R2C2 |R2C3
|===
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
-
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"] 将第一行设为表头
R1C1 | R1C2 |
---|---|
R2C1 |
R2C2 |
在表头下面加入一行,效果一样,不需要 options="header"。
|===
|R1C1 |R1C2
|R2C1 |R2C2
|===
另外 options="header"
可以简化成 %header
,如下述的 options="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)
-
Title1 | Title2 |
---|---|
R1C1 |
R1C2 |
R2C1 |
R2C2 |
R3C1 |
R3C2 |
R1C1 |
R1C2 |
R2C1 |
R2C2 |
R3C1 |
R3C2 |
栏属性 (cols)
cols
栏属性应用于整栏,栏属性可包含以下:-
样式 (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 |
|
|
|
单元格对齐
[cols="<,^,>"]
|===
靠左 |
水平居中 |
靠右 |
[cols=", .<, .^, .>"] (1)
1 | 点 (. ) 之后为垂直对齐,点 (. ) 之前为水平对齐 (本例没有指定,缺省为靠左)。注:逗号 ( , ) 为分栏 (混在一起看起来有点乱)。 |
第一栏 |
靠上 |
垂直居中 |
靠下 |
[cols=4*]
|===
| 第一栏 +
有两行 (R1)
<.<|左上方 ^.<|居中靠上 >.<|右上方
| 第一栏 +
有两行 (R2)
<.^|居中靠左 ^.^|水平及垂直居中 >.^|居中靠右
| 第一栏 +
有两行 (R3)
<.>|左下方 ^.>|居中靠下 >.>|右下方
|===
第一栏 |
左上方 |
居中靠上 |
右上方 |
第一栏 |
居中靠左 |
水平及垂直居中 |
居中靠右 |
第一栏 |
左下方 |
居中靠下 |
右下方 |
表格宽度
[width=75%] (width) 表格整体宽度占页面 75%
Cell in row 1, column 1 |
R1C2 |
R1C3 |
[%autowidth] (options) 单元格宽度根据内容决定
Cell in row 1, column 1 |
R1C2 |
R1C3 |
[%autowidth.stretch] (options) 表格宽度延伸 (stretch) 为页面,栏宽依据内容决定倍率。
Cell in row 1, column 1 |
R1C2 |
R1C3 |
注: DocBook 转换器无法识别 autowidth
属性。
[cols="1,4"] 按比例调整各栏的宽度,单元格宽度百分比为 20% 80%。
R1C1 |
R1C2 |
如指某栏为固定倍率,其他栏的宽度为自动宽度 (意思是不设置宽度),可指定 ~
作为栏宽度。
在该情况宽度值被假定为百分比值 (即基于100)。
[cols="35h, ~, ~"] 设置第一栏为 35%,其他栏 (C2 C3) 不指定宽度。
Cell in row 1, column 1 |
R1C2 |
R1C3 |
---|
跟 [cols="35h, 32, 33"] 类似 (因为 65 无法整除 2)
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 |
|
几乎支持全部替换的功能。 |
Emphasis (强调) |
|
斜体 (实际上斜体反向) Default |
Header (表头) |
|
应用于栏表头 Default |
Literal (文本) |
|
内容视为在 Literal 区块,不做文本替换。 |
Monospaced (等宽) |
|
等宽字体 Default |
None (缺省)) |
|
文本的处理方式跟普通段落一样 Default |
Strong (粗体) |
|
粗体 (实际上粗体反向) Default |
Verse (诗句) |
|
内容视为在诗句区块 Default |
Default:文本的处理方式跟普通段落一样。
(表格)栏样式范例
以下第二行内容全部为 * U *粗* _斜_ N `L` <<link>> {VAR} pass:[#] \*B*
注: {VAR}
是由 :VAR: 变量测试
来设置成 变量测试
。
a |
e (斜体) |
h (栏表头) |
l (Literal 区块) |
---|---|---|---|
|
* U 粗 斜 N |
* U 粗 斜 N Link-Label 变量测试 # |
* U *粗* _斜_ N `L` <<link>> {VAR} pass:[#] \*B* |
* U
在 a
显示成无序列表,在 HTML 字体比 d
(缺省) 大一些。
|
d (缺省) |
s (粗体) |
v (诗句区块) |
|
* U 粗 斜 N |
* U 粗 斜 N |
* U 粗 斜 N |
测试反斜线转译 \|===
h |
l |
|
d |
---|---|---|---|
|=== |
|=== |
|
|=== |
注:a
无法转译 \|===
无法表现。
单元格跨行、跨栏及重复栏
[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 |
||
|
|
|
表格边框线 (grid, frame)
grid
设置表格单元格的边框,可选值为 rows
、cols
或 none
。
R1C1 |
R1C2 |
R1C3 |
R2C1 |
R2C2 |
R2C3 |
R1C1 |
R1C2 |
R1C3 |
R2C1 |
R2C2 |
R2C3 |
R1C1 |
R1C2 |
R1C3 |
R2C1 |
R2C2 |
R2C3 |
Frame
设置表格边框,可选值为 topbot
、sides
或 none
。
R1C1 |
R1C2 |
R1C3 |
R2C1 |
R2C2 |
R2C3 |
R1C1 |
R1C2 |
R1C3 |
R2C1 |
R2C2 |
R2C3 |
R1C1 |
R1C2 |
R1C3 |
R2C1 |
R2C2 |
R2C3 |
Table format
format= psv | dsv | csv | tsv
[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
!===
|===
R1C1 |
R1C1 |
||||
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'
----
|===
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 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:高。 |
区块图片 (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]
三个图片为个别的区块 (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 并没有实作。 |
将鼠标移至图片上方可得知 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]
--
Left Right
Bottom
文绕图 (Block Image Float)
[.float-group] -- image::images/winlin/sunset.jpg[Sunset,100,float=right] 文绕图说明 ... --
以下的实际的输出并未使用浮动组,可以看到图片超出范围,如果文本内容不足则应该加上浮动组。
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 | 270flip= 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)
|
激活文档目录功能,设置值为 auto、left、right、macro 或 preamble。若 ToC 要在最上方则设为 auto (没有 top 的设置值)。 |
|
ToC 的阶层,该设置值为 1 时,只会产生第 1 阶的 ToC。 |
|
ToC 的标题文本;缺省为 Table of Contents。 |
|
激活标题中前置章节数字 (缺省为未激活),如 |
|
设置章节数字阶层,如 |
(上述两者同时影响 ToC 的项目文本。) |
|
|
章节产生 html 的 ID,缺省为激活。 |
|
激活时,当鼠标悬停在节标题上方时,会显示一个分节符号 ( |
|
不显示 (产生) 文档标题。 |
|
设置 Example block (四个=) 标题文本;缺省为 Example,
可采用 |
|
指定 Example block 开始编号,如为 10,那么下一个则为 |
|
设置表格标题文本;缺省为 Table。 |
|
指定表格标题开始编号。 |
|
设置图片标题文本;缺省为 Figure。 |
|
指定图片标题开始编号。 |
|
设置所有标题文本,如在文档内设置 |
|
页脚中 |
|
是否链接样式表,而不是嵌入样式表。 |
|
是否输出 CSS 文件 (Copy CSS files to output)。 |
|
是否使用 CDN 来解析图标字体。 |
|
设置 asciidoctor 的 CSS 文件。 |
|
激活用户接口宏 (button, menu and kbd)。 |
|
Listing block (原代码区块) 自动换行,该属性已缺省激活,采用 |
|
设置表格的底色,可设置值为 none、even、odd、all。亦可在 table 设置如 |
|
设置值为 |
|
图标字体集可设置值为 |
|
语法高亮度处理可选 |
取消属性可在后面加上 ! ,如 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::[]