最初にAsciidoctorを入れたとき「Rubyのgemなのか」と少し身構えましたが、実際にはコマンド1つで終わりました。むしろVS Code側のプレビュー設定の方に時間がかかったので、その手順を細かく残しておきます。

導入の全体像

AsciidoctorとVS Code拡張機能を含むツール導入の全体フロー図

図1: Ruby gemでAsciidoctorを導入し、CLIで変換・VS Codeでプレビューする全体フロー

AsciiDocの執筆環境は、大きく分けて次の2つの要素で構成されます。

  • Asciidoctor（必須） — .adocファイルをHTMLやPDFに変換するコマンドラインツール。Ruby gemとして配布されている。
  • VS Code + AsciiDoc拡張機能（任意・推奨） — 執筆中にシンタックスハイライトとリアルタイムプレビューを得るためのエディタ環境。

Asciidoctorだけでも執筆・変換は可能ですが、長文を書く場合はプレビューがないと構文ミスに気づきにくいため、本シリーズではVS Code拡張機能の併用を前提にします。

Asciidoctorのインストール（Ruby gem）

Asciidoctorは Ruby の gem として配布されています。事前にRubyがインストールされていることを確認したうえで、以下を実行します。

Shell — インストール 
# Rubyのバージョン確認（2.7以上を推奨）
ruby -v

# Asciidoctor本体のインストール
gem install asciidoctor

# インストール確認
asciidoctor -v

# まとめてインストールする場合（PDF出力も使う想定）
gem install asciidoctor asciidoctor-pdf
asciidoctor -v の出力例
Asciidoctor 2.0.20 [https://asciidoctor.org]
Runtime Environment (ruby 3.2.2 [x86_64-linux])

⚠️ Rubyが入っていない場合

WindowsではRubyInstallerを使うのが手軽です。macOSはHomebrewでbrew install ruby、LinuxはOS標準パッケージマネージャ（apt/yum等）で導入できます。会社のプロキシ環境下ではgem install時に追加のプロキシ設定が必要になる場合があります。

インストール確認

簡単なサンプルファイルを作成し、実際に変換できるか確認します。

Shell — 動作確認 
echo "= サンプル文書

Hello, AsciiDoc!" > sample.adoc

asciidoctor sample.adoc
# → sample.html が生成される

✅ ここまでで最低限の執筆・変換は可能

asciidoctorコマンドだけで.adoc → .htmlの変換は完結します。次からは、より快適に書くためのエディタ環境を整えます。

VS Code拡張機能の導入

VS Codeの拡張機能タブから 「AsciiDoc」（asciidoctor-vscode）を検索してインストールします。導入後は次の機能が使えるようになります。

機能説明
シンタックスハイライト見出し・強調・属性などが色分けされ、記法ミスに気づきやすくなる
リアルタイムプレビューCtrl+Shift+V（macOSはCmd+Shift+V）でHTMLレンダリング結果を横に表示
目次(TOC)のプレビュー反映属性:toc:を付けた場合、プレビュー上でも目次が確認できる
PDF出力ショートカットコマンドパレットから直接PDFエクスポートを呼び出せる（内部でAsciidoctorを利用）

💡 保存時の自動プレビュー更新

ファイル保存のたびにプレビューが自動更新されるため、Markdownエディタと同じ感覚で執筆できます。長い文書では、プレビューの自動スクロール同期（Sync Scrolling）機能も有効にしておくと確認が楽になります。

HTML / PDFへの変換コマンド

実際の執筆・公開フローで使う変換コマンドの主なオプションをまとめます。

Shell — 変換コマンド一覧 
# 基本のHTML変換（同名の.htmlが出力される）
asciidoctor article.adoc

# 出力先ディレクトリを指定
asciidoctor -D dist/ article.adoc

# 出力ファイル名を指定
asciidoctor -o output.html article.adoc

# 目次を自動生成（左サイドバー表示）
asciidoctor -a toc=left article.adoc

# シンタックスハイライトを有効化（rougeを使用する場合）
asciidoctor -a source-highlighter=rouge article.adoc

# 複数ファイルをまとめて変換
asciidoctor *.adoc
オプション意味
-D, --destination-dir出力先ディレクトリの指定
-o, --out-file出力ファイル名の指定
-a, --attribute属性をコマンドラインから設定（:toc:等をファイルに書かず指定できる）
-b, --backend出力形式の指定（html5／docbook等）

asciidoctor-pdfの追加インストール

標準のAsciidoctorはHTML/DocBook向けの変換が中心で、高品質なPDF出力には専用gemの asciidoctor-pdf を使います。日本語フォントを使う場合は、テーマファイルでフォント指定が必要になる点に注意してください。

Shell — PDF変換 
# asciidoctor-pdfのインストール
gem install asciidoctor-pdf

# PDFへの変換
asciidoctor-pdf article.adoc
# → article.pdf が生成される

⚠️ 日本語PDFで文字化けする場合

デフォルトのPDFテーマは日本語フォントを内蔵していません。.ymlテーマファイルでNotoフォント等を指定し、asciidoctor-pdf -a pdf-theme=my-theme.ymlのように読み込む必要があります。テーマ設定の詳細はシリーズの発展編として別途扱います。

執筆ワークフローのまとめ

ここまでの手順で、次のような執筆フローが確立できます。

  1. VS Codeで.adocファイルを編集（拡張機能でシンタックスハイライトとプレビューを確認）
  2. 区切りの良いタイミングでasciidoctorコマンドを実行しHTMLを生成
  3. 配布・提出が必要な場合はasciidoctor-pdfでPDFを生成

✅ 次の章では…

PART 03 では、見出しや段落といった基本構文に加えて、AsciiDocの中核機能である属性（Attribute）と相互参照（xref）による「要素の定義」の書き方を解説します。

→ PART 03 — 基本構文と要素の定義へ