PART 01 — AsciiDocとは
Markdownとの違いと採用メリット

仕様書をMarkdownで書いていて、章をまたいだ相互参照や複数の出力形式（HTML/PDF）が欲しくなるたびに外部ツールを組み合わせていました。そのたびに「これ標準機能で持っているマークアップ言語ないのか」と思って調べ、たどり着いたのがAsciiDocでした。導入の経緯を整理した回です。

AsciiDocとは

AsciiDocは、プレーンテキストに軽量な記号を使って見出し・強調・リストなどの構造を表現する軽量マークアップ言語です。2002年に仕様が公開され、その後Asciidoctorという高速な実装が登場したことで、技術文書・書籍執筆の分野を中心に採用が広がりました。

見た目の記法はMarkdownと似ている部分も多く、*太字*や_斜体_のような装飾はほぼ共通の感覚で書けます。一方で、AsciiDocは仕様そのものが「技術文書を書くための言語」として設計されており、章番号・目次・相互参照・脚注・属性（変数）といった、長文ドキュメントで必要になる機能を拡張なしで持っている点が特徴です。

なぜAsciiDocを選ぶのか

Markdownはシンプルさゆえに広く普及しましたが、そのシンプルさは「仕様がゆるい」ことの裏返しでもあります。表・脚注・相互参照などはCommonMark本体の仕様に含まれず、サービスや変換ツールごとに拡張記法がバラバラになりがちです。

この特性から、README や短いメモには依然としてMarkdownが手軽ですが、章立てのある仕様書・マニュアル・書籍のように「長く・構造的な文書」を書く場面ではAsciiDocに分があります。

Markdownとの比較（○×表）

実務でよく問題になる観点で、標準のMarkdown（CommonMark相当）とAsciiDocを比較しました。○＝標準仕様で対応、△＝拡張機能や実装依存で対応可能、×＝標準では非対応という基準です。

観点	Markdown（標準）	AsciiDoc
表（テーブル）	△ 拡張仕様（GFM等）依存	○ 標準搭載
相互参照・アンカー	× 標準では非対応	○ 標準搭載（xref）
属性（変数）	× 標準では非対応	○ 標準搭載
PDF直接出力	× 別ツール必須	△ asciidoctor-pdf追加で対応
ファイル分割（include）	× 標準では非対応	○ 標準搭載
学習コスト	○ 低い	△ Markdownよりやや高い
Webサービスでの普及度	○ 非常に高い（GitHub等）	△ 限定的（GitHub等の一部で表示対応）

変換エコシステム — Asciidoctor

AsciiDocの仕様を実装した変換エンジンにはいくつか歴史的な実装がありますが、現在の事実上の標準はAsciidoctor（Rubyで実装、Node.js版のAsciidoctor.jsも存在）です。次回のPART 02では、このAsciidoctorのインストールから、VS Code拡張機能によるプレビュー環境構築までを実際に手を動かしながら解説します。

どんな人におすすめか

• 複数章にわたる技術仕様書・運用マニュアルをテキストベースで管理したいエンジニア
• 同じ原稿からHTMLとPDFの両方を安定して出力したい人
• バージョン番号や環境名などを本文中に散りばめず、属性として一元管理したい人
• Markdownの表現力の限界（相互参照・脚注・章番号）に不便を感じたことがある人

本シリーズの構成

全5回で、ツール導入から実践的な記法、応用構文までを一通り解説します。

PART	内容
01（本記事）	Markdownとの比較と、AsciiDocを選ぶ理由
02	Asciidoctorのインストールと変換環境構築（VS Code拡張含む）
03	見出し・段落などの基本構文と、属性・相互参照による要素の定義
04	リスト・表・コードブロック・画像・admonitionの表記方法
05	includeによるファイル分割・目次・条件付きコンテンツとまとめ