為 github markdown 檔案生成目錄(toc)

葉止水發表於2018-07-12
Github

業務需要

在編寫 github 專案時，有時候會編寫各種 README.md 等 markdown 檔案，但是 github 預設是沒有目錄的。

於是就自己寫了一個小工具。

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

相關文章