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
開放區塊,除了 passthroughtable 區塊之外,配合 [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 特殊字符替換

除了 PassthroughComment 區塊之外,將特殊字符的三個字元 < > & 替換成 &lt; &gt; &amp; 能看到這三個字元 < > & 表示特殊字符替換已運作,無法讓它不運作否則會產生不合法的 HTML。
另外輸出成 HTML 代碼 <strong>粗體</strong>,這些代碼也是需要特殊字符替換。

Quotes 引號替換

參閱:引號替換

Attributes 屬性替換

引用變數 (屬性),如變數 {VAR}

Macros 巨集替換

包含 Pass 巨集使用者介面巨集連接防止替換及圖片。

Replacements 符號替換

參閱:符號替換

Post replacements 換行替換

替換 換行字符 +。Block 設定為 subs="post_replacements"

Callouts 標註替換

除了 passthroughtable 區塊之外,預設會處理 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 可為 headerfooterbreakableunbreakableautowidthautowidth.stretchrotate

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

  • cols

  • width

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

* Ua 顯示成無序列表,在 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|R1C1h|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 設定表格單元格的邊框,可選值為 rowscolsnone

[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 設定表格邊框,可選值為 topbotsidesnone

[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

設定值為 fontimagesvg,如在文件內設置 :icons: font 啟用圖示字體 (Font Awesome) 的功能。

icon-set

圖示字體集可設定值為 fafas …​,參閱 Font and Image Icons (僅支援 asciidoctor-pdf)

source-highlighter

語法高亮度處理可選 coderayhighlight.jspygmentsrouge
註: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::[] 顯示目錄。