前回の連載第3回「【AsciiDoc入門】箇条書き・チェックボックス・定義リストの極意をマスターしよう！」では、箇条書きの階層化やMarkdownにはない「定義リスト（コロン2つ ::）」などの便利なリスト表現について解説しました。
連載第4回となる今回は、AsciiDocが「技術書」「仕様書」「大規模マニュアル」の作成で圧倒的に選ばれる最大の理由である、神機能「ファイルの分割と結合（include ディレクティブ）」について徹底解説します！
第1回の比較記事（https://niyanmemo.com/7489/ ）でも「AsciiDocの決定的な強み」として触れましたが、数百ページに及ぶドキュメントや万単位の文字数になるブログ連載も、この機能を使えば驚くほどスマートに管理できるようになります。
VS Codeでの実践的なフォルダ構成例と合わせて見ていきましょう！
1. なぜ「ファイルの分割」が必要なのか？
1つの大きなドキュメントを1つのファイル（例: index.adoc）だけで書き進めると、以下のような問題が発生します。
- スクロールが大変: 数千〜数万行になり、編集したい章を探すだけで一苦労。
- チーム開発での衝突（コンフリクト）: Gitなどで複数人で同時に編集すると、同じファイルを触るためコンフリクトが多発する。
- 見通しの悪さ: 各章の構成の入れ替えや全体像の把握が難しくなる。
AsciiDocの include 機能を使えば、「章ごとにファイルをバラバラに書いて、最後は1つのファイルにガッチャンコして出力する」という理想的な運用が標準機能だけで可能になります。
2. 基本の書き方（include:: ディレクティブ）
書き方はとてもシンプルです。結合したいメインのファイル（親ファイル）の中に、以下のように1行記述するだけです。
include::読み込みたいファイル名.adoc[]💡 記述のポイント
include::の後ろに読み込みたいファイルの相対パスを指定します。- 末尾には
[]（角カッコ） を必ずつけてください。（カッコ内に追加の属性を指定することも可能です）。
3. 実践！VS Codeでのディレクトリ構成とコード例
実際の開発や執筆現場でよく使われるディレクトリ（フォルダ）構成とコードの書き方を見てみましょう。
おすすめのフォルダ構成
my-document/
├── main.adoc <-- 親ファイル（全体をまとめるファイル）
└── chapters/ <-- 子ファイルをまとめるフォルダ
├── 01_intro.adoc <-- 第1章
├── 02_install.adoc <-- 第2章
└── 03_usage.adoc <-- 第3章① 親ファイル（main.adoc）の記述
親ファイルには、第2回（https://niyanmemo.com/7505/ ）で紹介したタイトルや目次自動生成（:toc:）などの全体設定を書き、本文の位置に include を配置します。
= AsciiDoc完全マニュアル
:toc: left
:toclevels: 3
:toc-title: 目次
:numbered:
// 各章のファイルを読み込む
include::chapters/01_intro.adoc[]
include::chapters/02_install.adoc[]
include::chapters/03_usage.adoc[](※ :numbered: を書いておくと、各見出しに「1.」「1.1」のような章番号を自動付与してくれます)
② 子ファイル（例: chapters/01_intro.adoc）の記述
子ファイル側には、全体設定や <h1> 相当の = タイトル は書かず、== 大見出し から書き始めます。
== はじめに
本書はAsciiDocの基本から応用までを解説した完全マニュアルです。
=== 本書の対象読者
* ドキュメント作成を効率化したいエンジニア
* 技術ブログをスマートに管理したいライターこれで main.adoc をVS Codeのリアルタイムプレビューで開くと、すべての章がガッチャンコされ、目次も全章分を合算して左側に自動生成されます！
4. 【応用】ソースコードの一部を直接埋め込む
include 機能の凄さは、.adoc ファイルの結合だけにとどまりません。なんと実際のプログラム（PythonやRustなどのソースコード）をそのままドキュメント内に直接読み込むことができます！
フォルダ構成
my-document/
├── main.adoc <-- 親ファイル（全体をまとめるファイル）
├── chapters/ <-- 子ファイルをまとめるフォルダ
│ ├── 01_intro.adoc <-- 第1章
│ ├── 02_install.adoc <-- 第2章
│ └── 03_usage.adoc <-- 第3章
└── src/ <-- プログラムソースを置くフォルダ
└── main.py <-- Pythonスクリプト記述例
== サンプルプログラムの解説
以下のコードは、今回作成したPythonスクリプトの実装です。
[source,python]
----
include::src/main.py[]
----
コピペの手間と「載せ間違い」がゼロになる！
仕様書や解説記事を書く際、コードをコピー＆ペーストしてドキュメントに貼り付けていると、「元のプログラムを修正したのに、仕様書のコードを更新し忘れた！」というミスがよく起きます。
プログラム自体を include しておけば、元コードを修正すればドキュメント内の表示コードも自動的に最新化されます。エンジニアにとってまさに感涙ものの神機能です。
5. まとめ
今回はAsciiDocの真骨頂である「ファイルの分割と結合（include）」について解説しました。
include::ファイルパス[]で外部ファイルを簡単に結合できる- 章ごとにファイルを分割することで、チーム開発や長文執筆が爆速・快適になる
.adocだけでなく、プログラムのソースコードも直接埋め込める
「最初は1つのファイルで書いていたけれど、長くなってきたから章ごとに分けたい」と思ったときでも、すぐにファイルを切り出して include に書き換えるだけで対応できます。
コメント