github-markdown-toc

这是基于 golang 实现的 github-markdown-toc 工具。

该实现的优点：

• 无依赖（不需要 curl、wget、awk 等）
• 跨平台（支持 Windows、Mac OS 等）
• 使用正则表达式解析目录
• 并行处理多个文档

注意：gh-md-toc 只有在您的机器连接到互联网时才能正常工作。

目录

• github-markdown-toc
• 安装
  • 预编译二进制文件
  • 从源码编译
  • Go 安装
  • Homebrew（仅限 Mac）
• 测试
• 使用方法
  • 标准输入
  • 本地文件
  • 远程文件
  • 多个文件
  • 组合使用
  • 起始深度
  • 深度
  • 不转义
  • GitHub 令牌
  • GitHub Enterprise Server
  • Bash/ZSH 自动补全
• Alpine Linux
• 许可证

由 gh-md-toc 创建

安装

预编译二进制文件

请查看发布页面的"下载"部分：

• https://github.com/ekalinin/github-markdown-toc.go/releases

例如：

$ wget https://github.com/ekalinin/github-markdown-toc.go/releases/download/1.1.0/gh-md-toc.linux.amd64.tgz
$ tar xzvf gh-md-toc.linux.amd64.tgz
gh-md-toc
$ ./gh-md-toc --version
1.1.0

从源码编译

您需要在操作系统中安装 golang：

$ make build
$ ./gh-md-toc --help
用法: gh-md-toc [<标志>] [<路径>...]

标志:
  --help           显示上下文相关帮助（也可以尝试 --help-long 和 --help-man）。
  --serial         以串行模式获取目录
  --hide-header    隐藏目录头部
  --hide-footer    隐藏目录尾部
  --start-depth=0  从此级别开始包含。默认为 0（包含所有级别）
  --depth=0        包含的标题级别数。默认为 0（全部）
  --no-escape      不转义章节中的字符
  --token=TOKEN    GitHub 个人令牌
  --indent=2       生成列表的缩进空格数
  --debug          显示调试信息
  --version        显示应用程序版本。

参数:
  [<路径>]  要获取目录的文档的本地路径或 URL。如果未输入，则从标准输入读取 MD。

Go 安装

您需要在操作系统中安装 golang：

go install "github.com/ekalinin/github-markdown-toc.go/cmd/gh-md-toc@latest"

Homebrew（仅限 Mac）

$ brew install github-markdown-toc

测试

$ make test
覆盖率: 28.8% 的语句
ok      _~/projects/my/github-toc.go    0.003s

使用方法

标准输入

以下是从标准输入为 markdown 创建目录的示例：

