What is Markdown Toc

markdown-toc is a Table of Contents generator for Markdown files, developed in Rust. It helps users create structured and navigable documents by automatically generating a table of contents based on the headers in the Markdown file.

Use cases

Use cases for markdown-toc include generating a table of contents for software documentation, creating structured blog posts, organizing project documentation, and enhancing readability in lengthy Markdown files.

How to use

To use markdown-toc, you can run it in Docker, install it using Cargo, or build it from source. The basic command is ‘md-toc FILE’, where FILE is the Markdown file you want to generate a table of contents for. You can customize options such as bullet style, indentation, and header depth.

Key features

Key features of markdown-toc include the ability to customize bullet points, set indentation levels, limit the depth of headers included in the table of contents, and exclude specific links or headers from the generated ToC.

Where to use

markdown-toc can be used in various fields where Markdown is utilized, such as documentation, technical writing, blogging, and project README files. It is particularly useful for creating organized and easy-to-navigate documents.

markdown-toc

Table-of-Contents (toc) generator, written in Rust. Inspired by sebdah/markdown-toc.

Table of Contents

1. Table of Contents
2. Installation
   1. Run in Docker
   2. Install with cargo
   3. Build yourself
3. Usage
   1. Generating basic ToC
   2. Customizing bullets
   3. Limiting the depth of headers
   4. Excluding links
   5. Customizing header of ToC
      1. Excluding header

Installation

Run in Docker

docker run -v $PWD:/app -w /app --rm -it pbzweihander/markdown-toc README.md

Install with cargo

cargo install markdown-toc
md-toc README.md

Build yourself

git clone https://github.com/pbzweihander/markdown-toc.git
cd markdown-toc
cargo build --release
cargo install --path .
md-toc README.md

Usage

$ md-toc -h
    Usage: md-toc FILE [options]

      FILE        The Markdown file to parse for table of contents,
                  or "-" to read from stdin

    Options:
        -h, --help          print this help message
            --bullet {str}  Custom bullet of the ToC list. (default: "1.")
            --indent {int}  Indentation of the ToC list. (default: 4)
            --max-depth {int}
                            Max depth of headers to include.
            --min-depth {int}
                            Min depth of headers to include. (default: 0)
            --header {str}  Custom header of the ToC. (default: "## Table of
                            Contents")
            --no-link       Exclude links in ToC
            --no-header     Exclude the header of ToC

Generating basic ToC

md-toc README.md

Output:

## Table of Contents

1. [markdown-toc](#markdown-toc)
    1. [Table of Contents](#table-of-contents)
    1. [Installation](#installation)
        1. [Run in Docker](#run-in-docker)
        1. [Install with cargo](#install-with-cargo)
        1. [Build yourself](#build-yourself)
    1. [Usage](#usage)
        1. [Generating basic ToC](#generating-basic-toc)
        1. [Customizing bullets](#customizing-bullets)
        1. [Limiting the depth of headers](#limiting-the-depth-of-headers)
        1. [Excluding links](#excluding-links)
        1. [Customizing header of ToC](#customizing-header-of-toc)
            1. [Excluding header](#excluding-header)

Customizing bullets

md-toc README.md --bullet "-" --indent 2

Output:

## Table of Contents

- [markdown-toc](#markdown-toc)
- [Table of Contents](#table-of-contents)
- [Installation](#installation)
    - [Run in Docker](#run-in-docker)
    - [Install with cargo](#install-with-cargo)
    - [Build yourself](#build-yourself)
- [Usage](#usage)
    - [Generating basic ToC](#generating-basic-toc)
    - [Customizing bullets](#customizing-bullets)
    - [Limiting the depth of headers](#limiting-the-depth-of-headers)
    - [Excluding links](#excluding-links)
    - [Customizing header of ToC](#customizing-header-of-toc)
    - [Excluding header](#excluding-header)

Limiting the depth of headers

md-toc README.md --min-depth 1 --max-depth 2

Output:

## Table of Contents

1. [Table of Contents](#table-of-contents)
1. [Installation](#installation)
    1. [Run in Docker](#run-in-docker)
    1. [Install with cargo](#install-with-cargo)
    1. [Build yourself](#build-yourself)
1. [Usage](#usage)
    1. [Generating basic ToC](#generating-basic-toc)
    1. [Customizing bullets](#customizing-bullets)
    1. [Limiting the depth of headers](#limiting-the-depth-of-headers)
    1. [Excluding links](#excluding-links)
    1. [Customizing header of ToC](#customizing-header-of-toc)

Excluding links

md-toc README.md --no-link

Output:

## Table of Contents

1. markdown-toc
    1. Table of Contents
    1. Installation
        1. Run in Docker
        1. Install with cargo
        1. Build yourself
    1. Usage
        1. Generating basic ToC
        1. Customizing bullets
        1. Limiting the depth of headers
        1. Excluding links
        1. Customizing header of ToC
            1. Excluding header

Customizing header of ToC

md-toc README.md --header "# ToC"

Output:

# ToC

1. [markdown-toc](#markdown-toc)
    1. [Table of Contents](#table-of-contents)
    1. [Installation](#installation)
        1. [Run in Docker](#run-in-docker)
        1. [Install with cargo](#install-with-cargo)
        1. [Build yourself](#build-yourself)
    1. [Usage](#usage)
        1. [Generating basic ToC](#generating-basic-toc)
        1. [Customizing bullets](#customizing-bullets)
        1. [Limiting the depth of headers](#limiting-the-depth-of-headers)
        1. [Excluding links](#excluding-links)
        1. [Customizing header of ToC](#customizing-header-of-toc)
            1. [Excluding header](#excluding-header)

Excluding header

md-toc README.md --no-header

Output:

1. [markdown-toc](#markdown-toc)
    1. [Table of Contents](#table-of-contents)
    1. [Installation](#installation)
        1. [Run in Docker](#run-in-docker)
        1. [Install with cargo](#install-with-cargo)
        1. [Build yourself](#build-yourself)
    1. [Usage](#usage)
        1. [Generating basic ToC](#generating-basic-toc)
        1. [Customizing bullets](#customizing-bullets)
        1. [Limiting the depth of headers](#limiting-the-depth-of-headers)
        1. [Excluding links](#excluding-links)
        1. [Customizing header of ToC](#customizing-header-of-toc)
            1. [Excluding header](#excluding-header)