【AsciiDoc入門】基本のテキスト装飾・見出しと目次の自動生成をマスターしよう！

前回の記事「【完全解説】AsciiDocのインストール方法とMarkdown（マークダウン）徹底比較」では、AsciiDocの概要や各OSでのインストール方法、そしてVS Code（Visual Studio Code）の拡張機能を使った手軽な始め方について解説しました。

VS Codeの準備はバッチリでしょうか？連載第2回となる今回は、いよいよ実際にドキュメントを書き始めるための「基本のテキスト装飾」「見出しの書き方」、そしてAsciiDocの神機能の1つである「目次の自動生成」について詳しく解説します！

Markdownと似ている部分も多いですが、AsciiDocならではの便利なルールもあるので、ぜひ手を動かしながら試してみてください。

1. 基本のテキスト装飾（太字・斜体・等幅）

まずは、文章の一部を強調したり目立たせたりする基本的な装飾方法です。Markdownとの違いを意識しながら見ていきましょう。

文字列を アスタリスク * で囲みます。Markdownと同じ感覚で使えます。

test

*test*

文字列を アンダースコア _ で囲みます。

test

_test_

コマンドやソースコード、キーボードの入力を表現するときは、バッククォート ` で囲みます。

test

`test`

AsciiDocには「単語の一部分だけを太字にしたい」という場合に便利なルールがあります。記号を2つ重ねることで、スペースで区切られていない単語の途中でも部分的に装飾が可能です。

test

t**es**t

t__es__t

t``es``t

ドキュメントの構造を作る「見出し」は、イコール = を使って表現します。Markdownの # が = に変わったイメージです。

= ドキュメントのタイトル（H1相当・トップに1つだけ）

== 大見出し（H2相当）
文章がここに入ります。

=== 中見出し（H3相当）
さらに細かい解説。

==== 小見出し（H4相当）
補足情報など。

= の後ろには必ず 半角スペース を1つ入れてください。
一番上の = タイトル は、ドキュメント全体で最初の一行に1回だけ使用するのが基本ルールです（HTMLの <h1> タグ、本の表紙タイトルに相当します）。
本文内の章や節を区切るときは、== 大見出し から使い始めましょう。

前回の比較記事（https://niyanmemo.com/7489/ ）でもお伝えした通り、AsciiDocの強力なメリットの1つが「標準機能での目次の自動生成」です。

Markdownではツールやプラグインに頼る必要があった目次の作成ですが、AsciiDocならドキュメントの先頭（タイトルの直後）に属性（Attributes）を数行書き足すだけで、見出しから自動的に美しい目次（Table of Contents）を生成してくれます。

= AsciiDocのテスト文書
:toc: left
:toclevels: 3
:toc-title: 目次

== 1. はじめに
ここに本文が入ります。

== 2. インストール方法
ここに本文が入ります。

:toc: left 目次（TOC）を有効にします。left を指定すると、VS CodeのプレビューやHTML出力時に画面の左側にサイドバーとして目次が固定されます。右側にしたい場合は right、本文の先頭に埋め込みたい場合は macro や値なし（:toc:）を指定します。
:toclevels: 3 目次に表示する見出しの深さを指定します。上記の場合は === 中見出し（H3） までを目次に自動で拾ってくれます。
:toc-title: 目次 デフォルトでは「Table of Contents」と表示されてしまう目次のタイトルを、日本語の「目次」に変更します。