8 unstable releases (3 breaking)

0.4.1 Oct 9, 2024
0.4.0 Oct 9, 2024
0.3.3 Sep 21, 2024
0.3.1 Aug 29, 2024
0.1.1 Aug 29, 2024

#155 in Development tools

Download history 293/week @ 2024-08-24 56/week @ 2024-08-31 4/week @ 2024-09-14 166/week @ 2024-09-21 26/week @ 2024-09-28 255/week @ 2024-10-05 48/week @ 2024-10-12 1/week @ 2024-10-19

306 downloads per month

Custom license

165KB
324 lines

logo

mtoc 📄

Markdown table of contents generator

Built with ❤ in Rust

Table of Contents generated with mtoc

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 Rust
Crates Crates.io Version
Release Release
Code Code Size
CI - Build Build
CI - Release Build
CI - Test Build
CI - Coverage Build
Meta pre-commit License - MIT
Codecov codecov

Supported Platforms

Arch ARM64 AMD64
darwin
linux
windows

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

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

Dependencies

~5–15MB
~200K SLoC