Simplify Your GitHub README.md With gfm-toc

Simplify Your GitHub README.md With gfm-toc

Are you tired of scrolling through lengthy README.md files on GitHub repositories? Do you wish there was a way to quickly jump to the section you’re interested in? Look no further! In this article, we’ll explore a simple and customizable tool called gfm-toc that generates a table of contents for your README.md file, making it easier for readers to navigate and understand your documentation.

Overview

The gfm-toc tool is an easy and customizable way to generate a table of contents for your README.md file on GitHub. It automates the process of creating a TOC in accordance with GitHub Favored Markdown format. With just a single .py file, you can generate a TOC with no other dependencies. The tool supports text content in both Chinese and English languages, allows customization of the header level, and provides options to write the results to a file or print them to standard output. It also supports generating a TOC for multiple files simultaneously and handles repeating headers and filtering headers in code blocks.

Installation

To install gfm-toc, you have two options. The first option is to use Pypi:

bash
$ pip3 install gfm-toc --upgrade

Alternatively, you can manually download the gfm_toc/md_toc.py file from the GitHub repository and run it manually. Follow these steps:

bash
$ git clone https://github.com/waynerv/github-markdown-toc
$ cd github-markdown-toc
$ python3 setup.py install

Usage

The command syntax for gfm-toc is as follows:

bash
$ gfm-toc [-h] [-s {1,2,3,4,5,6}] [-e {1,2,3,4,5,6}] [-o] file [file ...]

To get help information for the command options, run the following command:

bash
$ gfm-toc -h

Single file

To automatically generate a TOC for a single markdown file and print the result to standard output, use the following command:

bash
$ gfm-toc -s 2 -e 4 -o README_eng.md

Copy the resulting TOC from the console and paste it between the prompt sentences in your original README.md file.

Multiple files

To generate a TOC for multiple markdown files with the default configuration and write them to separate files, use this command:

bash
$ gfm-toc file01.md file02.md file03.md

The tool will generate a TOC for each file and write it to a new file with “_with_TOC” added to the filename.

Configuration

gfm-toc provides several configuration options to customize the generated TOC according to your requirements.

Customize the header level

You can use the command line options -s or --start and -e or --end to set the start and end header levels of the TOC. The default value is 1 for the start level and 6 for the end level. For example:

bash
$ gfm-toc examples/Mastering_Markdown.md -o -s 2 -e 3

This command will generate a TOC that includes headers from level 2 to level 3 only.

Write results to a file or print to standard output

By default, gfm-toc automatically writes the generated TOC to the beginning of the original file. However, you can use the -o or --output option to print the results to standard output instead of writing them to a file. For example:

bash
$ gfm-toc -o README.md > table_of_content.md

This command will print the generated TOC to the console, allowing you to copy it and paste it wherever you need.

Add a title to the generated TOC

If you want to add a title to the generated TOC, you can use the -t or --title option. This will add a level 2 header called “Table of Contents” to the output. For example:

bash
$ gfm-toc examples/Mastering_Markdown.md -o -s 2 -e 3 -t

This command will generate a TOC with a “Table of Contents” header at the beginning.

Dependency

The gfm-toc tool requires Python3 to run. Make sure your device has Python3 installed before using it. The tool has been tested on Ubuntu 18.04 with Python 3.6.7.

Conclusion

With the gfm-toc tool, you can easily generate a table of contents for your GitHub README.md file. By improving the navigation and organization of your documentation, you can enhance the reading experience for your users. Try out gfm-toc today and simplify your GitHub repositories!

License

The gfm-toc tool is licensed under the MIT License.

Source: GitHub Repository