为github标记文件生成toc的简单且可定制的方法。
gfm-toc的Python项目详细描述
gfm总有机碳
目录
概述
Github上readme.md的generate toc的简单且可定制的方式。
- 根据Github偏好的降价格式自动生成目录
- 只需一个.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。
单个文件
自动为单个标记文件生成toc,并将结果打印到标准输出,只有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中。
多个文件
使用默认配置为多个标记文件生成toc,并将它们分别写入一个文件:
$ gfm-toc file01.md file02.md file03.md Table of contents generated.
下面是一个示例:
生成toc并写入文件后:
配置
自定义标题级别
使用命令行选项-s
或--start
并添加参数以设置toc的起始头级别。参数的默认值为1。
使用命令行选项-e
或--end
并添加参数以设置toc的结束头级别。参数的默认值是6。
title level参数必须是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个标题级别的toc(默认选项):
$ 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.
将结果写入文件或打印到标准输出
默认情况下,程序会自动将生成的toc写入原始文件的开头。
如果要将结果打印到标准输出以进行复制或其他处理,请添加选项-o
或--output
。
-o, --output print toc to stdout instead of writing to file
使用命令行上的>
将生成的目录导出到单独的文件:
$ gfm-toc -o README.md > table_of_content.md
为生成的目录添加标题
这个选项并不常见,因为在许多情况下,人们根据不同的规范或自己的习惯来编写标记文档。但如果需要,可以在执行命令时添加-t
或--title
选项。这将向生成的toc中添加一个名为Table of contens
的级别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
用python 3.6.7在bash的ubuntu 18.04上测试。
许可证
麻省理工学院