mktoc

Graphic design is my passion ✨

Table of Contents

• About
• Installation
  • Cargo
  • Binary
• Usage
  • Update Markdown file
    • Inline config
      • min_depth
      • max_depth
      • wrap_in_details
  • Command line
  • Environment configuration
• Auto-run with VSCode
• Performance
• Contributing
  • Where to start?
  • Tooling
  • Install dev build
• License

About

⬆️ Back to Top

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).

Installation

⬆️ Back to Top

mktoc can be installed using Cargo, the Rust package manager.

Cargo

Installation

$ cargo install mktoc

Update

$ cargo install --force mktoc

Binary

Binaries for Linux and MacOS can be downloaded from the release page.

Windows Binaries are not yet build automatically, see #7.

Usage

Update Markdown file

⬆️ Back to Top

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!

Inline config

⬆️ Back to Top

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.

min_depth

The minumum depth to look for, defaults to 1 which is equal to <h1> or #.

max_depth

The maximum depth to look for, defaults to 6 which is equal to <h6> or ######.

wrap_in_details

If set to true, the ToC will be wrapped in a <details> element.

Command line

⬆️ Back to Top

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
$ 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.

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]

Environment configuration

⬆️ Back to Top

mktoc can be configured with environment variables, namely:

• MKTOC_MIN_DEPTH equal to -m
• MKTOC_MAX_DEPTH equal 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.md

Auto-run with VSCode

⬆️ Back to Top

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.

"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.

Performance

⬆️ Back to Top

mktoc is fast but can probably be even faster! Pull Requests and bug reports are appreciated!

Contributing

⬆️ Back to Top

We love and welcome every form of contribution.

Where to start?

Here are some good places to start:

• Issues with label Good first issue
• Issues with label Documentation
• Providing example implementations or usage demos

Tooling

• mktoc is used for table of content generation in the README.md (neat!)
• criterion for benchmarking

Install dev build

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_NAME

License

⬆️ Back to Top

MIT, see LICENSE file.