Skip to content
A Python command line tool that creates a Table of Contents for Markdown documents
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
example_markdown header-strip fix Aug 21, 2015
images header-strip fix Aug 21, 2015
markdown_toclify Increment minor version Nov 5, 2017
tests Refactor test_markdown_std Nov 5, 2017
.gitignore removed tmp files Jun 8, 2014
CHANGELOG.txt header-strip fix Aug 21, 2015 contributing Jan 26, 2015
LICENSE Initial commit Jun 8, 2014 README - fixes markown typo Jul 8, 2018 Increment minor version Nov 5, 2017

markdown-toclify is a Python command line script that adds a Table of Contents with internal section-links to Markdown documents.

This project is hosted at:

Compatible to CommonMark (formerly known as Common Markdown).

Sebastian Raschka 2014-2015



[back to top]

You can simply copy the stand_alone script ./markdown_toclify/ to a local directory on your computer and use it from there.

The basic usage is quite simple, you just need to provide a Markdown-formatted input file and the modified Markdown contents will be printed to the standard output screen.


Command line arguments

[back to top]

positional arguments:              path to the Markdown input file

optional arguments:
  -h, --help            show this help message and exit
  -o, --output
                        path to the Markdown output file
  -b, --back_to_top     add [back to top] links.
  -g, --github          omits id-anchor tags (recommended for GitHub)
  -s pixels, --spacer pixels
                        add horizontal space (in pixels) after the table of contents
  -n, --nolink          create the table of contents without internal links
  -e EXCLUDE_H, --exclude_h EXCLUDE_H
                        exclude eading levels, e.g., "2,3" to exclude all level 2 and 3 headings
  --placeholder PLACEHOLDER
                        inserts TOC at the placeholder string instead of inserting it on top of the document
  --no_toc_header       suppresses the Table of Contents header
  --remove_dashes       Removes dashes from generated slugs
  -v, --version         show program's version number and exit

Using the Python module

[back to top]

Alternatively, markdown_toclify can be installed via pip

pip install markdown_toclify

and used from the command line as

python -m markdown_toclify -h

Furthermore, markdown_toclify can also be imported as module and be used within Python. For example,

from markdown_toclify import markdown_toclify
cont = markdown_toclify(input_file='/Users/sebastian/Desktop/')

The markdown_toclify module has the same functionality as the command line tool. For more information about the usage, please refer to the help function via


#Examples [back to top]

Basic usage

Input file

[back to top]

Input file

Simple output file

[back to top]


./ -o

Output file 1

Advanced options

Output file with back-to-top links and vertical space

[back to top]


./ -o -b -s 100

Output file 2

Heading level exclusion

[back to top]


./ -o --exclude_h 2,3

Output file 3

TOC insertion at a placeholder position

[back to top]


./ -o --placeholder ??placeholder??


Input file 3


Output file 4

You can’t perform that action at this time.