mtoc 📄

Markdown table of contents generator

Built with ❤ in Rust

Table of Contents generated with mtoc

• Introduction
• Badges
• Supported Platforms
• Installation
  • Install latest binary version
  • Install specific binary version
  • Install using cargo
• Uninstall
• Usage
  • Help
  • Generate TOC
  • Generate TOC for a specific directory
  • Exclude directories from search
  • Generate TOC for a specific file
• Using pre-commit
• Example
• Local development
• IN PROGRESS
• License

Introduction

I'm very supper fan of doctoc and I use it a lot, but I wanted to create a similar tool in Rust.

From this:

# Hello
## World
### How are you?

To this:

<!-- START OF TOC !DO NOT EDIT THIS CONTENT MANUALLY-->
**Table of Contents**  *generated with [mtoc](https://github.com/containerscrew/mtoc)*
- [Hello](#hello)
  - [World](#world)
    - [How are you?](#how-are-you?)
<!-- END OF TOC -->

Badges

Language
Crates
Release
Code
CI - Build
CI - Release
CI - Test
CI - Coverage
Meta
Codecov

Supported Platforms

Maybe in windows systems this tool will work, but has not been tested

Installation

Install latest binary version

curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/containerscrew/mtoc/main/install.sh | sh

Install specific binary version

curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/containerscrew/mtoc/main/install.sh | sh -s -- -v "v0.8.0"

Install using cargo

• Install Cargo

cargo install mtoc

If you want to update the tool to a new version, just the run the same command cargo install mtoc.

Uninstall

Binary:

sudo rm /usr/local/bin/mtoc

With cargo:

cargo uninstall mtoc

Usage

By default, the command will search for markdown files in the current directory and generate the table of contents for each file. But, you can specify a directory to search for markdown files, specify only a specific file, or exclude directories from the search.

Help

$ mtoc --help

Git markdown table of contents generator.

Usage: mtoc [OPTIONS]

Options:
  -d, --directory <DIRECTORY>     Directory to search for markdown files [default: .]
  -e, --exclude-dir <EXCLUDE>...  Exclude directories from search
  -f, --file <FILE>...            Only generate TOC for the specified file(s)
  -h, --help                      Print help
  -V, --version                   Print version

Generate TOC

mtoc # default the current dir where the command is executed. All the files, all the directories will be scanned.

Generate TOC for a specific directory

mtoc -d /path/to/directory

Exclude directories from search

mtoc -e ".target/" -e "node_modules/"

Generate TOC for a specific file

mtoc -f README.md

Using pre-commit

Add this configuration to your .pre-commit-config.yaml

  - repo: https://github.com/containerscrew/mtoc
    rev: v0.3.2 # use the most recent tag
    hooks:
      - id: mtoc
        args: [ "-e", ".target/" ]

Always stay up to date with the latest changes in the project markdown files.

Example

$ mtoc -e ".target/"                                                                                                                                                                                                                                         🦀 v1.80.1
Excluding directories  [".target/"]
Updated markdown file  ./docs/test.md
Updated markdown file  ./CHANGELOG.md
Updated markdown file  ./README.md

Local development

1. Make your changes
2. Run pre-commit
3. Test and build pipelines must pass

$ pre-commit install
# Or run once
$ pre-commit run -a

IN PROGRESS

IN PROGRESS

License

mtoc is distributed under the terms of the GNU AFFERO GENERAL PUBLIC LICENSE.