目次を操作する5つの設定 #AsciiDoc

AsciiDoc おける目次の設定方法をご紹介します。

このページでは、目次の表示/非表示やタイトル、表示するセクションレベル、表示位置を設定する方法、そしてセクションタイトルに番号を付ける方法について掲載しています。

目次の表示/非表示

目次を出力するには :toc: と記載します。

:toc:

「TOC」とは「Table of Contents」の略で、日本語では「目次」という意味です。

目次はデフォルトで出力されませんが、明示的に出力しない旨を AsciiDoc のソースに記載する場合は :toc!: と記載します。

:toc!:

目次に出力されるセクションレベルは :tocLevels: で指定できます。

:toc:
:tocLevels: 3

tocLevels 属性のデフォルト値は 2 です。

目次のタイトルを変更するには :toc-title: でタイトルを指定します。

目次のタイトルを [目次] に変更する場合は、次のように記載します。

:toc:
:toc-title: [目次]

デフォルトの値は Table of Contents です。

「目次は出力するが、目次のタイトルを出力しない」という場合には、目次のタイトルを指定せずに :toc-title: とだけ記載します。

:toc:
:toc-title:

ただし、目次のタイトルを囲う HTML は出力されます。

目次の表示位置を変更するには、toc 属性に値を指定します。
toc 属性に指定可能な値は left, right, preamble, macro, auto の5つで、デフォルトは auto です。

目次をコンテンツの左側に表示するには、toc 属性に left を指定します。

:toc: left

画面の幅が狭いと auto と同じ位置（文書タイトルのすぐ下）に表示されます。

目次をコンテンツの右側に表示するには、toc 属性に right を指定します。

:toc: right

画面の幅が狭いと auto と同じ位置（文書タイトルのすぐ下）に表示されます。

目次を文書タイトルのすぐ下に表示するには、toc 属性に auto と記載します。

:toc: auto

toc 属性のデフォルト値は auto なので、auto は省略できます。

:toc:

文書タイトルと最初のセクションタイトルの間の内容は「preamble(プリアンブル)」と呼ばれます。

目次をプリアンブルの下に表示するには、toc 属性に preamble を指定します。

:toc: preamble

= 文書タイトル

これはプリアンブルです。

== セクションタイトル

toc 属性に preamble を指定してもプリアンブルがない場合、目次は表示されません。

目次を特定の位置に表示するには、toc 属性に macro を指定します。
そして表示させる位置に toc::[] と記載します。

:toc: macro

= 文書タイトル

== セクション

toc::[]

セクション の内容

toc::[] は複数の場所に記載することができます。

セクションタイトルに番号を付けるに :sectNums: と記載します。
そして :sectNumLevels: で何階層目まで番号を付けるかを指定します。

:sectNums:
:sectNumLevels: 5

sectNumLevels 属性のデフォルト値は 3 です。

目次に影響する5つの共通属性をご紹介しました。

:toc: left
:toc-title: [目次]
:tocLevels: 3
:sectNums:
:sectNumLevels: 3

以上、この情報がお役に立てれば幸いです。