2 releases
0.1.1 | Jul 4, 2022 |
---|---|
0.1.0 | Jun 25, 2022 |
#682 in Text processing
30 downloads per month
23KB
272 lines
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
{{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 becomeindex.html
and end up being the default landing page for the book. An alternative name (e.g.indexing.md
) for the file avoids this.
- Note that it's best not to use
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".
Limitations
- Avoid putting the index inside a link, as it breaks the link, i.e. prefer:
to:{{i:[text](http:link)}}
[{{i:text}}](http:link)
- Index entries inside footnotes (from the
mdbook-footnote
preprocessor) do not work correctly.
Dependencies
~8–39MB
~676K SLoC