mktocMarkdown Table of Content generator
- About
- Installation
- Cargo
- Binary
- Usage
- Update Markdown file
- Inline config
- min_depth
- max_depth
- wrap_in_details
- Command line
mktoc parses markdown files and generates a Table Of Content linking all headlines up to heading level 6 deep, or as specified by command line arguments, environment variables, or inline JSON config (see Usage).
mktoc can be installed using Cargo, the Rust package manager.
Installation
sh
$ cargo install mktoc
Update
sh
$ cargo install --force mktoc
Binaries are not available yet. If you know how releasing binaries with Rust can be implemented, please let me know!
Add the following HTML comment into the Markdown file where the Table of Contents should be rendered.
html
<!-- BEGIN mktoc -->
<!-- END mktoc -->
Everything between those comments will be replaced!
Starting with version 3.0.0 it's possible to set values in-line which is great when collaborating with teams who may have individual settings.
html
<!-- BEGIN mktoc {"min_depth": 2, "max_depth": 4, "wrap_in_details": false} -->
<!-- END mktoc -- >
this is equal to running mktoc -m 2 -M 4 or setting these environment variables MKTOC_MIN_DEPTH=2 and MKTOC_MAX_DEPTH=4.
Inline config takes priority over environment or CLI arguments.
min_depthThe minumum depth to look for, defaults to 1 which is equal to <h1> or #.
max_depthThe maximum depth to look for, defaults to 6 which is equal to <h6> or ######.
wrap_in_detailsIf set to true, the ToC will be wrapped in a <details> element.
Specify --stdout or -s to output generated content to stdout instead of overwriting file. By default the specified file will be overwritten.
```sh $ mktoc -h Generate Table of Contents from Markdown files
Usage: mktoc [OPTIONS] [FILE]
Arguments: [FILE] [default: README.md]
Options:
-s, --stdout If set will output to stdout instead of replacing content in file
-m, --min-depth
sh
$ mktoc -s README.md
$ mktoc -m 2 -M 4 README.md
$ mktoc
```
If no arguments are given the default or configured (via environment) values are
used.
See mktoc --help for list of all arguments and flags.
```sh mktoc
USAGE: mktoc [FLAGS] [OPTIONS] [file]
FLAGS: -h, --help Prints help information -s, --stdout If set will output to stdout instead of replacing content in file -V, --version Prints version information
OPTIONS:
-M, --max-depth
ARGS:
mktoc can be configured with environment variables, namely:
MKTOC_MIN_DEPTH equal to -mMKTOC_MAX_DEPTH equal to -MPlace these variables in a shell environment file such as ~/.bashrc or
~/.zshrc, then just run mktoc without -m and -M
```sh
$ mktoc README.md ```
For VSCode the Run on save extension can be used to trigger mktoc.
Install the extension and then add the following config to workspace or user settings.json.
json
"emeraldwalk.runonsave": {
"commands": [
{
"match": "\\.md$",
"cmd": "mktoc ${file}"
}
]
}
This will run the command for every markdown file on safe. If there is no mktoc comment in the Markdown file nothing happens.
mktoc is fast but can probably be even faster! Pull Requests and bug reports are appreciated!
We love and welcome every form of contribution.
Here are some good places to start:
Sometimes it's nice to install a specific version of mktoc, this can be done with the following command:
```sh
cargo install --git https://github.com/KevinGimbel/mktoc --force --rev $COMMIT_ID
cargo install --git https://github.com/KevinGimbel/mktoc --force --branch $BRANCH_NAME ```
MIT, see LICENSE file.