gh-md-toc
gh-md-toc — is for you if you want to generate TOC (Table Of Content) for a README.md ora GitHub wiki page without installing additional software.
It's my try to fix a problem:
gh-md-toc is able to process:
- stdin
- local files (markdown files in local file system)
- remote files (html files on github.com)
gh-md-toc tested on Ubuntu, and macOS High Sierra (gh-md-toc release 0.4.9). If you want it on Windows, youbetter to use a golang based implementation:
It's more solid, reliable and with ability of a parallel processing. Andabsolutely without dependencies.
Table of contents
Installation
Linux (manual installation)
$ wget https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc
$ chmod a+x gh-md-toc
MacOS (manual installation)
$ curl https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc -o gh-md-toc
$ chmod a+x gh-md-toc
Linux or MacOS (using Basher)
$ basher install ekalinin/github-markdown-toc
# `gh-md-toc` will automatically be available in the PATH
Usage
STDIN
Here's an example of TOC creating for markdown from 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)
Local files
Here's an example of TOC creating for a local README.md:
➥ ./gh-md-toc ~/projects/Dockerfile.vim/README.md
Table of Contents
=================
* [Dockerfile.vim](#dockerfilevim)
* [Screenshot](#screenshot)
* [Installation](#installation)
* [OR using Pathogen:](#or-using-pathogen)
* [OR using Vundle:](#or-using-vundle)
* [License](#license)
Remote files
And here's an example, when you have a README.md like this:
And you want to generate TOC for it.
There is nothing easier:
➥ ./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)
That's all! Now all you need — is copy/paste result from console into originalREADME.md.
If you do not want to copy from console you can add > YOURFILENAME.md at the end of the command like ./gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md > table-of-contents.md and this will store the table of contents to a file named table-of-contents.md in your current folder.
And here is a result:
Moreover, it's able to work with GitHub's wiki pages:
➥ ./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)
Multiple files
It supports multiple files as well:
➥ ./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)
Combo
You can easily combine both ways:
➥ ./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)
Auto insert and update TOC
Just put into a file these two lines:
<!--ts-->
<!--te-->
And run:
$ ./gh-md-toc --insert README.test.md
Table of Contents
=================
* [gh-md-toc](#gh-md-toc)
* [Installation](#installation)
* [Usage](#usage)
* [STDIN](#stdin)
* [Local files](#local-files)
* [Remote files](#remote-files)
* [Multiple files](#multiple-files)
* [Combo](#combo)
* [Tests](#tests)
* [Dependency](#dependency)
!! TOC was added into: 'README.test.md'
!! Origin version of the file: 'README.test.md.orig.2018-02-04_192655'
!! TOC added into a separate file: 'README.test.md.toc.2018-02-04_192655'
Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
Now check the same file:
➜ grep -A15 "<\!\-\-ts" README.test.md
<!--ts-->
* [gh-md-toc](#gh-md-toc)
* [Table of contents](#table-of-contents)
* [Installation](#installation)
* [Usage](#usage)
* [STDIN](#stdin)
* [Local files](#local-files)
* [Remote files](#remote-files)
* [Multiple files](#multiple-files)
* [Combo](#combo)
* [Auto insert and update TOC](#auto-insert-and-update-toc)
* [Tests](#tests)
* [Dependency](#dependency)
<!-- Added by: <your-user>, at: 2018-02-04T19:38+03:00 -->
<!--te-->
Next time when your file will be changed just repeat the command (./gh-md-toc --insert ...) and TOC will be refreshed again.
GitHub token
All your tokens are here.
You will need them if you get an error like this:
Parsing local markdown file requires access to github API
Error: You exceeded the hourly limit. See: https://developer.github.com/v3/#rate-limiting
or place github auth token here: ./token.txt
A token can be used as an env variable:
➥ GH_TOC_TOKEN=2a2dab...563 ./gh-md-toc README.md
Table of Contents
=================
* [github\-markdown\-toc](#github-markdown-toc)
* [Table of Contents](#table-of-contents)
* [Installation](#installation)
* [Tests](#tests)
* [Usage](#usage)
* [LICENSE](#license)
Or from a file:
➥ echo "2a2dab...563" > ./token.txt
➥ ./gh-md-toc README.md
Table of Contents
=================
* [github\-markdown\-toc](#github-markdown-toc)
* [Table of Contents](#table-of-contents)
* [Installation](#installation)
* [Tests](#tests)
* [Usage](#usage)
* [LICENSE](#license)
TOC generation with Github Actions
Config:
on:
push:
branches: [main]
paths: ['foo.md']
jobs:
build:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v2
- run: |
curl https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc -o gh-md-toc
chmod a+x gh-md-toc
./gh-md-toc --insert --no-backup foo.md
- uses: stefanzweifel/git-auto-commit-action@v4
with:
commit_message: Auto update markdown TOC
Tests
Done with bats.Useful articles:
- https://blog.engineyard.com/2014/bats-test-command-line-tools
- http://blog.spike.cx/post/60548255435/testing-bash-scripts-with-bats
How to run tests:
➥ make test
✓ TOC for local README.md
✓ TOC for remote README.md
✓ TOC for mixed README.md (remote/local)
✓ TOC for markdown from stdin
✓ --help
✓ --version
6 tests, 0 failures
Dependency
- curl or wget
- awk (mawk is not tested)
- grep
- sed
- bats (for unit tests)
Tested on Ubuntu 14.04/14.10 in bash/zsh.
Docker
Local
- Build
$ docker build -t markdown-toc-generator .
- Run on an URL
$ docker run -it markdown-toc-generator https://github.com/ekalinin/envirius/blob/master/README.md
- Run on a local file (need to share volume with docker)
$ docker run -it -v /data/ekalinin/envirius:/data markdown-toc-generator /data/README.md
Public
$ docker pull evkalinin/gh-md-toc:0.7.0
$ docker images | grep toc
evkalinin/gh-md-toc 0.7.0 0b8db6aed298 11 minutes ago 147MB
$ docker run -it evkalinin/gh-md-toc:0.7.0 \
https://github.com/ekalinin/envirius/blob/master/README.md
-
[TOC] 原文翻译自github的Basic writing and formatting syntax和Working with advanced formatting. why using markdown?（为什么使用Markdown） Markdown是一种易于读写的文本标记。 可以方便你做好学习笔记等工作，比简单的记事本码字来说相对的对于格式比较容易控制。 可以很容易的写出格式整齐美观
-
Git commit 表情符号 commit 格式 git commit 时，提交信息遵循以下格式： :emoji1: :emoji2: 不超过 50 个字的摘要，首字母大写，使用祈使语气，句末不要加句号 提交信息主体 引用相关 issue 或 PR 编号 <#110> 初次提交示例： git commit -m ":tada: Initialize Repo" emoji 指南 emoj
-
Easy Markdown to Github Pages Introduction This little guide demonstrates how to turn any Github repository with a bunch of Markdown files into a simple website using Github Pages and Jekyll. You don'
-
我知道可以使用或的MD语法将图像放置在MD中，但我很难将SVG放置在代码托管在GitHub上的MD中。 最终使用rails3，并且现在经常更改模型，所以我使用RailRoady生成模型的模式图的SVG。我希望将SVG放在readme.md中并显示出来。当我在本地打开SVG文件时，它确实起作用，那么我如何让浏览器呈现MD文件中的SVG呢？考虑到代码在完成之前是动态的（似乎永远不会），将SVG托管在一
-
我正在Github存储库中编辑一个Readme.md文件，并插入了一张图片（见https://github.com/khpeek/FMCW-radar）。这幅画占据了整个宽度，但这样看起来很粗糙，我更喜欢把它做得更小。有什么办法可以做到吗？ P. S.我已经尝试了如何更改图像大小Markdown？的命令，但它们似乎不起作用。
-
我想在GitHub上的一个Markdown文件中显示一些图像。我发现它是这样工作的： 它可以在我的本地磁盘上工作，但不能在GitHub上工作。 有人知道这个问题吗？
-
我天真地以为只需在post.md页面中添加带有内容的标记就会很容易，如下所示： 但我看到的不是图像，而是SVG代码（在Firefox中）。到目前为止还没有找到任何办法来解决看起来很简单的事情。在jekyll/liquid减价范围内有可能吗？ > 我想用d3.js来操作svg代码，所以我假设我需要嵌入svg代码，而不是作为外部映像文件引用它。 我可以直接用d3.js生成初始的svg内容（这是可行的）
-
它最好不使用HTML。