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]

positional arguments:
  input.md              path to the Markdown input file

optional arguments:
  -h, --help            show this help message and exit
  -o output.md, --output output.md
                        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
  -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 markown_toclify -h

Furthermore, markown_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