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