toc4github

• Install
• Usage
• Showcase

The toc4github is a very tiny tool to automatically generate Table of Contents (TOC) for Markdown file, especially for README.md in Github.com. It might also be used for other markdown rendering system, but I never tested! :)

Install

$ pip install toc4github
$ python -m toc4github -h  # inline help

Usage

You should insert a placeholder which is {toc} in README.md. The placeholder ocuppies a whole line. Then:

$ python -m toc4github [-d] [-t TITLE] <path/to/README.md>

Now, the placeholder is replaced by TOC generated with an optional title, and your markdown file is updated.

Or, you can call make_toc interface in your python code. It returns the TOC as string in accordance with input, and you can do anything you want with it.

# how to import
from toc4github import make_toc
# signature
make_toc(lines: Iterable[str]|str) -> str

Showcase

In addition, All my repos' TOC are generated by toc4github. Have fun ... ^___^