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: 3 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-10-23T09:21:52.355Z (12 days 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 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)