Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/rasbt/markdown-toclify

A Python command line tool that creates a Table of Contents for Markdown documents
https://github.com/rasbt/markdown-toclify

Last synced: 29 days ago
JSON representation

A Python command line tool that creates a Table of Contents for Markdown documents

Awesome Lists containing this project

README

        

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](https://github.com/rasbt/markdown-toclify).

**Compatible to [CommonMark](http://commonmark.org) (formerly known as Common Markdown).**

Sebastian Raschka 2014-2015


- [Usage](#usage)
- [Command line arguments](#command-line-arguments)
- [Using the Python module](#useing-the-python-module)
- [Examples](#examples)
- [Basic usage](#basic-usage)
- [Input file](#input-file)
- [Simple output file](#simple-output-file)
- [Advanced options](#advanced-options)
- [Output file with back-to-top links and vertical space](#output-file-with-back-to-top-links-and-vertical-space)
- [Heading level exclusion](#output-file-with-back-to-top-links-and-vertical-space)
- [TOC insertion at a placeholder position](#toc-insertion-at-a-placeholder-position)


**Requires:**

- [Python 2.7.x or 3.x](https://www.python.org/downloads/)
- [argparse](https://pypi.python.org/pypi/argparse)


# Usage
[[back to top](#markdown-toclify)]

You can simply copy the stand_alone script [./markdown_toclify/markdown_toclify.py](./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](#markdown-toclify)]

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
--remove_dashes Removes dashes from generated slugs
-v, --version show program's version number and exit




## Using the Python module
[[back to top](#markdown-toclify)]

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](#markdown-toclify)]




## Basic usage


### Input file
[[back to top](#markdown-toclify)]

![Input file](./images/example_1.png)




### Simple output file
[[back to top](#markdown-toclify)]

Command:

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


![Output file 1](./images/example_2.png)




## Advanced options


### Output file with back-to-top links and vertical space
[[back to top](#markdown-toclify)]

Command:

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


![Output file 2](./images/example_3.png)




### Heading level exclusion
[[back to top](#markdown-toclify)]

Command:

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

![Output file 3](./images/example_4.png)




### TOC insertion at a placeholder position
[[back to top](#markdown-toclify)]

Command:

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

**Input**

![Input file 3](./images/example_5.png)

**Output**

![Output file 4](./images/example_6.png)