AsciiDoc記法の書き方(表結合などMarkdownより表現力が高い!)

2021年07月10日(土) Markdown

Markdownが開発者の間では有名ですが、他にも記法は存在します。今回はその中の一つ、AsciiDocの書き方を紹介します。AsciiDocは歴史の長い記法で、HTMLというよりもDocBookやLaTeXなど専門的な文書を作成するのに作られたという背景があります。

記法はAsciidoctor 文法クイックリファレンス(日本語訳)に記載されている内容に沿って紹介します。

段落と改行

段落は改行を2回続けるだけです。

強制的な改行は + を行末に付けます。

+

preタグ

行頭をスペースで開始すると、その部分全体がpreタグで囲まれます。

pre

脚注

行頭に指定された文字を書くことで、注意書きのような部分を表現できます。

NOTE:
TIP: Tips
IMPORTANT:
WARNING:
CAUTION:

なお、Asciidoctor 文法クイックリファレンス(日本語訳)ではアイコンが表示されていますが、これはスタイルシートや画像素材などに依存します。AsciiDoc Viewer and Editorでは以下のようにテキストが表示されました。

リード文

[.lead] を付けると、その下の行がリード文として表示されます。その後からの文章は通常の大きさになります。

[.lead]

文字装飾

文字装飾は次のように用意されています。スペースを間に挟む場合は語句として認識されます。 *_ 、それに ““ は組み合わせて利用できます。

AsciiDoc 内容
*語句* または **文字** strongタグで囲まれます
_語句_ または __文字__ emタグで囲まれます
`語句` または `文字` codeタグで囲まれます
#語句# markタグで囲まれます
^文字^ supタグで囲まれます(上付き文字)
"`文字`" “文字”
'`文字`' ‘文字’
~文字~ subタグで囲まれます(下付き文字)
[.クラス名]#語句# <span class="クラス名">語句</span> という形式になります

ヘッダー

ドキュメントのヘッダーは次のように定義されています。著者名、リビジョンは必須ではありませんが、リビジョンを付ける場合には著者名は必須になります。

=
<>

見出し

見出しは = の個数で定義します。 = が1つの場合はヘッダーで利用していますので、 == がセクションレベル1となります。

== 1
====== 5

ID指定

見出しの上に [[名前]] でIDを指定できます。

[[section1]]
## 1

外部ファイルの読み込み

外部にある別なAsciiDocを読み込めます。末尾にある [] は読み込む行数やタグを指定して、ファイルの一部だけを読み込めます。ローカルファイルだけでなく、URIを指定して外部コンテンツも読み込めます。

include::basics.adoc[]

水平線

水平線は ` を3つ並べます。

```

改ページ

LaTeXなどで出力した際に改ページを指定する場合には <<< を使います。

リスト

番号なしリスト

番号なしリストは * を使います。 * の個数で深さが変わります。

* 1
** 1-1
** 1-2
** 2
** 2-1
** 2-2

番号ありリスト

番号ありリストには . を使います。

. 1
.. 1-2
. 2
.. 2-1
.. 2-2

チェックリスト

チェックリストは - [ ] を使います。 [*] または [x] とすることでチェック済みになります。

- [ ] 1
- [*]
- [x]

定義リスト

定義リストは :: を使います。1行または複数行の2パターンが用意されています。

::
::

Q&A

Q&Aは定義リストに似ていますが、各質問に数字が振られます。

[qanda]
A::
A
B:: B

リンク

リンクはURLについて自動リンクするのと、 URL[タイトル] という形式でも表現できます。

https://notepm.jp/[NotePM - (wiki)]

スペースや特殊文字を含んだ場合には、頭に link: を付けます。また、ローカルファイルなどを相対パスで指定する場合にも使えます。

link:++http://example.org/?q=[a b]++[URL]

画像

画像の基本記法は image::URL[title or alt] です。画像はインラインでも使えます。

image::http://asciidoctor.org/images/octocat.jpg[GitHub mascot]

しかし、キャプションやリンク、表示サイズなどを指定することもできます。

image::()[(alt), (width), (height)]

動画

動画は video:: を使います。幅や開始時間など、オプションも指定可能です。

video::video_file.mp4[width=640, start=140, options=autoplay]

YouTubeとVimeoは専用記法があります。

YouTube
video::TabMg56daZ0[youtube]
Vimeo
video::22439234[vimeo]

コード

コードは、インラインの場合は ` で囲みます。複数行の場合は .... で囲みます。

....
puts "Hello, world!"
....

さらに ---- ではタイトル付きになります。

hello.rb
----
puts "Hello, world!"
----

シンタックスハイライトを付ける場合には [[source,(言語)]] を使います。

[source,ruby]
hello.rb
----
puts "Hello, world!"
----

ソースコード中に説明を追加することもできます。

[source,ruby]
----
require 'sinatra' // <1>
get '/hi' do // <2>
"Hello World!" // <3>
end
----
<1> Library import
<2> URL mapping
<3> HTTP response body

ソースコードファイルも外部ファイル読み込みできます。

include::{sourcedir}/StringUtils.java[lines=5..7]

サイドバー

**** で囲まれた部分はサイドバーというブロックになります。divタグにsidebarblockクラスを付けて表示されます。

.
****
****

コメント

// ではじまると1行コメントになります。複数行コメントは //// で囲みます。

////
////

テーブル

テーブルは列名を |=== で定義します。その後は行ごとに縦に並べて書いていきます。

.
|===
|1 |2 |3
|11
|12
|13
|21
|22
|23
|===

CSVとして定義もできます。

[format="csv", options="header"]
|===
,,
Baauer,Harlem Shake,Hip Hop
The Lumineers,Ho Hey,Folk Rock
|===

さらに外部ファイルとしてCSV読み込みも可能です。

|===
include::customers.csv[]
|===

セル結合も定義できます。

[cols="e,m,^,>s", width="25%"]
|===
|1 >s|2 |3 |4
^|5 2.2+^.^|6 .3+<.>m|7
^|8
|9 2+>|10
|===

まとめ

AsciiDocは当初からHTMLだけを対象とはしていないので、記法が特殊になっています。その代わり実現できる機能も数多くあります。一旦覚えてしまえばHTMLはもちろん、書籍などを執筆する際にも役立つです。外部ファイル取り込みなど、メンテナンス性や再利用性も考慮されているのが利点と言えそうです。

おすすめの情報共有ツール

NotePM(ノートピーエム) は、ナレッジ共有に特化した社内版ウィキペディアです。検索に強く、情報を整理しやすいのが特徴です。3,000社以上に導入され、とくに『使いやすいさ・導入しやすさ』の点で高く評価されています。「ほしい情報を探すのが大変」「社内のナレッジ共有が上手くいっていない」とお悩みの方は、NotePMの無料トライアル をお試しください。

NotePMの資料請求はこちら