AsciiDocの良いところ

はじめに

軽量マークアップ言語で最もメジャーなMarkdownと比較しつつ、AsciiDocの良いところをここでは書いています。

既にAsciiDocに関する良記事は以前からありますので、こちらを参照することをお勧めします。

• AsciiDoc入門

※余談ですが、4年前くらいにこちらの記事で基本的なことを知ることが出来ました。
私は当時Markdownを知らなくて、AsciiDocを先に覚えました。

AsciiDocは軽量マークアップ言語の１つ

AsciiDocとは、軽量マークアップ言語のひとつです。
簡単な文法を覚えるだけで書くことが出来、そのままでも単なるテキストとしても読めます（可読性が高い）が、HTMLやPDFに変換することで表現力豊かな文章を作成することが出来ます。
※変換には、Asciidoctorやpandocなどを使用します。

• 記述／出力イメージ（Wikipediaより）

テーブル（表）を書くのが簡単

まず、Markdownで表を書くのはすこし難しいです。
列を追加するときなど、繊細な作業になりメンテがしづらいです。

• Markdownの表の書き方

| Column 1 | Column 2 | Column 3 |
| -------- | -------- | -------- |
| Text     | Text     | Text     |

• 出力

一方でAsciiDocも似たような書き方が出来るのですが、さらにcsv形式で書くということが出来ます。

• AsciiDoc、csv形式での表の書き方

[options="header"]
,=====
Column 1,Column 2, Column 3
Text,Text,Text
,=====

先頭末尾の|が無いだけでもすっきりしていて書きやすいです。
それに、この表部分だけを抜き出して他所に提出するシーンがあったとしてもcsv形式なので恥ずかしくありません。

また、外部のcsvファイルをそのまま取り込んで出力することもできます（後述）

定数を使うことが出来る(attribute)

Markdownではできない（と思いますが）定数定義ができます。
これをattribute(属性)というようですが、以下のように書きます。

• 記述例

// attributeを定義
:burebureName: ブレブレサービス

// attributeを使うとき
{burebureName}は、こんなサービスです。

• 出力結果

これは、ドキュメント量が増えてくると効いてきます。
上記のように、言葉がブレやすかったり今後変わる可能性のあるような文言に使えます。

外部ファイルの取り込みが出来る

これもMarkdownではできない（と思いますが）外部ファイルの取り込みができます。

例えば、APIリファレンスによくあるレスポンス出力例を別ファイルにするというような使い方が出来ます。
レスポンスの出力内容を変えたときに、テストで出力したjsonファイルをそのまま使おうと思えば使えます。

• 記述例

* レスポンス

[source,json]
----
include::./sample.json.[]
----

• sample.json

[
    {
      "created_at": "2000-01-01T00:00:00+00:00",
      "id": "c686397e4a0f4f11683d",
      "updated_at": "2000-01-01T00:00:00+00:00",
      "page_views_count": 100
    }
]

• 出力結果
  

ちなみに末尾の.[]は、.[lines=1..3]とすると1~3行だけ出力します。

前述のcsvテーブルもこんな感じに外部ファイル化できます。

[options="header"]
,=====
include::./sample.csv.[]
,=====

おわりに

Markdownに比べると覚えることは若干多いと経験上感じていますので、

• 軽いメモを取る場合には、Markdown
• ドキュメント総量が多い、メンテナンスの頻度が高い場合には、AsciiDoc

と使い分けをすることを個人的にはお勧めします。

参考

• AsciiDoc-homepage
• AsciiDoc cheatsheet
• AsciiDoc-Wikipedia