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::[]