AsciiDoc記法の書き方（表結合などMarkdownより表現力が高い！）

こんにちは。マニュアル作成・ナレッジ共有ツール「NotePM」ブログ編集局です。

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などで出力した際に改ページを指定する場合には <<< を使います。

リンク

リンクは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」

NotePM

NotePM（ノートピーエム） は、Webで簡単にマニュアル作成できて、強力な検索機能でほしい情報をすぐに見つけられるサービスです。さまざまな業界業種に導入されている人気サービスで、大手IT製品レビューサイトでは、とくに『使いやすいさ・導入しやすさ』を高く評価されています。

NotePMの特徴

マニュアル作成、バージョン管理、社外メンバー共有
強力な検索機能。PDFやExcelの中身も全文検索
社内FAQ・質問箱・社内ポータルとしても活用できる
銀行、大学も導入している高度なセキュリティ。安全に情報共有できる

URL: https://notepm.jp/

NotePMについて詳しく見る＞

AsciiDoc記法の書き方（表結合などMarkdownより表現力が高い！）

段落と改行

preタグ

脚注

リード文

文字装飾

ヘッダー

見出し

ID指定

外部ファイルの読み込み

水平線

改ページ

リスト

番号なしリスト

番号ありリスト

チェックリスト

定義リスト

Q&A

リンク

画像

動画

コード

サイドバー

コメント

テーブル

まとめ