前回の連載第6回「【AsciiDoc入門】内部リンク（クロスリファレンス）と画像・動画の埋め込みをマスターしよう！」では、見出しを変更してもリンク切れを起こさない「クロスリファレンス」の書き方や、画像・動画の埋め込み方法について解説しました。
連載の最終回となる第7回は、エンジニアや技術ブロガー、仕様書作成者にとって欠かせない「ソースコードの埋め込みとシンタックスハイライト」について徹底解説します！
Markdownでもおなじみのコードブロック表示ですが、AsciiDocでは「タイトル（キャプション）の付与」「行番号の自動表示」「特定の行のハイライト」など、プレゼンテーション層の機能が非常に充実しています。
VS Codeでのリアルタイムプレビューを見ながら、綺麗で読みやすいコードブロックの作り方をマスターしましょう！
1. 基本的なコードブロックの書き方
最もシンプルなソースコードの囲み方です。
[source,python]
----
def hello():
print("Hello, AsciiDoc!")
hello()
----見え方
💡 記述のポイント
- コードブロックは
----（ハイフン4つ） で上と下を囲みます。 - 直前の行に
[source,言語名]を記述することで、その言語に応じたシンタックスハイライト（色付け）が有効になります。 - 指定できる言語例:
python,rust,bash,html,javascript,json,cなど
2. 【応用】コードに「タイトル」をつける
「このコードがどのファイルの何処理なのか」を読者に伝えるため、コードブロックの上にファイル名やタイトルを表示できます。
.src/main.py（Pythonの実行サンプル）
[source,python]
----
import sys
print(f"Python version: {sys.version}")
----
- コードブロックの直前に
.タイトル名（ドットから始まる文字列）を書くだけで、自動的に太字のキャプション（タイトル）として出力されます。
見え方
3. 【超便利】特定の行を解説する「Callout（注釈）機能」
「コードの〇行目の処理について説明したい」という場合に大活躍するのが Callout（注釈番号） です。
コード内に <1> や <2> と書くことで、コードのすぐ下で各行の解説を紐付けることができます。環境や出力形式に左右されず、VS CodeプレビューやPDF出力でも綺麗に表示されます。
= Rustのコード解説
:icons: font
[source,rust]
----
fn main() {
let mut vec = Vec::new(); <1>
vec.push(1); <2>
println!("{:?}", vec);
}
----
<1> 可変（mut）なVector配列を初期化
<2> 要素を末尾に追加💡 見た目のイメージ
コードの該当行の横に丸数字の ① や ② が表示され、直下にその番号の解説文が綺麗にレイアウトされます。コードの中に直接長いコメントを書かずに済むため、ソースコードの見た目を汚さずに分かりやすい解説が作成できます。
4. 【第4回のおさらい】実ファイル（include::）と組み合わせる
第4回（https://niyanmemo.com/7544/ ）で解説した include 機能と組み合わせることで、実際のプログラムファイルを直接コードブロック内に読み込むことができます。
フォルダ構成
my-document/
├── main.adoc
└── src/
└── main.rs記述例（main.adoc）
.src/main.rs
[source,rust,linenums]
----
include::src/main.rs[]
----コードをコピー＆ペーストして貼り付ける必要がなくなり、元プログラムを修正すればドキュメント内の表示コードも自動的に最新化されるため、コピペミスや更新漏れを完全に防止できます！
見え方
5. まとめ＆全7回の連載を振り返って
今回は、コードブロックの記述、言語ごとのハイライト、タイトルや行番号の表示テクニックについて解説しました。
- コードブロックは
----（ハイフン4つ） で囲む [source,言語名]でシンタックスハイライトを有効化- 直前に
.ファイル名を書くとタイトルが付けられる linenumsを追加するだけで行番号がつくinclude::と組み合わせれば実ファイルを直接読み込める
🎉 AsciiDoc入門連載完結！
全7回にわたってお届けしてきた「AsciiDoc入門」シリーズも、今回でひとまず完結です！
- 第1回: インストール方法とMarkdown徹底比較
- 第2回: 基本のテキスト装飾・見出し・目次の自動生成
- 第3回: 箇条書き・チェックボックス・定義リストの極意
- 第4回: ファイルの分割と結合（include）
- 第5回: 高度なテーブル（表組み）マスター
- 第6回: 内部リンク（相互参照）と画像・動画の埋め込み
- 第7回: コードブロックとシンタックスハイライト（今回）
Markdownの「手軽さ」を残しつつ、仕様書や技術書、大規模ドキュメントで圧倒的な威力を発揮するAsciiDoc。ぜひVS Codeの環境を活用して、今後のドキュメント作成やブログ執筆に役立ててみてください！
ご愛読ありがとうございました！
コメント