Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A Python command line tool that creates a Table of Contents for Markdown documents
Python
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
example_markdown
images header-strip fix
markdown_toclify
tests
.gitignore
CHANGELOG.txt
CONTRIBUTING.md
LICENSE
README.md
setup.py

README.md

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



Requires:


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]

Input file



Simple output file

[back to top]

Command:

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


Output file 1



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


Output file 2



Heading level exclusion

[back to top]

Command:

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

Output file 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

Input file 3

Output

Output file 4

Something went wrong with that request. Please try again.