markdown-toc

Generating your Markdown Table of Contents

markdown-toc is a small application written in Go that helps you generate a Table of Contents (ToC) for your Markdown file. There are already a number of scripts etc doing this, but I failed to find one that suited my needs.

In short the features of markdown-toc are:

• Cross platform (OS X, Linux, Windows)
• Replacement of an existing ToC
  • The new file can be written to stdout or overwritten on disk
• Able to skip n number of initial headers
• Configurable depth of headers to include
• Customizable header for the table of contents

Please star the project if you like it!

Table of Contents

1. Table of Contents
2. Installation
   1. Running it in Docker
   2. Building it yourself
3. Example usage
   1. Generating a ToC to stdout
   2. Controlling depth of headers
   3. Set a custom header
   4. Render the ToC without a header
   5. Skip n headers
   6. Print the full Markdown file, not only the ToC
   7. Inject the ToC into a file on disk
4. Helping out!
   1. Running the test suite
   2. Build locally with build flags
5. Releasing new versions
6. Contributors
7. License

Installation

Running it in Docker

The project has a Docker image that you can use easily:

docker run -v $(pwd)":/app" -w /app --rm -it sebdah/markdown-toc README.md

The above will mount your current directory into the Docker container. Just modify the -v flag according to your needs if you need to modify some other folder.

markdown-toc is the ENTRYPOINT in the Dockerfile, which means that it's the default command.

Building it yourself

Currently the easiest way is to clone the repository and run:

make install

You will end up having a binary called markdown-toc in your system afterwards.

Example usage

Generating a ToC to stdout

Command:

markdown-toc README.md

Output:

<!-- ToC start -->
# Table of Contents

- [`markdown-toc` - Generate your Table of Contents](#`markdown-toc`---generate-your-table-of-contents)
- [Example usage](#example-usage)
  - [Generating a ToC to `stdout`](#generating-a-toc-to-`stdout`)
- [License](#license)
<!-- ToC end -->

Controlling depth of headers

Using the --depth flag you can control how many labels of headers to include in the output. If the --depth is set to 1, only level 1 headers are included. Set this value to 0 (default) to include any depth of headers.

Command:

markdown-toc --depth 1 README.md

Output:

<!-- ToC start -->
# Table of Contents

- [`markdown-toc` - Generate your Table of Contents](#`markdown-toc`---generate-your-table-of-contents)
- [Example usage](#example-usage)
- [License](#license)
<!-- ToC end -->

Set a custom header

By default we print a header like # Table of Contents above the table of contents. You can change the header to suit your project using the --header flag.

Command:

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

Output:

<!-- ToC start -->
# ToC

- [`markdown-toc` - Generate your Table of Contents](#`markdown-toc`---generate-your-table-of-contents)
- [Example usage](#example-usage)
  - [Generating a ToC to `stdout`](#generating-a-toc-to-`stdout`)
- [License](#license)
<!-- ToC end -->

Render the ToC without a header

By default we print a header like # Table of Contents above the table of contents. You can remove the header by providing --no-header to the command.

Command:

markdown-toc --no-header README.md

Output:

<!-- ToC start -->
- [`markdown-toc` - Generate your Table of Contents](#`markdown-toc`---generate-your-table-of-contents)
- [Example usage](#example-usage)
  - [Generating a ToC to `stdout`](#generating-a-toc-to-`stdout`)
- [License](#license)
<!-- ToC end -->

Skip n headers

If you do not want to include n number of initial headers in your ToC, you can use the --skip-headers=1 flag. This is useful if you have your project name as the first header and you don't really want that in the ToC for example.

Command:

markdown-toc --skip-headers=1 README.md

Output:

<!-- ToC start -->
- [Example usage](#example-usage)
  - [Generating a ToC to `stdout`](#generating-a-toc-to-`stdout`)
- [License](#license)
<!-- ToC end -->

Print the full Markdown file, not only the ToC

markdown-toc --replace README.md

This will print the full Markdown of README.md and a table of contents section will be injected into the Markdown based on the following rules:

• If no ToC was found, the ToC will be injected on top of the file
• If a section starting with <!-- ToC start --> and ending with <!-- ToC end --> is found, it will be replaced with the new ToC.

Inject the ToC into a file on disk

markdown-toc --replace --inline README.md

This will overwrite the README.md file on disk with the full Markdown of README.md and a table of contents section will be injected into the Markdown based on the following rules:

• If no ToC was found, the ToC will be injected on top of the file
• If a section starting with <!-- ToC start --> and ending with <!-- ToC end --> is found, it will be replaced with the new ToC.

Helping out!

There are many ways to help out with this project. Here are a few:

• Answer questions here
• Enhance the documentation
• Spread the good word on Twitter or similar places
• Implement awesome features. Some of the suggested features can be found here

Running the test suite

make test

Build locally with build flags

make build

Releasing new versions

From the master branch run make release. You will need to have access to pushing to the GitHub project as well as Docker Hub.

Contributors

• Sebastian Dahlgren (maintainer)

License

MIT license