1つの.mdファイルが数千行になって編集が辛くなった経験から、includeで章ごとにファイルを分けられる仕組みには最初にとても助けられました。最終回は、この分割の仕組みとシリーズ全体のまとめです。

includeによるファイル分割

main.adocからinclude::で複数ファイルを取り込み、1つのHTML/PDFに結合される流れを示す図

図1: 章ごとにファイルを分けても、ビルド時には1つの成果物として結合される

include::ファイルパス[]マクロを使うと、別ファイルの内容をその位置に取り込めます。章立てのある文書を1ファイルにまとめず、章ごとに分割して管理できるため、長編ドキュメントの見通しが大きく改善します。

AsciiDoc — includeの基本 
= マニュアル全体
:doctype: book
:toc: left
:sectnums:

include::chapters/ch01-intro.adoc[]

include::chapters/ch02-install.adoc[]

include::chapters/ch03-usage.adoc[]

// 行範囲を指定して一部だけ取り込むことも可能
include::chapters/ch04-appendix.adoc[lines=1..20]

// タグで囲んだ範囲だけ取り込む（ソースコードの一部抜粋などに便利）
include::examples/sample.py[tag=main-logic]

💡 属性はファイルをまたいで共有される

親ファイル（例のmain.adoc）で定義した属性は、includeされた子ファイルの中でもそのまま参照できます。バージョン番号などを親ファイル1箇所で管理し、全章で使い回す構成が一般的です。

目次(TOC)の自動生成

:toc:属性を宣言するだけで、見出し構造から目次が自動生成されます。値によって表示位置を制御できます。

指定表示位置
:toc:本文の先頭（デフォルト位置）
:toc: left左サイドバーに固定表示
:toc: right右サイドバーに固定表示
:toc: macro本文中のtoc::[]マクロを書いた位置
:toclevels: 2目次に含める見出しレベルの深さを制限

✅ Markdownとの決定的な違い

Markdownで目次を作るには専用プラグインや手動でのリンク列挙が必要ですが、AsciiDocは属性を1行足すだけで目次・見出しレベル制御・表示位置までが完結します。

条件付きコンテンツ（ifdef / ifndef）

属性の有無によって、出力する内容を出し分けられます。社内向け／社外向けで内容を切り替えたい場合や、下書き段階のメモだけ最終稿から除外したい場合に使います。

AsciiDoc — 条件付きコンテンツ 
// 属性 internal が定義されている場合のみ出力
ifdef::internal[]
社内向け：この機能は現在ベータ版です。
endif::[]

// 属性 internal が定義されていない場合のみ出力
ifndef::internal[]
一般公開版のドキュメントです。
endif::[]

// コマンドラインから属性を渡してビルドを出し分ける
// asciidoctor -a internal manual.adoc

⚠️ 条件分岐は「表示/非表示」であってセキュリティ機能ではない

ifdef/ifndefはビルド時に該当ブロックを出力するかどうかを制御するだけです。ソース側の.adocファイル自体に機密情報が書かれている場合、リポジトリの閲覧権限とは別に管理する必要があります。

全5回の振り返り

PART内容
01AsciiDocとは — Markdownとの違いと採用メリット導入
02ツール導入 — Asciidoctorのインストールと変換環境構築環境構築
03基本構文と要素の定義 — 見出し・属性・相互参照記法
04リスト・表・コードブロック・画像・admonitionの表記方法記法
05（本記事）include・目次・条件付きコンテンツとまとめ応用

構文早見表（総集編）

目的記法
文書タイトル / 見出し= / == / ===
太字 / 斜体 / コード*text* / _text_ / `text`
属性の定義 / 参照:name: value / {name}
相互参照[[id]] と <<id>>
箇条書き / 番号付き / 説明* / . / 用語::
表|=== ... |===
コードブロック[source,言語] + ----
画像（ブロック / インライン）image:: / image:
admonitionNOTE: / TIP: / WARNING: 等
ファイル分割include::path[]
条件付きコンテンツifdef::attr[] ... endif::[]

✅ シリーズ完走おつかれさまでした

本シリーズで扱った範囲だけでも、章立てのある技術文書は十分に書けるはずです。困ったときは、公式ドキュメントのUser Manualが最も網羅的なリファレンスになります。