Graphic design is my passion ✨
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
$ cargo install mktocUpdate
$ cargo install --force mktocBinaries for Linux and MacOS can be downloaded from the release page.
Windows Binaries are not yet build automatically, see #7.
Add the following HTML comment into the Markdown file where the Table of Contents should be rendered.
<!-- 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.
<!-- 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.
The minumum depth to look for, defaults to 1 which is equal to <h1> or #.
The maximum depth to look for, defaults to 6 which is equal to <h6> or ######.
If 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.
$ 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 <MIN_DEPTH> Minimum heading level [env: MKTOC_MIN_DEPTH=] [default: 1]
-M, --max-depth <MAX_DEPTH> Maximum heading level [env: MKTOC_MAX_DEPTH=] [default: 6]
-w, --wrap-in-details Wrap ToC in details html element [env: MKTOC_WRAP_IN_DETAILS=]
-h, --help Print help
-V, --version Print version
$ mktoc -s README.md
$ mktoc -m 2 -M 4 README.md
$ mktocIf no arguments are given the default or configured (via environment) values are used.
See mktoc --help for list of all arguments and flags.
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 <max-depth> Maximum heading level [env: MKTOC_MAX_DEPTH=] [default: 6]
-m, --min-depth <min-depth> Minimum heading level [env: MKTOC_MIN_DEPTH=2] [default: 1]
ARGS:
<file> [default: README.md]mktoc can be configured with environment variables, namely:
MKTOC_MIN_DEPTHequal to-mMKTOC_MAX_DEPTHequal to-M
Place these variables in a shell environment file such as ~/.bashrc or
~/.zshrc, then just run mktoc without -m and -M
# The following in ~/.bashrc|~/.zshrc configures mktoc to render headings from level 2 to
# level 4
#
# MKTOC_MIN_DEPTH=2
# MKTOC_MAX_DEPTH=4
# MKTOC_WRAP_IN_DETAILS=true
$ mktoc README.mdFor 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.
"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:
- Issues with label Good first issue
- Issues with label Documentation
- Providing example implementations or usage demos
Sometimes it's nice to install a specific version of mktoc, this can be done with the following command:
# install specific commit
cargo install --git https://github.com/KevinGimbel/mktoc --force --rev $COMMIT_ID
# install branch
cargo install --git https://github.com/KevinGimbel/mktoc --force --branch $BRANCH_NAMEMIT, see LICENSE file.