最初に属性の存在を知らずに書いていたときは、バージョン番号やリンク先URLを文中に直接ベタ書きしていて、変更のたびに全文検索・置換をしていました。属性でまとめて管理できると知ってからは、その手間がほぼなくなりました。

基本構文の全体像

AsciiDocの基本的な装飾記法は、Markdownを触ったことがあれば直感的に読めるものがほとんどです。まずは見出し・段落・強調といった基礎から確認します。

見出しと段落

見出しは=の数でレベルを表します。文書タイトル（レベル0）は=1つ、以降は章・節・項と=を1つずつ増やします。

AsciiDoc — 見出しと段落 
= 文書タイトル（レベル0）

== 第1章（レベル1）

段落はそのまま改行なしで続けて書きます。
1行の途中で改行しても、変換結果では同じ段落として
連結されて表示されます。

段落と段落の間は、空行を1行入れることで区切ります。

=== 第1節（レベル2）

さらに深い階層はレベル3・4と続けられます（== の数を増やす）。

💡 Markdownとの違い

Markdownの見出しは#を使いますが、AsciiDocでは=を使います。また文書タイトル（レベル0の=1つ）は文書全体で1つだけという明確なルールがあり、章立ての構造がより厳密に扱われます。

強調・インラインコード

AsciiDoc — インライン装飾 
*太字* と _斜体_ と `インラインコード` を組み合わせられます。

**強い強調** と __より強い斜体__ のように、記号を2つ重ねる書き方もあります。

上付き文字は^text^、下付き文字は~text~で表現します。

[.underline]#下線付きテキスト# のように、role属性で装飾を拡張できます。
記法意味表示例
*text*太字text
_text_斜体text
`text`インラインコードtext
^text^上付き文字text上付き
~text~下付き文字text下付き

属性（Attribute）による要素の定義

属性の定義から本文中での置換、アンカーからxrefでの参照までの仕組みを示す図

図1: 文書ヘッダーで定義した属性は本文中で {name} 形式で置換され、見出しのアンカーはxrefで参照できる

属性は、文書全体で使い回す値や設定を1箇所で定義する仕組みです。文書ヘッダー（タイトル直下）で:属性名: 値の形式で宣言し、本文中では{属性名}で参照・置換します。

AsciiDoc — 属性の定義と参照 
= APIリファレンス
:app-version: 1.4.0
:api-base-url: https://api.example.com/v1
:author-name: あくろぽりす

このドキュメントは バージョン {app-version} 時点のものです。

エンドポイントのベースURLは {api-base-url} です。

作成者: {author-name}
変換後のHTML（本文抜粋）
このドキュメントは バージョン 1.4.0 時点のものです。
エンドポイントのベースURLは https://api.example.com/v1 です。
作成者: あくろぽりす

✅ 属性は「変更に強いドキュメント」の土台になる

バージョン番号やURLを本文中に直接書かず属性化しておくことで、更新時にヘッダーの1行を書き換えるだけで文書全体に反映できます。複数ファイルに分割した長文ドキュメント（PART 05で扱うinclude）でも、属性はファイルをまたいで共有されます。

よく使う組み込み属性

Asciidoctorには最初から用意されている属性も多く、宣言するだけで出力の挙動が変わります。

属性効果
:toc:目次を自動生成する
:toc: left目次を左サイドバーに固定表示する
:sectnums:見出しに章番号を自動採番する
:source-highlighter: rougeコードブロックのシンタックスハイライトを有効化する
:icons: fontadmonition（NOTE等）にアイコンフォントを使う
:doctype: book書籍形式（部・章構成）として扱う

アンカーとxrefによる相互参照

見出しには自動的にIDが割り振られますが、[[id]]や[#id]で明示的にアンカーを付けることもできます。参照する側は<<id>>、またはxref:id[表示テキスト]の形式でリンクを張ります。

AsciiDoc — アンカーとxref 
[[install-section]]
== インストール手順

このセクションでインストール方法を説明します。

== トラブルシューティング

インストールがうまくいかない場合は、
<<install-section>> の手順を再確認してください。

より読みやすいリンクテキストを付けたい場合は、
xref:install-section[インストール手順のセクション] のように書きます。

外部ファイルの見出しを参照する場合は
xref:other-file.adoc#some-id[他ファイルの見出し] のように
ファイル名を含めて指定します。

⚠️ アンカーIDの命名規則

IDには半角英数字・ハイフン・アンダースコアのみを使うのが安全です。日本語の見出しをそのまま自動採番に任せると、ビルドツールによってはIDが意図しない形式になることがあるため、重要な参照先には明示的にIDを付けることをおすすめします。

早見表

目的記法
文書タイトル= タイトル
見出し（章・節）== / === / ====
太字・斜体・コード*text* / _text_ / `text`
属性の定義:name: value（ヘッダー部）
属性の参照{name}
アンカーの明示[[id]] / [#id]
相互参照<<id>> / xref:id[text]

✅ 次の章では…

PART 04 では、リスト・表・コードブロック・画像・admonition（注意書き）といった、文書を構成する具体的な要素の表記方法をまとめて解説します。

→ PART 04 — 要素の表記方法へ