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::[] 顯示目錄。