分享一个为Github Markdown文档自动生成目录（toc）的扩展

分享
,
1

最近在整理Github上的项目时发现上传后的markdown文档居然不支持用 [TOC] 自动生成目录！

对于内容较多的文档使用目录进行总览和页内跳转是非常有必要的，找了几个自动生成toc的工具发现并不好用（有些还不支持中文），所以自己写了一个简单的扩展，添加了一些常用的功能，还上传到了Pypi，论坛的朋友们如果有这个需求可以试试:grinning:

Github：gfm-toc:简单、可自定义的方式为 Github Markdown 文件自动生成目录。

扩展的简单介绍如下（详细内容可查看项目的中文README）：

gfm-toc

简单且可自定义的方式为 Github Markdown 文档自动生成目录。

  • 遵照 Github Favored Markdown 格式自动生成目录
  • 单个.py文件即可运行，无其他依赖
  • 支持中文与英文语言的文本内容
  • 支持自定义生成目录的标题级别
  • 支持自动将结果写入文件，也可打印结果到标准输出自行处理
  • 支持同时为多个文件生成目录
  • 支持重复标题、过滤代码块中的标题

安装

Pypi

$ pip3 install gfm-toc --upgrade

手动安装

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

也可直接下载仓库目录中的gfm_toc/md_toc.py文件并像下面这样手动运行脚本：

$ python3 md_toc.py [-h] [-s {1,2,3,4,5,6}] [-e {1,2,3,4,5,6}] [-o] file [file ...]

使用

命令格式如下：

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

以如下方式运行命令可获取命令选项的帮助信息（可将-h替换成--help）：

$ gfm-toc -h

注意：使用前请确保你的设备已经成功安装了 Python3。

单个文件

为单个 markdown 文件自动生成目录并打印到标准输出，目录中仅包含1-3级标题：

$ gfm-toc -s 1 -e 3 -o README.md
Generate from file: README.md

- [目录](#目录)
- [md-toc](#md-toc)
- [安装](#安装)
- [使用](#使用)
  - [单个文件](#单个文件)
  - [多个文件](#多个文件)
  - [配置](#配置)
    - [自定义目录的标题级别](#自定义目录的标题级别)
    - [将结果写入到文件或打印到标准输出](#将结果写入到文件或打印到标准输出)
- [环境依赖](#环境依赖)
- [版权许可](#版权许可)

Table of contents generated.

然后将命令提示语句之间的结果从终端复制粘贴到原来的 README.md 文件中。

多个文件

使用默认配置为多个md文件自动生成目录并分别写入到文件中：

$ gfm-toc file01.md file02.md file03.md
Table of contents generated.

原文件示例：

自动生成目录并写入到文件后：

2 个赞