mdbook-indexing

A preprocessor for mdbook to support building an index.

• Phrases enclosed in {{i:<text>}} are transmitted as-is to the rendered output, but also get an index entry added for them.
• Phrases enclosed in {{ii:<text>}} are transmitted to the rendered output as italics, but also get an index entry added for them.
• Phrases enclosed in {{hi:<text>}} are removed from the rendered output, but get an index entry added for them anyway.
• The contents of any chapter with name Index are replaced by the accumulated contents of the index.
  • Note that it's best not to use index.md as the filename for the index, as that will become index.html and end up being the default landing page for the book. An alternative name (e.g. indexing.md) for the file avoids this.

Installation

To use, install the tool

cargo install mdbook-indexing

and add it as a preprocessor in book.toml:

[preprocessor.indexing]

Configuration

See Instead

Key-value pairs in the [preprocessor.indexing.see_instead] section of the book.toml configuration file indicate index entries where the key should point to the value. Thus an entry like:

"unit type" = "`()`"

would result in an index entry that says: "unit type, see ()" (instead of a list of locations).

Nested Entries

Key-value pairs in the [preprocessor.indexing.nest_under] section of the book.toml configuration file indicate index entries where the entry for the key should be nested under value. Thus an entry like:

"generic type" = "generics"

would result in the index entry for "generic type" being only listed as an indented sub-entry under "generics".

The suppress_head Boolean config option indicates whether sub-entries that start with the text of the main entry should have that prefix removed. With this option un-set, a nested index might be:

test, 1, 2, 3
    test, fuzz, 1
    test, unit, 1, 2

If the option is set, this would change to:

test, 1, 2, 3
    fuzz, 1
    unit, 1, 2

Chapter Names

The use_chapter_names boolean config option enables a mode where the generated index uses the names of chapters where index entries are located, rather than just numbers.

Skip Renderer

The skip_renderer config option allows indexing output to be skipped for some renderers, specified as a comma-separated list.

Limitations

• Avoid putting the index inside a link, as it breaks the link, i.e. prefer:

  {{i:[text](http:link)}}

  to:

  [{{i:text}}](http:link)