kevingimbel/mktoc

🦀 Markdown Table of Content generator

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.

mktoc's Issues

Extract input manipulation

The code responsible for adding the ToC is inside the make_toc function. This means a third-party user cannot get a full Markdown file generated without specifying an actual file (make_toc takes a file path).

https://github.com/KevinGimbel/mktoc/blob/main/src/lib.rs#L227-L237

Todo

Extract code into function

fn add_toc(original_file_content: String, new_toc: String) -> String

Write tests

• Adding the ToC is implicitly tested, should be explicitly tested

Automate binary releases

Find a way how binaries can be released and added to GitHub Releases.

Feature: wrap ToC in details block

Add an option to wrap the generated ToC in a <details> element.

Example:

Table of Contents

• Installation 🤖
  • Build from source
    • Prerequisites
    • Instructions
  • Binary releases
  • Docker
    • Images
    • Usage
    • Building

Code:

<!-- BEGIN mktoc -->
<details>
  <summary>Table of Contents</summary>

- [Installation 🤖](#installation)
  - [Build from source](#build-from-source)
    - [Prerequisites](#prerequisites)
    - [Instructions](#instructions)
  - [Binary releases](#binary-releases)
  - [Docker](#docker)
    - [Images](#images)
    - [Usage](#usage)
    - [Building](#building)
</details>
<!-- END mktoc -->

Important:

• Newline after <summary> is required, otherwise the markdown is not parsed.
• Should be configurable via ENV, cli argument, and inline config

Strip special characters

Special characters like ( must be removed from the link.

The headline

## MongoDB (Atlas)

must be linked as

- [MongoDB (Atlas)](#mongodb-atlas)

but currently mktoc produces a link like

- [MongoDB (Atlas)](#mongodb-(atlas))

Replace structopts with clap

structopts will not receive new features and is integrated with clap, see https://github.com/texitoi/structopt#maintenance

As clap v3 is now out, and the structopt features are integrated into (almost as-is), structopt is now in maintenance mode: no new feature will be added.

almost as-is makes it seem like this shouldn't be much work.

Links in Headlines produce wrong output

The rendered output is wrong

Code:

<!-- BEGIN mktoc -->

  - [Links in [Headlines](/headlines/)](#links-in-headlinesheadlines)
<!-- END mktoc -->

### Links in [Headlines](/headlines/)

Rendered like:

• [Links in Headlines](#links-in-headlinesheadlines)

Desired Output:

<!-- BEGIN mktoc -->

  - [Links in Headlines](#links-in-headlines)
<!-- END mktoc -->

### Links in [Headlines](/headlines/)

---

Link inside a Headline must be stripped out.

Proper documentation

Actually write down how to use mktoc.

Parsing issues

Since we're using a "simple" Regex based parser to find headlines we also get things that are not a headline, e.g. comment blocks inside of code snippets:

# my comment
pub fn is_issue() -> bool {
  true
}

Here # my comment would be added to the Table of Contents. So far I cannot think of a way to fix this without using a markdown parser to process the markdown before getting the headlines.

Add Windows binaries to release action

Binaries are now build with GitHub Actions (https://github.com/KevinGimbel/mktoc/blob/main/.github/workflows/release.yml), so Windows binaries should be supported alongside Apple and Linux ones.

I know nothing about Windows binaries so I'm unsure which of these targets make sense to build for:

• x86_64-pc-windows-msvc
• x86_64-pc-windows-gnu
• i686-pc-windows-msvc
• i686-pc-windows-gnu

Maybe all of them?

cargo-dist

We want to use cargo-dist to replace the current release pipeline with a new shiny one. Additionally, we want to build brew taps so installation on MacOS and Linux is smoother!

https://opensource.axo.dev/cargo-dist/
https://github.com/axodotdev/cargo-dist