Index

You can mark index terms explicitly in AsciiDoc content. Index terms form a controlled vocabulary that can be used to navigate the document by keyword starting from an index.

Index catalog

Although index terms are always processed, only Asciidoctor PDF and the DocBook toolchain support creating an index catalog automatically. The built-in HTML5 converter in Asciidoctor does not generate an index.

To create an index, define a level 1 section (==) marked with the style index at the end of your document. (In a multipart book, the index can be the last level 0 section (=)).

[index]
== Index

Both Asciidoctor PDF and the DocBook toolchain will automatically populate an index into this seed section.

The index will consist of term entries that link to (or otherwise cite) the location of each marked index term. You learn how to mark an index term in the next section.

Index terms

Every index term, as well as every occurrence of that index term, must be explicitly marked in the AsciiDoc document. It’s not enough just to mark the first occurrence of an index term if you want every occurrence to appear in the index. Instead, each occurrence you want to be cited in the index must be marked explicitly.

There are two types of index terms in AsciiDoc:

flow index term

indexterm2:[<primary>]
((<primary>))

An index term that appears in the flow of text (i.e., a visible term) and in the index. This type of index term can only be used to define a primary entry and is case sensitive. If you want the entry to appear in the index using a different case, use an adjacent concealed index term, such as ((term))Term.

concealed index term

indexterm:[<primary>, <secondary>, <tertiary>]
(((<primary>, <secondary>, <tertiary>)))

A group of index terms that appear only in the index. This type of index term can be used to define a primary entry as well as optional secondary and tertiary entries.

Here’s an example that shows the two forms in use.

The Lady of the Lake, her arm clad in the purest shimmering samite,
held aloft Excalibur from the bosom of the water,
signifying by divine providence that I, ((Arthur)), (1)
was to carry Excalibur(((Sword, Broadsword, Excalibur))). (2)
That is why I am your king. Shut up! Will you shut up?!
Burn her anyway! I'm not a witch.
Look, my liege! We found them.

indexterm2:[Lancelot] was one of the Knights of the Round Table. (3)
indexterm:[knight, Knight of the Round Table, Lancelot] (4)
1 The double parenthesis form adds a primary index term and includes the term in the generated output.
2 The triple parenthesis form allows for an optional second and third index term and does not include the terms in the generated output (i.e., concealed index term).
3 The inline macro indexterm2:[primary] is equivalent to the double parenthesis form.
4 The inline macro indexterm:[primary, secondary, tertiary] is equivalent to the triple parenthesis form.

If you’re defining a concealed index term (i.e., the indexterm macro), and one of the terms contains a comma, you must surround that segment in double quotes so the comma is treated as content. For example:

I, King Arthur.
indexterm:[knight, "Arthur, King"]

or

I, King Arthur.
(((knight, "Arthur, King")))

Placement of hidden index terms

Hidden index entries should be directly adjacent to the paragraph content to which they apply. Example 1 shows where to place hidden index terms for a paragraph.

Example 1. Correct
=== Create a new Git repository

(((Repository, create)))
(((Create Git repository)))
To create a new git repository,

If the terms are offset from the paragraph content by an empty line, it will cause an empty paragraph to be created in the parsed document, thus leaving extra space in the generated output. Example 2 and Example 3 show where you should not place hidden index terms for a paragraph.

Example 2. Incorrect
=== Create a new Git repository

(((Repository, create)))
(((Create Git repository)))

To create a new git repository,
Example 3. Also incorrect
=== Create a new Git repository
(((Repository, create)))
(((Create Git repository)))

To create a new git repository,