1
Fork 0
mdbook-toc/README.md

90 lines
1.4 KiB
Markdown
Raw Permalink Normal View History

2018-07-20 10:07:21 +00:00
# mdbook-toc
2019-07-10 19:22:50 +00:00
A preprocessor for [mdbook][] to add inline Table of Contents support.
2018-07-20 10:07:21 +00:00
[mdbook]: https://github.com/rust-lang-nursery/mdBook
2023-06-01 14:41:26 +00:00
It turns this marker:
2018-07-20 10:07:21 +00:00
```md
2018-07-20 10:07:21 +00:00
<!-- toc -->
```
2023-06-01 14:41:26 +00:00
into a Table of Contents based on headings of the chapter following the marker.
2018-07-20 10:07:21 +00:00
## Installation
If you want to use only this preprocessor, install the tool:
```sh
2019-07-10 19:15:33 +00:00
cargo install mdbook-toc
2018-07-20 10:07:21 +00:00
```
2019-07-10 19:15:33 +00:00
Add it as a preprocessor to your `book.toml`:
2018-07-20 10:07:21 +00:00
```toml
2019-07-10 19:15:33 +00:00
[preprocessor.toc]
command = "mdbook-toc"
renderer = ["html"]
2018-07-20 10:07:21 +00:00
```
2019-07-10 19:15:33 +00:00
Finally, build your book as normal:
2018-07-20 10:07:21 +00:00
```sh
2019-07-10 19:15:33 +00:00
mdbook path/to/book
2018-07-20 10:07:21 +00:00
```
## Configuration
### Custom TOC marker
The default marker is:
```md
<!-- toc -->
```
If you wish to use a different marker, such as the GitLab marker `[[_TOC_]]`, you must add the following settings to your `book.toml`.
```toml
[preprocessor.toc]
marker = "[[_TOC_]]"
```
You can also use multi-line markers such as the GitHub marker, which is:
```md
* auto-gen TOC;
{:toc}
```
Configure the string with a newline:
```toml
[preprocessor.toc]
marker = "* auto-gen TOC;\n{:toc}"
```
or with multi-line strings:
```toml
[preprocessor.toc]
marker = """* auto-gen TOC;
{:toc}"""
```
### Maximum header level
By default the ToC will include headings up to level 4 (`####`).
This can be configured in your `book.toml` as follows:
```toml
[preprocessor.toc]
max-level = 4
```
2018-07-20 10:07:21 +00:00
## License
MPL. See [LICENSE](LICENSE).
2020-04-06 08:39:07 +00:00
Copyright (c) 2018-2020 Jan-Erik Rediger <janerik@fnordig.de>