➥ cat ~/projects/Dockerfile.vim/README.md | ./gh-md-toc
  * [Dockerfile.vim](#dockerfilevim)
  * [截图](#截图)
  * [安装](#安装)
        * [或者使用 Pathogen:](#或者使用-pathogen)
        * [或者使用 Vundle:](#或者使用-vundle)
  * [许可证](#许可证)

本地文件

以下是为本地 README.md 创建目录的示例：

➥ ./gh-md-toc ~/projects/Dockerfile.vim/README.md                                                                                                                                                2015年3月22日 星期日 22:51:46 MSK

目录
=================

  * [Dockerfile.vim](#dockerfilevim)
  * [截图](#截图)
  * [安装](#安装)
        * [或者使用 Pathogen:](#或者使用-pathogen)
        * [或者使用 Vundle:](#或者使用-vundle)
  * [许可证](#许可证)

远程文件

这里有一个示例，当您有一个像这样的 README.md 时：

• 没有目录的 README.md 你想为它生成目录。

这再简单不过了:

➥ ./gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md

目录
==============

  * [envirius](#envirius)
    * [理念](#理念)
    * [特性](#特性)
  * [安装](#安装)
  * [卸载](#卸载)
  * [可用插件](#可用插件)
  * [使用方法](#使用方法)
    * [查看可用插件](#查看可用插件)
    * [查看每个插件的可用版本](#查看每个插件的可用版本)
    * [创建环境](#创建环境)
    * [激活/停用环境](#激活停用环境)
      * [在新的 shell 中激活](#在新的-shell-中激活)
      * [在同一 shell 中激活](#在同一-shell-中激活)
    * [获取环境列表](#获取环境列表)
    * [获取当前激活的环境](#获取当前激活的环境)
    * [在不启用环境的情况下在环境中执行操作](#在不启用环境的情况下在环境中执行操作)
    * [获取帮助](#获取帮助)
    * [获取某个命令的帮助](#获取某个命令的帮助)
  * [如何添加插件?](#如何添加插件)
    * [必需元素](#必需元素)
      * [plug_list_versions](#plug_list_versions)
      * [plug_url_for_download](#plug_url_for_download)
      * [plug_build](#plug_build)
    * [可选元素](#可选元素)
      * [变量](#变量)
      * [函数](#函数)
    * [示例](#示例)
  * [使用示例](#使用示例)
  * [依赖项](#依赖项)
  * [支持的操作系统](#支持的操作系统)
  * [测试](#测试)
  * [版本历史](#版本历史)
  * [许可证](#许可证)
  * [其他语言的README](#其他语言的readme)

就这么简单!现在你需要做的就是将控制台中的结果复制/粘贴到原始的 README.md 中。

这里是结果:

• 带有目录的 README.md

多个文件

它也支持多个文件:

➥ ./gh-md-toc \
    https://github.com/aminb/rust-for-c/blob/master/hello_world/README.md \
    https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md \
    https://github.com/aminb/rust-for-c/blob/master/primitive_types_and_operators/README.md \
    https://github.com/aminb/rust-for-c/blob/master/unique_pointers/README.md

  * [Hello world](https://github.com/aminb/rust-for-c/blob/master/hello_world/README.md#hello-world)

  * [控制流](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#control-flow)
    * [If](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#if)
    * [循环](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#loops)
    * [For 循环](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#for-loops)
    * [Switch/Match](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#switchmatch)
    * [方法调用](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#method-call)

  * [基本类型和运算符](https://github.com/aminb/rust-for-c/blob/master/primitive_types_and_operators/README.md#primitive-types-and-operators)

  * [唯一指针](https://github.com/aminb/rust-for-c/blob/master/unique_pointers/README.md#unique-pointers)

自 0.4.0 版本起，多文档处理采用并行模式。 你可以通过在控制台中传递 --serial 选项来使用(旧的)串行模式:

$ ./gh-md-toc --serial ...

时间对比:

➥ time (./gh-md-toc --serial README.md ../envirius/README.ru.md ../github-toc/README.md > /dev/null)

real    0m1.200s
user    0m0.040s
sys     0m0.004s

➥ time (./gh-md-toc README.md ../envirius/README.ru.md ../github-toc/README.md > /dev/null)

real    0m0.784s
user    0m0.036s
sys     0m0.004s

组合使用

你可以轻松地结合这两种方式:

➥ ./gh-md-toc \
    ~/projects/Dockerfile.vim/README.md \
    https://github.com/ekalinin/sitemap.s/blob/master/README.md

  * [Dockerfile.vim](https://github.com/ekalinin/github-markdown-toc.go/blob/master/~/projects/Dockerfile.vim/README.md#dockerfilevim
  * [截图](https://github.com/ekalinin/github-markdown-toc.go/blob/master/~/projects/Dockerfile.vim/README.md#screenshot
  * [安装](https://github.com/ekalinin/github-markdown-toc.go/blob/master/~/projects/Dockerfile.vim/README.md#installation
        * [或者使用 Pathogen:](https://github.com/ekalinin/github-markdown-toc.go/blob/master/~/projects/Dockerfile.vim/README.md#or-using-pathogen
        * [或者使用 Vundle:](https://github.com/ekalinin/github-markdown-toc.go/blob/master/~/projects/Dockerfile.vim/README.md#or-using-vundle
  * [许可证](https://github.com/ekalinin/github-markdown-toc.go/blob/master/~/projects/Dockerfile.vim/README.md#license

  * [sitemap.js](https://github.com/ekalinin/sitemap.js/blob/master/README.md#sitemapjs)
    * [安装](https://github.com/ekalinin/sitemap.js/blob/master/README.md#installation)
    * [使用方法](https://github.com/ekalinin/sitemap.js/blob/master/README.md#usage)
    * [许可证](https://github.com/ekalinin/sitemap.js/blob/master/README.md#license)
起始深度
--------------

使用 `--start-depth=INT` 来控制起始标题级别（即只包含从 `INT` 开始的级别）

```bash
➥ ./gh-md-toc --start-depth=1 ~/projects/Dockerfile.vim/README.md

目录
=================

  * [或者使用 Pathogen:](#或者使用-pathogen)
  * [或者使用 Vundle:](#或者使用-vundle)

由 [gh-md-toc](https://github.com/ekalinin/github-markdown-toc) 创建

深度

使用 --depth=INT 来控制在目录中包含多少级标题

➥ ./gh-md-toc --depth=1 ~/projects/Dockerfile.vim/README.md

目录
=================

  * [Dockerfile\.vim](#dockerfilevim)
  * [截图](#截图)
  * [安装](#安装)
  * [许可证](#许可证)

不转义

➥ ./gh-md-toc ~/projects/my/Dockerfile.vim/README.md | grep Docker
* [Dockerfile\.vim](#dockerfilevim)

➥ ./gh-md-toc --no-escape ~/projects/my/Dockerfile.vim/README.md | grep Docker
* [Dockerfile.vim](#dockerfilevim)

GitHub 令牌

所有令牌都在这里。

命令行参数示例：

➥ ./gh-md-toc --depth=1 --token=2a2dabe1f2c2399bd542ba93fe6ce70fe7898563 README.md

目录
=================

* [github\-markdown\-toc](#github-markdown-toc)
* [目录](#目录)
* [安装](#安装)
* [测试](#测试)
* [使用方法](#使用方法)
* [许可证](#许可证)

环境变量示例：

➥ GH_TOC_TOKEN=2a2dabe1f2c2399bd542ba93fe6ce70fe7898563 ./gh-md-toc --depth=1  README.md

目录
=================

* [github\-markdown\-toc](#github-markdown-toc)
* [目录](#目录)
* [安装](#安装)
* [测试](#测试)
* [使用方法](#使用方法)
* [许可证](#许可证)

GitHub 企业服务器

如果你使用的是 GitHub 企业服务器，可以覆盖 API 的默认 URL：

➥ GH_TOC_URL=https://api.github.mycompany.com ./gh-md-toc README.md

Bash/ZSH 自动补全

只需在你的 ~/.bashrc 或 ~/.zshrc 中添加一个简单的命令：

# 对于 zsh
eval "$(gh-md-toc --completion-script-zsh)"

# 对于 bash
eval "$(gh-md-toc --completion-script-bash)"

Alpine Linux

Alpine Linux 默认使用 musl 而不是 glibc。如果你安装 binutils 并运行...

apk add binutils && \
readelf -l /path/to/gh-md-toc

...你会看到它依赖 /lib64/ld-linux-x86-64.so.2 作为其解释器。你可以通过在下载 Linux amd64 构建的同时安装 libc6-compat 来解决这个问题。

apk add libc6-compat

许可证

请参阅 LICENSE 文件。