MarkdownユーザーがAsciidocを試してみた｜使いやすさ・欠点・移行の所感

この記事でわかること

  • MarkdownとAsciidocの主な違い
  • Asciidocを使って感じたメリット・デメリット
  • 実際の使用例と学習コストの印象
  • Markdownからの移行はおすすめできるのか？

Markdownの限界

Markdownで記事をずっと書いてきたが、そろそろ限界を感じていた。ルビが振れない。表が書きにくい。数式が表示できない。…そんな中で見つけたのが「Asciidoc」だった。

はじめは軽い気持ちだった。「ちょっと試してみるか」程度で始めたものの、いざ書き始めてみると、予想以上にしっくりきた。「これ、最初からこっちで書いていればよかったのでは？」とすら感じるほどだった。Asciidocの思想は、“なんとなく書ける”Markdownとは違い、“最初から構造的に書く”という方向に向いている。

使い慣れているMarkdownと比べて何がどう違い、どこに惹かれたのかを、ここに記録しておく。

MarkdownからAsciidocに興味を持った理由

Markdownは軽量で便利だが、「構造化された長文」を扱うには力不足だと感じるようになった。特に以下の点で不満があった：

  • 表記の自由度が低い（脚注・ルビ・図番号など）
  • 表が複雑になると地獄（パイプ区切りの視認性）
  • 数式を書こうとするとKaTeXやMathJax頼りで面倒
  • ファイル構造やテンプレートとの連携に限界がある

そんな中で「Asciidocは本格的な技術ドキュメントのために作られた」「見出し構造や属性が自然」「PDFやHTML、EPUBにも出力可能」といった紹介を見て、試してみたくなった。

各記法の詳細等は、Qiitaなどで調べればいくらでも出てくるので割愛するが、以下に実際に使ってみて感じたことを記す。

Asciidocを使って感じた4つのメリット

1. 見出しやリストのネストが、MediaWiki記法に近い

Asciidocでの記法

== 見出し
* 箇条書き
** ネスト1
*** ネスト2

Markdownのように見出しに#を使うか、asciidocのように=を使うかは、単なるルールの違いのため、どちらが良いとは言えないが、個人的にWikipediaなどのMediaWiki記法には馴染みがあるため、asciidocのように見出しに=を使うというのは、書く上で慣れていて嬉しい。逆に、MediaWiki記法に慣れた状態から、初めてMarkdownを触ったときは、#を使うのに戸惑ったくらいだ。

箇条書き及びネストについては、asciidocの仕様はMediaWiki記法そのものである。個人的にMarkdownのネストの仕様は好きでは無かった。Markdownでは、箇条書きをネストする場合、以下のように空白文字でインデントする必要がある。空白文字でのコントロールは視認性に劣ると感じている。

Markdownでの記法

* 箇条書き
  * ネスト1
    * ネスト2

2. テーブルがCSV形式で書ける

Asciidocでの記法

[format="csv", opstions="header"]
|======
a, b, c
1, 2, 3
4, 5, 6
|======

csv形式で書けるのが地味に嬉しい。行数・列数が一目瞭然である。以下のようなMarkdownでの記法も悪い訳では無いが、どのパイプ文字「|」の内側にいるかを意識しないと、プログラミング言語における括弧閉じ忘れのように、意図しない挙動になりがちだ。

Markdownでの記法

|a  |b  |c  |
|---|---|---|
|1  |2  |3  |
|4  |5  |6  |

3. ルビが振れる

Asciidocでの記法

{ruby}漢字[かんじ]

Markdownでは不可能に近かったルビ表現も、Asciidocなら標準対応（もしくは拡張対応）。

4. 複雑なドキュメント構造が扱いやすい

  • include:: でファイルを分割できる
  • 属性（変数）で値を使い回せる
  • セクション単位でテンプレート化できる

ドキュメント全体を構造化・再利用する思想があることが好印象だった。

課題と落とし穴

もちろん完璧ではない。主な難点：

  • 普及していない（対応エディタやWebサービスが少ない）
  • 学習コストがMarkdownよりは高い（記法が多く、文法エラーもある）
  • HugoやZolaなど一部SSGではMarkdown優遇
  • PDF化には別途asciidoctor-pdfやSVG埋め込みが必要
  • 引用のデフォルト見た目が微妙（カスタム必須）

それでも、Markdownに戻れない感覚

Markdownが“誰でも書ける”軽量言語だとすれば、Asciidocは“ドキュメントのための道具”。

ルビ、数式、属性、構造、再利用──Markdownでは我慢していたものが、Asciidocでは最初からちゃんと設計されている。これはもう、「Markdownの上位互換」と言って差し支えない。

今後の方針

  • Hugo × Asciidoc のサイト構成を実験してみたい
  • Asciidoctor拡張でPDFやEPUB出力も試したい
  • Markdownでは難しかった記事テンプレートをAsciidocで再設計したい

締めの感想

「なぜこれが広まってないんだ」と思うレベルで良い。Asciidocは、“本当に書く人”のためのマークアップだと感じた。