gfm-toc

中文文档 | README

目录

• 概述
• 安装
• 使用
  • 单个文件
  • 多个文件
  • 配置
    • 自定义标题级别
    • 将结果写入文件或打印到标准输出
    • 为生成的目录添加标题
• 依赖
• 许可证

概述

一种简单且可定制的在GitHub的README.md中生成目录的方法。

• 根据GitHub受欢迎的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 文件生成 目录 并将结果打印到标准输出，只包含 2-4 级标题

$ gfm-toc -s 2 -e 4 -o README_eng.md
Generate from file: README_eng.md

- [Table of Contents](#table-of-contents)
- [md-toc](#md-toc)
- [Installation](#installation)
- [Usage](#usage)
  - [Single file](#single-file)
  - [Multiple files](#multiple-files)
  - [Configuration](#configuration)
    - [customize  the title level](#customize--the-title-level)
    - [Write results to a file or print to standard output](#write-results-to-a-file-or-print-to-standard-output)
- [Dependency](#dependency)

Table of contents generated.

然后，将结果从控制台提示句子中复制/粘贴到原始 README.md 中。

多个文件

使用默认配置为多个 Markdown 文件生成 目录 并分别写入文件

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

以下是一个示例：

• 没有目录的文件.md

生成目录并写入文件后：

• 有目录的文件.md

配置

自定义标题级别

使用命令行选项 -s 或 --start 并添加参数来设置目录的起始标题级别。参数的默认值为 1。

使用命令行选项 -e 或 --end 并添加参数来设置目录的结束标题级别。参数的默认值为 6。

标题级别参数必须是介于 1 和 6 之间的整数，且起始标题级别不能大于结束标题级别。

-s {1,2,3,4,5,6}, --start {1,2,3,4,5,6}  choose the start level of TOC, default value is 1
-e {1,2,3,4,5,6}, --end {1,2,3,4,5,6}  choose the end level of TOC, default value is 6

生成 1-6 级标题的目录（默认选项）

$ gfm-toc test/Mastering_Markdown.md -o
Generate from file: test/Mastering_Markdown.md

- [Mastering Markdown](#mastering-markdown)
  - [What is Markdown?](#what-is-markdown)
  - [Examples](#examples)
  - [Syntax guide](#syntax-guide)
    - [Headers](#headers)
    - [Emphasis](#emphasis)
    - [Lists](#lists)
      - [Unordered](#unordered)
      - [Ordered](#ordered)
    - [Images](#images)
    - [Links](#links)
    - [Blockquotes](#blockquotes)
    - [Inline code](#inline-code)

Table of contents generated.

只生成 2-3 级标题

$ gfm-toc examples/Mastering_Markdown.md -o -s 2 -e 3
Generate from file: examples/Mastering_Markdown.md

- [What is Markdown?](#what-is-markdown)
- [Examples](#examples)
- [Syntax guide](#syntax-guide)
  - [Headers](#headers)
  - [Emphasis](#emphasis)
  - [Lists](#lists)
  - [Images](#images)
  - [Links](#links)
  - [Blockquotes](#blockquotes)
  - [Inline code](#inline-code)

Table of contents generated.

将结果写入文件或打印到标准输出

默认情况下，程序会自动将生成的目录写入原始文件的开始处。

当您想要将结果打印到标准输出进行复制或其他处理时，请添加选项 -o 或 --output。

-o, --output          print toc to stdout instead of writing to file

在命令行中使用 > 将生成的目录导出到单独的文件中

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

为生成的目录添加标题

此选项并不常见，因为在许多情况下，人们根据不同的规范或自己的习惯编写 Markdown 文档。但如果有需要，在执行命令时可以添加 -t 或 --title 选项。这将向生成的目录中添加一个 2 级标题，称为 目录，如下所示

$ gfm-toc examples/Mastering_Markdown.md -o -s 2 -e 3 -t
Generate from file: examples/Mastering_Markdown.md

## Table of contents

- [What is Markdown?](#what-is-markdown)
- [Examples](#examples)
- [Syntax guide](#syntax-guide)
  - [Headers](#headers)
  - [Emphasis](#emphasis)
  - [Lists](#lists)
  - [Images](#images)
  - [Links](#links)
  - [Blockquotes](#blockquotes)
  - [Inline code](#inline-code)

Table of contents generated.

依赖

• Python3

在 Ubuntu 18.04 的 bash 中使用 Python 3.6.7 进行了测试。

许可证

MIT