Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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
- Host: GitHub
- URL: https://github.com/rasbt/markdown-toclify
- Owner: rasbt
- License: gpl-3.0
- Created: 2014-06-08T16:23:49.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2018-07-13T02:23:51.000Z (over 6 years ago)
- Last Synced: 2024-11-07T16:13:31.191Z (about 1 month ago)
- Language: Python
- Homepage:
- Size: 3.38 MB
- Stars: 92
- Watchers: 6
- Forks: 42
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.txt
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- starred-awesome - markdown-toclify - A Python command line tool that creates a Table of Contents for Markdown documents (Python)
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 fileoptional 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)