为 github markdown 文件生成目录(toc)

缘起

有需求，才有创作。

每次写 github 上的 README.md，内容较多时阅读不方便，也没有自动生成的 TOC(目录)。于是就自己写了一个。

markdown-toc

markdown-toc

可以根据 atx(# 指定标题) 标题形式的 markdown 文件生成对应目录。

效果展示

Before

After

markdown-toc

markdown-toc 可以用来生成 markdown 页面的目录，便于 github 页面展现。

Features

• Github Markdown 文件一键生成目录

• 支持 fluent 优雅的写法

• 支持多次生成

• 支持重复标题的生成

• 支持特殊字符的过滤

• 支持指定不同的文件编码

• 支持文件夹的文件批量处理(可指定是否包含子文件夹文件)

• 支持是否写入文件，可返回目录的内容，便于用户自行处理

• …

环境依赖

JDK

JDK7+, 请确保 JDK 设置正确。

Maven

Jar 使用 Maven 进行统一管理。

快速入门

maven 引入

<dependency>
    <groupId>com.github.houbb</groupId>
    <artifactId>markdown-toc</artifactId>
    <version>1.0.2</version>
</dependency>

md 文件

本项目支持的 md 文件后缀名称为 .md 或者 .markdown

快速开始

• 单个文件

AtxMarkdownToc.newInstance().genTocFile(path);

其中 path 为 md 文件的路径

• 指定文件夹

AtxMarkdownToc.newInstance().genTocFile(path);

其中 path 为 md 文件的父类文件夹

属性配置

• 代码示例

AtxMarkdownToc.newInstance()
                .charset("UTF-8")
                .write(true)
                .subTree(true);

属性说明

序号	属性	默认值	说明
1	charset	UTF-8	文件编码
2	write	true	是否将 toc 写入文件(默认写入)
3	subTree	true	是否包含子文件夹的文件(默认包含)

返回值说明

genTocFile() 返回 TocGen，genTocDir() 返回 List

• TocGen 属性说明

序号	属性	类型	说明
1	filePath	String	当前 md 的文件路径
2	tocLines	List	当前 md 文件对应的目录内容

测试案例

单个文件-目录生成测试案例

文件夹-目录生成测试案例

github 地址

markdown-toc