實用帖 | 如何為 Markdown 文件自動生成目錄？

Foreword

在 Markdown：寫技術文檔、個人博客和讀書筆記都很好用的輕量級標記語言這篇文章中，給大家介紹了 Markdown 及其創始人的故事、Markdown 基本語法、常見的 Markdown 編輯器（Mac/Windows 平台和在線編輯器）。

新接觸 Markdown 的小夥伴建議先戳那篇文章去補充點能量，已熟悉 Markdown 的小夥伴可以速往下看。

在使用 Markdown 寫文檔時，有時需要給單個文檔生成目錄，比如包含多個問題的 FAQ (Frequently Asked Questions) 文檔。

那麼，如何為 Markdown 文件（即 .md 格式的文件）自動生成目錄呢？下面給大家介紹兩種方法：

• Visual Studio Code + Markdown TOC 擴展
• Pandoc 命令

1. Visual Studio Code + TOC 擴展

Visual Studio Code (VS Code) 是一個由微軟開發的，同時支持 Windows、Linux 和 macOS 操作系統的開源文本編輯器。它支持調試，內置了 Git 版本控制功能，同時也具有開發環境功能，例如代碼補全、代碼片段、代碼重構等。

如果你對 VS Code 的圖標感興趣，可以參考這篇文章：The Icon Journey

VS Code 編輯器支持用戶自定義配置，例如改變主題顏色、鍵盤快捷方式、編輯器屬性和其他參數。另外，還支持擴展程序，並在編輯器中內置了擴展程序管理的功能。

到底如何使用 VS Code + TOC 擴展為 Markdown 文件自動生成目錄呢？具體操作步驟如下：

1. 下載和安裝 Visual Studio Code。

下載地址：https://code.visualstudio.com/download

安裝成功後，雙擊圖標打開，顯示如下：

2. 單擊 VS Code 的擴展圖標，在搜索框搜索 Markdown TOC 並安裝。

此擴展長這樣：

安裝成功後，點擊左側擴展圖標，可查看已安裝的擴展。如下圖所示：

3. 點擊菜單欄的文件 -> 打開，打開需要生成目錄的 .md 格式的文件。

以如下 FAQ.md 文件為例：

FAQ.md 在 VS Code 中打開後顯示如下：

4. 將游標移至需要插入目錄的位置，右鍵單擊 Markdown TOC: Insert/Update [^M T]，目錄即自動插入。

顯示效果如下：

5. 單擊右上角的預覽圖標，可查看目錄的顯示效果。

顯示效果如下：

注：為保持文檔整潔，刪除目錄首尾的如下字元：

<!-- TOC -->n<!-- /TOC --> n

6. 保存，關閉文件。

2. Pandoc 命令

Pandoc 是由 John MacFarlane 開發的標記語言轉換工具，可實現不同標記語言間的格式轉換，堪稱該領域中的「瑞士軍刀」。Pandoc 使用 Haskell 語言編寫，以命令行形式實現與用戶的交互，可支持多種操作系統。

如何使用 pandoc 命令為 Markdown 文件自動生成目錄呢？仍以 FAQ.md 文件為例，具體操作步驟如下：

1. 下載和安裝 pandoc。

下載地址：https://github.com/jgm/pandoc/releases

關於安裝，可參考：https://pandoc.org/installing.html

2. 打開終端，輸入 pandoc --version 確認 pandoc 已成功安裝。

此命令返回結果如下圖所示：

3. 依次使用以下命令，轉到 FAQ.md 文件所在的目錄。

• pwd：查看查看當前目錄路徑，「printing working directory」 的縮寫。
• ls：查看目錄列表，「list segment」 的縮寫。
• cd：轉到某目錄下，是 「change directory」 的縮寫。

具體使用舉例：

或者，如果你清楚地知道文檔所在目錄，可以使用如下簡化的操作：

詳細的使用說明可參閱：https://pandoc.org/getting-started.html#step-3-changing-directories

4. 輸入以下命令，即可自動生成目錄。

pandoc -s --toc --toc-depth=4 FAQ.md -o FAQ.md n

注：pandoc 默認生成三級目錄。以上述命令為例，如果使用如下命令則只會生成三級目錄：

pandoc -s --toc FAQ.md -o FAQ.md n

而我想讓 FAQ.md 這篇文檔生成四級目錄，所以加了個參數 --toc-depth，並將其值設置為 4。大家可根據具體需求進行設置。

5. 打開 .md 文檔，查看目錄。

命令已成功為 FAQ.md 文件生成了目錄，顯示如下：

如果你想了解 pandoc 的更多功能和參數使用，可參考 pandoc 官網的文檔：https://pandoc.org/MANUAL.html

Afterword

以上兩種方法，我更常用的是 Visual Studio Code 中的 Markdown TOC 擴展，因為操作起來既方便又直觀。有需求的小夥伴趕快試一試吧！

你可能想讀：

有哪些適合技術傳播從業者關注的優質博客？

Markdown：寫技術文檔、個人博客和讀書筆記都很好用的輕量級標記語言

技術寫作實例解析 | 簡潔即是美

兩分鐘趣味解讀 Technical Writer

若脫離理解，直譯得再正確又有何意？

優質譯文不應止於正確，還要 Well-Organized

寫在入職技術型創業公司 PingCAP 一個月之後

-END-

推薦閱讀：