前回の連載第5回「【AsciiDoc入門】表作成の限界を突破！高度なテーブル（表組み）をマスターしよう！」では、縦横のセル結合やセル内での箇条書き（a|）、配置調整など、Markdownを超える高度な表組みテクニックを解説しました。
連載第6回となる今回は、ドキュメントの利便性と見栄えを飛躍的に向上させる「クロスリファレンス（相互参照）」と「画像・動画の埋め込み」について徹底解説します！
第1回の比較記事（https://niyanmemo.com/7489/ ）でもお伝えした通り、AsciiDocは長文の仕様書やマニュアルを作成する際に「リンク切れ」を起こしにくい設計が標準で備わっています。
VS Codeでの書き方とプレビューを見ながら、一緒にマスターしていきましょう！
1. クロスリファレンス（相互参照）とは？
クロスリファレンスとは、ドキュメント内の別の章や節へ案内する「内部リンク」のことです。例えば「詳細は第2回（〇〇）を参照」といったリンクを安全に貼ることができます。
Markdownでは「見出しのテキスト」をそのままアンカーとしてリンクを貼るため、後で見出しの文言を変更した際にリンク切れが発生しやすいというデメリットがありました。
AsciiDocなら、見出しに一意のID（識別子）を付与して紐付けるため、見出しのタイトルを後から変更してもリンクが壊れません！
2. クロスリファレンスの書き方
使い方は「リンク先にIDを設定する」と「リンク元から呼び出す」の2ステップです。
① リンク先に見出しIDを設定する（[[ID名]]）
リンクさせたい見出しの直前の行に、半角角カッコ2つで囲んだIDを記述します。
[[install-section]]
== 2. インストール手順
ここにインストールの詳細が入ります。
② リンク元から呼び出す（<<ID名>>）
文章内でその見出しを参照したい場所で、IDを << >> で囲みます。
[[install-section]]
== 2. インストール手順
ここにインストールの詳細が入ります。
環境構築の詳細については、<<install-section>> を確認してください。見え方
リンク先が表示されてみえます。
💡 ここが凄い！
上記のように <<install-section>> とだけ書くと、AsciiDocが自動的に対象の見出しタイトルを取得して、「環境構築の詳細については、2. インストール手順 を確認してください。」 というリンクテキストを出力してくれます！
もし表示されるリンクテキストを自分の好きな文字列に変えたい場合は、カンマ区切りで指定できます。
[[install-section]]
== 2. インストール手順
ここにインストールの詳細が入ります。
環境構築の詳細については、<<install-section>> を確認してください。
<<install-section, こちらのインストールガイド>> を参照してください。見え方
3. 画像の埋め込み（image::）
ドキュメントに画像を挿入する場合、インライン画像とブロック画像の2種類がありますが、基本的には独立した行として表示するブロック画像（image::）を使います。
基本的な書き方
image::icon.png[代替テキスト]- コロンは 2つ（
::） 書きます（第4回で解説したinclude::と同じスタイルです）。 []の中に画像が表示されない場合の代替テキスト（alt属性）を記述します。
見え方
画像のサイズや配置、キャプションを調整する
角カッコ [] の中や、画像の直前の行に属性を追加することで、サイズ調整やタイトル付けが可能です。
.図1: VS Codeのプレビュー画面
image::icon.png[VS Codeプレビュー, width=600, align="center"]見え方
.タイトル名: 画像の上に「図1: 〜」のようなキャプション（タイトル）を表示します。width=600: 横幅を600pxに指定します（width=50%のようなパーセント指定も可能）。align="center": 画像を中央寄せにします（leftやrightも指定可能）。
4. 動画や音声の埋め込み（video::）
AsciiDocは、ローカルの動画ファイル（.mp4等）やYouTubeの動画も標準シンタックスで埋め込むことができます！
YouTube動画を埋め込む場合
video::dQw4w9WgXcQ[youtube, width=640, height=360]見え方
すいません。手元にいい感じの動画ないので、サンプルなしです。。。
video:: の後ろに YouTubeの動画ID（URLの v= の後の文字列）を指定し、角カッコ内に youtube と記述するだけで、HTML出力時に埋め込みプレイヤーが生成されます。
5. まとめ
今回は、ドキュメントの回遊性とビジュアルを高める「クロスリファレンス」と「メディア埋め込み」について解説しました。
- クロスリファレンスは
[[ID]]で見出しにIDを付け、<<ID>>で安全に参照する - 見出しタイトルが変わってもリンク切れを起こさないのが強力なメリット
- 画像は
image::パス[代替テキスト, width=600, align="center"]でサイズや配置を柔軟にコントロール - 動画も
video::動画ID[youtube]で簡単に埋め込める
参照リンクや画像を使いこなすことで、大規模な仕様書やマニュアルの読みやすさが格段にアップします。
コメント