【完全解説】AsciiDocのインストール方法とMarkdown（マークダウン）徹底比較

Webライティングやドキュメント作成で広く使われている「Markdown（マークダウン）」。しかし、技術書や仕様書、大規模なマニュアル作成において、その上位互換とも言える「AsciiDoc（アスキードック）」が今、強い注目を集めています。

「Markdownと何が違うの？」「どうやって使い始めるの？」という疑問を持つ方に向けて、本記事ではAsciiDocの概要、主要OSでのインストール手順、そしてMarkdownとの決定的な違いを徹底比較します！

1. AsciiDoc（アスキードック）とは？
2. AsciiDocのインストール方法
3. 【比較表】AsciiDoc vs Markdown
4. MarkdownにはないAsciiDocのメリット・強み
5. まとめ：どちらを選ぶべき？

1. AsciiDoc（アスキードック）とは？

AsciiDocは、プレーンテキストで構造化された文書を書くための軽量マークアップ言語です。Markdownよりも後発であり、Markdownの「シンプルで書きやすい」というメリットを活かしつつ、標準機能だけで高度なドキュメント（技術書、仕様書、論文など）を作成できるように設計されています。

2. AsciiDocのインストール方法

AsciiDocをコンパイル（HTMLやPDFへ変換）するには、現在最も活発に開発されている「Asciidoctor（アスキードクター）」をインストールするのが一般的です。各OSでの手順は以下の通りです。

前提条件

AsciidoctorはRuby環境で動作するため、事前にRuby（バージョン2.7以上推奨）がインストールされている必要があります。

Windowsへのインストール手順

Windowsでは、パッケージマネージャー「Chocolatey」を使うか、Ruby環境を入れてからインストールします。

コマンドプロンプトまたはPowerShellを管理者権限で起動します。
以下のコマンドを実行してインストールします。
gem install asciidoctor
PDF出力も行いたい場合は、以下も追加でインストールします。
gem install asciidoctor-pdf

macOSへのインストール手順

macOSでは、Homebrewを使用するのが最も簡単です。

ターミナルを開きます。
以下のコマンドを実行します（Homebrewが自動で依存関係を処理します）。
brew install asciidoctor

Linux（Ubuntu/Debian）へのインストール手順

ターミナルを開き、パッケージリストを更新します。
sudo apt update
以下のコマンドでインストールします。
sudo apt install asciidoctor

【おすすめ】VS Code拡張機能で「インストールなし」で始める

とりあえず試してみたい方は、コードエディタ「Visual Studio Code (VS Code)」の拡張機能を使うのが最も手軽です。

VS Codeの拡張機能マーケットプレイスで「AsciiDoc」（作者: Asciidoctor）を検索してインストール。
拡張機能を入れれば、特別な環境構築なしでリアルタイムプレビューを見ながら執筆が可能です。

3. 【比較表】AsciiDoc vs Markdown

どちらを採用すべきか迷っている方のために、両者の違いを表にまとめました。

比較項目	AsciiDoc (アスキードック)	Markdown (マークダウン)
主な用途	技術書、仕様書、大規模マニュアル、論文	ブログ、メモ、GitHubのREADME、チャットツール
習得難易度	やや高め（機能が多いため）	非常に低い（シンプル）
表（テーブル）の表現	標準でセルの結合、配置調整、高度な表現が可能	基本的な表のみ（方言/拡張機能に依存）
ファイル分割・結合	標準機能（`include`）で可能	標準では不可能（外部ツールが必要）
目次の自動生成	行頭に設定を入れるだけで自動生成	ツールや環境によって対応が異なる
方言（仕様の乱立）	少ない（標準仕様が厳格）	多い（CommonMark, GFMなど乱立）
エコシステム・認知度	エンジニアや執筆者に人気	IT業界全体、一般ビジネスでも広く普及

4. MarkdownにはないAsciiDocのメリット・強み

なぜ大規模なドキュメント作成でAsciiDocが選ばれるのか、具体的な強みを3つ解説します。

① 外部ファイルの読み込み（Include機能）

仕様書や本を書く際、1つのファイルが数万行になると管理が困難になります。AsciiDocなら、以下のように別のファイルを簡単に埋め込めます。

include::chapters/introduction.adoc[]

これにより、章ごとにファイルを分けて複数人で共同編集することが容易になります。

② 標準での強力なテーブル（表）機能

Markdownの表は単純なものしか作れませんが、AsciiDocなら「セルの結合」「右寄せ・中央寄せ」「セル内での箇条書き」などが標準のシンタックスだけで柔軟に表現できます。

【参考：AsciiDocでの複雑な表のコード例】

[cols="1,2,2", options="header"]
|===
| 言語 | 特徴 | 記述サンプル

| Markdown
| シンプル。セルの結合は基本的に不可。
| `\| セル1 \| セル2 \|`

.2+| AsciiDoc
| 縦のセル結合（このセルは2行分結合しています）
| 縦結合のサンプル

a| セル内に箇条書きを含めることも可能：
* 項目A
* 項目B
| 横の結合や右寄せなども自由自在
|===

(※ .2+\| という記述だけで、簡単に縦2行分のセルを結合できます)

③ 構築済みのクロスリファレンス（相互参照）

「詳細は〇章を参照」といった文書内のリンク（アンカー）を、高度な設定なしで安全に紐付けることができます。ドキュメントの規模が大きくなってもリンク切れを起こしにくい設計になっています。

【参考：AsciiDocでのクロスリファレンスのコード例】

// リンク先にID（アンカー）を設定する
[[target-section]]
== 5. 詳細な設定方法について

〜（中略）〜

// 別の場所から上記のセクションへリンクを貼る
インストールが完了したら、<<target-section>> を参照して初期設定を行ってください。

(※ <<ID>> と書くだけで、自動的にその見出しのタイトル（例：「5. 詳細な設定方法について」）をリンクテキストとして出力してくれます)

5. まとめ：どちらを選ぶべき？

Markdownを選ぶべき人：
- 日々のメモ書き、ブログ記事の下書き
- シンプルなドキュメントを素早く作成したい
- チーム全員がすでにMarkdownに慣れている
AsciiDocを選ぶべき人：
- 100ページを超えるような技術書や製品マニュアルを作りたい
- 複数のファイルをガッチャンコして1つのPDFやHTMLを出力したい
- 複雑な表や図をドキュメント内に多用する