Asciidoc変換の方法｜AsciidoctorでできるHTML・PDF出力

1. AsciiDocの特徴・メリット

AsciiDocの特徴やメリットをご紹介します。

1-1. 読みやすく、表現力が高い

AsciiDocは軽量マークアップ言語の一つなので、以下のポイントは前提的な特徴です。

・プレーンテキストで記述できる
・見出し、番号付きリスト、箇条書きリストなど、情報の性質をマークアップによって明示できる
・人にとってもコンピュータにとっても読みやすい

これらに加え、AsciiDocに特有な点として以下の2点があります。

構文が標準化されている

AsciiDocはEclipse Foundationによって構文の標準化が行われています。
記法の拡張方法が公式の言語仕様にて定められているため、Markdownで時折みられる「方言」の違いに悩まされることはほぼありません。

高度な表現方法に対応

AsciiDocは高度な表現方法に対応しています。例えば、図表にタイトルを追加したり、表のセルを結合したりできます。
以下の画像はAsciiDoc文書とHTML出力結果（後述のAsciidoctorによる出力結果）です。

表：AsciiDoc

表：HTML

脚注、コードブロック、引用ブロックのほか、「警告」「注意」のようなラベル付きのブロック要素も用意されています。特に「警告」「注意」などのスタイルは、マニュアル類の文書では必須ともいえる表現です。

注意スタイル：AsciiDoc

注意スタイル：HTML

1-2. バージョン管理システムとの相性が良い

AsciiDocはプレーンテキストなので、Gitをはじめとするバージョン管理システムとの相性が抜群です。特に、GitHubなどのコラボレーションプラットフォームを活用し、チームで共有管理することで真価を発揮します。
開発の現場では、普段行っているコードレビュー・プルリクエストなどのプロセスをドキュメント作成に適用することで、ドキュメントをより迅速に、正確にメンテナンスできるメリットがあります。
なお、GitHubではAsciiDocのレンダリングを標準でサポートしているため、リポジトリ内のAsciiDoc文書を、整形された外観で閲覧できます。

1-3. 別ファイルを文書内に組み込める

他のAsciiDocファイルやテキストファイルなど、別ファイルのコンテンツをAsciiDoc文書に組み込むことができます。includeディレクティブという機能です。
公式ドキュメント（Includes | Asciidoctor Docs）によれば、大規模なドキュメントをサブドキュメントに分割して束ねる使い方や、別ファイルの一部を引用するような使い方が想定されているようです。
マニュアル制作では、例えば「マニュアルの分冊ごとに出力する章を変更したい」「複数のマニュアルで使用する共通記載を1か所で管理したい」などといった制作上の要望が発生することがあります。includeを上手に活用すれば、これらの要望を大きな手間なく満たすことができます。

1-4. 多様な出力形式

オープンソースのAsciiDocプロセッサ「Asciidoctor」を用いて、AsciiDocをさまざまな形式に変換できます。
Asciidoctorによる変換については、次の項目で詳しく説明します。

2. AsciidoctorでAsciiDocを他の媒体に変換

2-1. Asciidoctorとは

Asciidoctorは、現在最も広く使われているAsciiDocの実装（処理エンジン）です。
現在のAsciiDocは、Asciidoctorでの実装を前提として整備されているので、AsciiDoc文書の運用を始めるなら、多くの場合Asciidoctorも併せて導入することになると思います。

2-2. Asciidoctorで変換できる形式

Asciidoctorがインストールされた環境では、AsciiDoc文書をHTML、PDF、EPUB、DocBookなどの形式に変換できます。つまり、AsciiDocをソースとして、Webページ、電子書籍、印刷用文書などを作成できます。
マニュアル制作においては、WebマニュアルとPDFマニュアルを併用したいケースが少なくないのですが、Asciidoctorで簡単にワンソース・マルチユースが叶うのは大きなメリットです。

Word/Excelを活用したマニュアル作成のデメリットとは？マニュアル作成の最新動向を紹介

2-3. コマンド実行ですぐにHTML変換

AsciiDoc文書を用意し、Asciidoctorのインストールが済んだら、すぐに文書を変換することができます。
例えば、HTMLに変換するとしましょう。文書を指定してコマンドを1つ実行するだけで、HTMLファイルが出来上がります。AsciidoctorではHTML用にデフォルトのスタイルシートが整備されており、そのまま実用できるものなので、これで作成完了としてもよいかもしれません。
外観をアレンジしたい場合は、スタイルシートを別途作成してAsciiDoc文書内でパスを指定します。この状態で変換コマンドを実行すれば、スタイルシートが適用されたHTMLファイルが出来上がります。
外観や機能を高度に・複雑にカスタムしていくこともできますが、「まず変換して出力結果を得る」までの手順はとても簡単です。

3. AsciiDoc活用にまつわるよくある課題とその解決策

AsciiDoc文書を企業で運用するときの課題とその解決策を解説します。

3-1.記法を覚える必要がある

AsciiDocの記法を習得するには、少し時間的コストがかかります。
Web上に記法のリファレンスがあるので、それらを参照して覚えていくのが基本ですが、まずはよく使う記法だけを覚えるのも一つの手です。
定型的なドキュメントを作成する場合は、あらかじめテンプレートとなるAsciiDocファイルを作成して各要素を配置しておき、コピー＆ペーストをしながら自然に記法を使えるようにすると便利です。

公式クイックリファレンス：
AsciiDoc Syntax Quick Reference | Asciidoctor Docs

3-2. ITリテラシーが必要

AsciiDoc文書の閲覧や編集、他形式での出力を行うには、ある程度準備が必要になります。

・編集

AsciiDoc自体の記述はテキストエディタさえあれば可能ですが、プレビューをしながら編集したり、編集した文書をシームレスに別形式へ変換したりするには、Visual Studio Codeのような高機能エディタの使用や、拡張機能のインストールがおのずと求められます。

・環境構築

AsciiDoc文書をPDFやHTMLとして出力するためには、Ruby環境やAsciidoctorのインストールが必要となります。

・出力のカスタマイズ

テーマファイルやスタイルシートの設定、日本語フォントの適用など、出力のカスタマイズをするためには、関連する知識が必要となります。

これらに関しては、いずれもWeb上で情報を手に入れることができます。
逆に言えば、これらの対応にハードルを感じない環境であれば、AsciiDoc文書の運用をスムーズに始めることができると思います。

4. まとめ：Asciidoc変換で文書管理を効率化

AsciiDocは表現力と拡張性に優れた言語で、Asciidoctorを使えば多様な出力も可能です。特にマニュアル制作やチームでのドキュメント管理において、強力な選択肢になり得ます。

ヒューマンサイエンスは、日本語版のマニュアル作成から英語および多言語翻訳まで、ワンストップでご支援いたします。1985年からの長きにわたり数々のマニュアルを手がけてきた実績があります。
マニュアルの構築・運用にお悩みの方は、ヒューマンサイエンスの導入支援サービスをご活用ください。GitHubや軽量マークアップ言語の活用を通じて、効率的で一貫性のあるドキュメント作成をサポートします。
ぜひお気軽にご相談ください。

GitHub/Markdown/Asciidoc導入支援サービス