markdown-toclify

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

This project is hosted at: https://github.com/rasbt/markdown-toclify.

Compatible to CommonMark (formerly known as Common Markdown).

Sebastian Raschka 2014-2015

• Usage
  • Command line arguments
  • Using the Python module
• Examples
  • Basic usage
    • Input file
    • Simple output file
  • Advanced options
  • Output file with back-to-top links and vertical space
  • Heading level exclusion
  • TOC insertion at a placeholder position

Requires:

• Python 2.7.x or 3.x
• argparse

Usage

[back to top]

You can simply copy the stand_alone script ./markdown_toclify/markdown_toclify.py 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.

./markdown_toclify.py input.md

Command line arguments

[back to top]

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/test_input.md')

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

help(markdown_toclify)

#Examples [back to top]

Basic usage

Input file

[back to top]

Simple output file

[back to top]

Command:

./markdown_toclify.py input.md -o output.md

Advanced options

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

[back to top]

Command:

./markdown_toclify.py input.md -o output.md -b -s 100

Heading level exclusion

[back to top]

Command:

./markdown_toclify.py test_input_2.md -o test2_output.md --exclude_h 2,3

TOC insertion at a placeholder position

[back to top]

Command:

./markdown_toclify.py test_input_3.md -o test3_output.md --placeholder ??placeholder??

Input

Output