生成 GitHub README.md 目录

作者：: truesnow
发布于：: 7年前
收录于：: 实用教程分享
: 5091 0

摘要：[TOC] 在创建 GitHub 项目时，想要给 README.md 文档加上目录，本以为直接使用 `[TOC]` 可以自动生成目录，跟其它的 Markdown 编辑器一样，但是发现 GitHub 并不支持。搜索了一下相关的问题，分享一下。 # GFM...

[TOC]

在创建 GitHub 项目时，想要给 README.md 文档加上目录，本以为直接使用 `[TOC]` 可以自动生成目录，跟其它的 Markdown 编辑器一样，但是发现 GitHub 并不支持。搜索了一下相关的问题，分享一下。

# GFM

GitHub 使用的 Markdown 是 Github Flavored Markdown，简称 GFM，参考 GitHub 官方的 [GitHub Flavored Markdown Spec](https://github.github.com/gfm/ )，Markdown 的目录使用页面内 Anchor 锚点跳转。格式如下：

```
  * [标题1](#标题1)
  * [标题2](#标题2)
  * [标题3](#标题3)
        * [标题3.1](#标题3.1)
        * [标题3.2](#标题3.2)
  * [标题4](#标题4)

```

遗憾的是 GitHub 没有自动生成目录的功能，于是找到一个开源的生成 GFM 目录的工具：[ekalinin/github-markdown-toc](https://github.com/ekalinin/github-markdown-toc ) ，使用起来简单方便，只是结合使用情况来看，速度（性能）上有些慢。使用方法见该项目的 GitHub 主页。下面简单介绍一下。

# gh-md-toc 使用

`gh-md-toc` 支持以下几种方式来生成 GFM TOC：

- stdin （标准输入，使用管道符处理）

- 本地文件

- 远程文件（支持通过 GitHub HTML 文件 URL 处理）

`gh-md-toc` 项目在 Ubuntu 和 macOS 上测试过。如果要在 Windows 上使用，使用基于 golang 的实现：[github-markdown-toc.go](https://github.com/ekalinin/github-markdown-toc.go )。而且很重要的一点是，它不需要安装额外的依赖。

## 安装

```
$ wget https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc
$ chmod a+x gh-md-toc

```

## 使用

### STDIN

示例：

```
➥ cat ~/projects/Dockerfile.vim/README.md | ./gh-md-toc -
  * [Dockerfile.vim](#dockerfilevim)
  * [Screenshot](#screenshot)
  * [Installation](#installation)
        * [OR using Pathogen:](#or-using-pathogen)
        * [OR using Vundle:](#or-using-vundle)
  * [License](#license)

```

### 本地文件

示例：

```
➥ ./gh-md-toc ~/projects/Dockerfile.vim/README.md Вс. марта 22 22:51:46 MSK 2015
Table of Contents
=================
  * [Dockerfile.vim](#dockerfilevim)
  * [Screenshot](#screenshot)
  * [Installation](#installation)
        * [OR using Pathogen:](#or-using-pathogen)
        * [OR using Vundle:](#or-using-vundle)
  * [License](#license)

```

### 远程文件

示例文件：[README.md without TOC](https://github.com/ekalinin/envirius/blob/f939d3b6882bfb6ecb28ef7b6e62862f934ba945/README.md )

```
➥ ./gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md
Table of Contents
=================
  * [envirius](#envirius)
    * [Idea](#idea)
    * [Features](#features)
  * [Installation](#installation)
  * [Uninstallation](#uninstallation)
  * [Available plugins](#available-plugins)
  * [Usage](#usage)
    * [Check available plugins](#check-available-plugins)
    * [Check available versions for each plugin](#check-available-versions-for-each-plugin)
    * [Create an environment](#create-an-environment)
    * [Activate/deactivate environment](#activatedeactivate-environment)
      * [Activating in a new shell](#activating-in-a-new-shell)
      * [Activating in the same shell](#activating-in-the-same-shell)
    * [Get list of environments](#get-list-of-environments)
    * [Get current activated environment](#get-current-activated-environment)
    * [Do something in environment without enabling it](#do-something-in-environment-without-enabling-it)
    * [Get help](#get-help)
    * [Get help for a command](#get-help-for-a-command)
  * [How to add a plugin?](#how-to-add-a-plugin)
    * [Mandatory elements](#mandatory-elements)
      * [plug_list_versions](#plug_list_versions)
      * [plug_url_for_download](#plug_url_for_download)
      * [plug_build](#plug_build)
    * [Optional elements](#optional-elements)
      * [Variables](#variables)
      * [Functions](#functions)
    * [Examples](#examples)
  * [Example of the usage](#example-of-the-usage)
  * [Dependencies](#dependencies)
  * [Supported OS](#supported-os)
  * [Tests](#tests)
  * [Version History](#version-history)
  * [License](#license)
  * [README in another language](#readme-in-another-language)

```

你要做的就是将生成的 TOC 拷贝到你的 *README.md* 文件中。结果：[README.md with TOC](https://github.com/ekalinin/envirius/blob/24ea3be0d3cc03f4235fa4879bb33dc122d0ae29/README.md )

也支持 GitHub wiki 页面：

```
➥ ./gh-md-toc https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv
Table of Contents
=================
  * [Who Uses Nodeenv?](#who-uses-nodeenv)
    * [OpenStack](#openstack)
    * [pre-commit.com](#pre-commitcom)

```

多个文件：

```
➥ ./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)
  * [Control Flow](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)
    * [Loops](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#loops)
    * [For loops](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)
    * [Method call](https://github.com/aminb/rust-for-c/blob/master/control_flow/README.md#method-call)
  * [Primitive Types and Operators](https://github.com/aminb/rust-for-c/blob/master/primitive_types_and_operators/README.md#primitive-types-and-operators)
  * [Unique Pointers](https://github.com/aminb/rust-for-c/blob/master/unique_pointers/README.md#unique-pointers)

```

也可以混合使用以上几种方式：

```
➥ ./gh-md-toc \
    ~/projects/Dockerfile.vim/README.md \
    https://github.com/ekalinin/sitemap.s/blob/master/README.md
  * [Dockerfile.vim](~/projects/Dockerfile.vim/README.md#dockerfilevim)
  * [Screenshot](~/projects/Dockerfile.vim/README.md#screenshot)
  * [Installation](~/projects/Dockerfile.vim/README.md#installation)
        * [OR using Pathogen:](~/projects/Dockerfile.vim/README.md#or-using-pathogen)
        * [OR using Vundle:](~/projects/Dockerfile.vim/README.md#or-using-vundle)
  * [License](~/projects/Dockerfile.vim/README.md#license)
  * [sitemap.js](https://github.com/ekalinin/sitemap.js/blob/master/README.md#sitemapjs)
    * [Installation](https://github.com/ekalinin/sitemap.js/blob/master/README.md#installation)
    * [Usage](https://github.com/ekalinin/sitemap.js/blob/master/README.md#usage)
    * [License](https://github.com/ekalinin/sitemap.js/blob/master/README.md#license)
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)

```

# 添加命令别名

为方便使用，可以为 `gh-md-toc` 命令设置别名。

命令行输入 `cd` 进入用户家目录，新建或编辑 *.bash_profile* 或 *.bashrc* 文件，添加以下内容：

```
cd 
vim ~/.bash_profile
```

```
alias ghtoc="~/git/gh-md-toc"

```

> 将 *~/git/gh-md-toc* 替换成你自己的路径。

保存退出，执行 `source ~/.bash_profile` 重载该文件，命令行输入 `alias` 可看到该别名。然后就可以直接使用 `ghtoc` 命令来生成 GitHub README.md 文件的目录了：

```
ghtoc ~/projects/README.md

```

# 在线使用

如果嫌下载使用麻烦的话，我今天把这个功能开发到自己的博客里了，你可以访问 [https://sleepeatcode.com/ghtoc](https://sleepeatcode.com/ghtoc ) 在线生成 GitHub README.md 目录了~欢迎使用拍砖~

# 参考

- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/ )

- [ekalinin/github-markdown-toc](https://github.com/ekalinin/github-markdown-toc )

- [在线生成 GitHub README.md 目录](https://sleepeatcode.com/ghtoc)

文章目录

生成 GitHub README.md 目录

所有评论（0）