本文書では、Asciidoc 冒頭部の設定例を示し、それぞれの設定（document attribute）について解説する。

更新履歴

Date	Version	Comment
2021-05-02	1.0	初版作成
2021-01-08	1.1	メールアドレス修正。:doctype: article　追加。概要を [Abstract] 形式に。更新履歴に番号なしのセクションタイトルを付加

Asciidoc 冒頭部の書き方

Asciidoc 冒頭部には、文書のレンダリング（整形）の仕方を設定する document
attribute を記述する。Asciidoc 冒頭部の書き方の例を以下に示す。詳細は、参考文献を参照。

Asciidoc 冒頭部の設定例

= Asciidoc 冒頭部の設定例
三浦克介 <miura.katsuyoshi+github@gmail.com>
v1.1, 2023-01-08
:doctype: article
:lang: ja
:toc: left
:toc-levels: 3
:toc-title: 目次
:sectnums:
:sectnum-levels: 3
:icons: font
:imagesdir: Images
:xrefstyle: short
:abstract-caption: 概要
:figure-caption: 図
:table-caption: 表
:listing-caption: リスト
:appendix-caption: 付録
:example-caption: 例
:source-highlighter: highlightjs
:stem: latexmath

Asciidoc 文書設定の説明

前節で示した Asciidoc 文書設定の各項目について、設定内容を以下に示す。

項目名	値	説明
doctype	article	文書タイプ：article, book, manpage, inline
lang	ja	言語設定
toc	left	目次の配置位置：left はページ左側に目次を配置する。但し、ページ幅が狭い場合は、自動的に文書冒頭部に配置される
toc-levels	3	目次に表示されるセクションレベルの最大値。toc-levels=3 は、`===` で記述されるセクションまでが目次に表示される。但し、`=` は文書タイトルであり、これは目次には表示されない。
toc-title	目次	目次のタイトル部に表示される文字列。
sectnums		章に番号を付ける。
sectnum-levels	3	番号を付ける章の最大レベル。`=` は文書タイトルなので、`==` が第1レベルの章を示す。
icons	font	CAUTION:, WARNING:, NOTE:, TIPS: の欄に、アイコンを表示する。
imagesdir	Images	画像を格納するディレクトリ。
xrefstyle	short	図や表などを参照する際、「図1」の様に表示する。
figure-caption	図	図番号に付ける文字列。
table-caption	表	表番号に付ける文字列。
listing-caption	リスト	リスト番号に付ける文字列。
appendix-caption	付録	付録を示す文字列。
example-caption	例	例を示す文字列。
source-highlighter	highlightjs	ソースコードを表示する際、シンタックスハイライトを行う。この作業を行う外部ツールとして、highlight.js を用いる ¹ 。
stem	latexmath	STEM (Science, Technology, Engineering and Math) による数式表示を有効にし、LaTeX 形式を選択。latexmath を指定しない場合は、AsciiMath 形式。なお、数式は、HTML 形式に変換した場合のみ正しく表示される。

参考文献

Asciidoctor User Manual, Appendix A: Catalog of Document Attributes,
http://www.seinan-gu.ac.jp/~shito/asciidoctor/html_chunk/chap99.html
Asciidoctor 文法クイックリファレンス(日本語訳),
https://takumon.github.io/asciidoc-syntax-quick-reference-japanese-translation/
Katsuyoshi Miura, asciidoc_settings, GitHub, https://github.com/miura-katsuyoshi/asciidoc_settings

ソースコードのシンタックスハイライトを行うツールとして、highlight.js の他に、coderay, prettify, pygments, rouge がある。いずれも、外部ツールのインストールが必要。VsCode に Asciidoc 拡張をインストールしていれば、highlight.js は外部ツール無しでシンタックスハイライトが可能。 ↩