ekalinin / github-markdown-toc.go

Easy TOC creation for GitHub README.md (in go)

github-markdown-toc

This is a golang based implementation of the github-markdown-toc tool.

The advantages of this implementation:

• no dependencies (no need curl, wget, awk, etc.)
• cross-platform (support for Windows, Mac OS, etc.)
• regexp for parsing TOC
• parallel processing of multiple documents

Attention: gh-md-toc is able to work properly only if your machine is connected to the Internet.

Table of Contents

• github-markdown-toc
• Installation
  • Precompiled binaries
  • Compiling from source
  • Go Install
  • Homebew (Mac only)
• Tests
• Usage
  • STDIN
  • Local files
  • Remote files
  • Multiple files
  • Combo
  • Starting Depth
  • Depth
  • No Escape
  • Github token
  • GitHub Enterprise Server
  • Bash/ZSH auto-complete
• Alpine Linux
• LICENSE

Created by gh-md-toc

Installation

Precompiled binaries

See the releases page, "Downloads" section:

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

For example:

$ 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

Compiling from source

You need golang installed in your OS:

$ make build
$ ./gh-md-toc --help
usage: gh-md-toc [<flags>] [<path>...]

Flags:
  --help           Show context-sensitive help (also try --help-long and --help-man).
  --serial         Grab TOCs in the serial mode
  --hide-header    Hide TOC header
  --hide-footer    Hide TOC footer
  --start-depth=0  Start including from this level. Defaults to 0 (include all levels)
  --depth=0        How many levels of headings to include. Defaults to 0 (all)
  --no-escape      Do not escape chars in sections
  --token=TOKEN    GitHub personal token
  --indent=2       Indent space of generated list
  --debug          Show debug info
  --version        Show application version.

Args:
  [<path>]  Local path or URL of the document to grab TOC. Read MD from stdin if not entered.

Go Install

You need golang installed in your OS:

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

Homebew (Mac only)

$ brew install github-markdown-toc

Tests

$ make test
coverage: 28.8% of statements
ok      _~/projects/my/github-toc.go    0.003s

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                                                                                                                                                Вс. марта 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)

Remote files

And here's an example, when you have a README.md like this:

• README.md without TOC

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 original README.md.

And here is a result:

• README.md with TOC

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)

Processing of multiple documents is in parallel mode since version 0.4.0 You can use (old) serial mode by passing option --serial in the console:

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

Timings:

➥ 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

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)

Starting Depth

Use --start-depth=INT to control the starting header level (i.e. include only the levels starting with INT)

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

Table of Contents
=================

  * [Or using Pathogen:](#or-using-pathogen)
  * [Or using Vundle:](#or-using-vundle)

Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)

Depth

Use --depth=INT to control how many levels of headers to include in the TOC

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

Table of Contents
=================

  * [Dockerfile\.vim](#dockerfilevim)
  * [Screenshot](#screenshot)
  * [Installation](#installation)
  * [License](#license)

No escape

➥ ./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 token

All your tokents are here.

Example for cli argument:

➥ ./gh-md-toc --depth=1 --token=2a2dabe1f2c2399bd542ba93fe6ce70fe7898563 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)

Example for environment variable:

➥ GH_TOC_TOKEN=2a2dabe1f2c2399bd542ba93fe6ce70fe7898563 ./gh-md-toc --depth=1  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)

GitHub Enterprise Server

If you're using GitHub Enterprise Server, you can override default URL for API:

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

Bash/ZSH auto-complete

Just add a simple command into your ~/.bashrc or ~/.zshrc:

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

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

Alpine Linux

Alpine Linux uses musl instead of glibc by default. If you install binutils and run…

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

…you'll see that it relies on /lib64/ld-linux-x86-64.so.2 as its interpreter. You can solve this by installing libc6-compat alongside downloading the Linux amd64 build.

apk add libc6-compat

LICENSE

See LICENSE file.

github-markdown-toc.go's Issues

TOC entries only generated when online

Steps to reproduce:

1. ensure machine is connected to the Internet.

2. find or write a Markdown document that should generate a good TOC, e.g.
   this gist.

3. use gh-md-toc to generate a TOC for it, to stdout.

   $ ~/bin/gh-md-toc ~/Desktop/burnout.md
   
   Table of Contents
   =================
   
   * ["The Modern Day Sisyphus: \#libtech Burnout and You": <a href="https://twitter\.com/yo\_bj">Becky Yoose</a>](#the-modern-day-sisyphus-libtech-burnout-and-you-becky-yoose)
     * [Abstract &amp; slides](#abstract--slides)
     * [twelve phases of burnout](#twelve-phases-of-burnout)
     * [what's special about \#libtech burnout](#whats-special-about-libtech-burnout)
     * [how to prevent/recover](#how-to-preventrecover)
     * [\.\.\.but this isn't about what the victim should do](#but-this-isnt-about-what-the-victim-should-do)
       * [co\-workers](#co-workers)
       * [managers](#managers)
       * [community](#community)
     * [community privilege](#community-privilege)
   
   Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
   $
   

4. turn off networking

5. attempt to generate the TOC again.

Expected:

• same TOC is generated as in step 3.

Actual:

• only header is generated:

  $ ~/bin/gh-md-toc ~/Desktop/burnout.md
  
  Table of Contents
  =================
  
  
  Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)
  $
  

Notes

• MacOS X 10.10.5
• go version go1.6 darwin/amd64
• gh-md-toc 5.0 built from commit 0523167

[BUG] [Windows release] Doesn't output any TOC, just a list of HTTP headers

Describe the bug

I downloaded the Windows binary release to try out. It seems to succeed in converting the Markdown to HTML, but instead of printing a Markdown TOC, it prints a list of what appear to be HTTP response headers from GitHub.

To Reproduce

1. Download and extract the Windows binary (I also had to give it an .exe extension)
2. Run it on a local markdown file in the same directory (doesn't seem to be able to handle drive letters in paths, but relative paths are OK)

Example command:

gh-md-toc.exe Home.md --debug

I also tried using the --token argument with my GitHub token, did not see any difference.

The file being used does have headings in the form of #, ## and so on.

Expected behavior

Markdown TOC, like the examples in the readme.

Environment (please complete the following information):

• OS: Windows 10
• Version: 1.2.0

Additional context

Here's a complete copy/paste of the command line:

gh-md-toc.exe Home.md --debug

Table of Contents
=================

2022/12/08 20:26:46 Convert2HTML: start.
2022/12/08 20:26:46 IsRemoteFile: false
2022/12/08 20:26:46 Convert2HTML: local file: Home.md
Header: X-Commonmarker-Version=0.23.6
Header: Cache-Control=public, max-age=60, s-maxage=60
Header: X-Ratelimit-Resource=core
Header: Access-Control-Expose-Headers=ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Header: X-Content-Type-Options=nosniff
Header: X-Xss-Protection=0
Header: Content-Security-Policy=default-src 'none'
Header: Content-Type=text/html;charset=utf-8
Header: Vary=Accept
Header: X-Github-Media-Type=github.v3; format=json
Header: Access-Control-Allow-Origin=*
Header: X-Frame-Options=deny
Header: X-Github-Request-Id=<redacted>
Header: Server=GitHub.com
Header: Date=Fri, 09 Dec 2022 01:26:47 GMT
Header: Etag=<redacted>
Header: X-Github-Api-Version-Selected=2022-11-28
Header: X-Ratelimit-Reset=1670552242
Header: X-Ratelimit-Used=6
Header: Strict-Transport-Security=max-age=31536000; includeSubdomains; preload
Header: X-Ratelimit-Limit=60
Header: X-Ratelimit-Remaining=54
Header: Referrer-Policy=origin-when-cross-origin, strict-origin-when-cross-origin
2022/12/08 20:26:47 Convert2HTML: converted to html, size: 19997
2022/12/08 20:26:47 Convert2HTML: write html file: Home.md.debug.html
2022/12/08 20:26:47 Convert2HTML: done.
2022/12/08 20:26:47 GrabToc: start, html size: 19997
2022/12/08 20:26:47 GrabToc: matching ...
2022/12/08 20:26:47 GrabToc: processing groups ...
2022/12/08 20:26:47 Including starting frome level 0
2022/12/08 20:26:47 GrabToc: done.

Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)

I'd rather not post the entire converted HTML but I verified that it does have <h1>, <h2> etc. tags.

[Feature] Add --insert option (like in shell project)

See:

• ekalinin/github-markdown-toc#105

[ BUG ] empty render

Describe the bug
The app renders an empty TOC:

Table of Contents
=================


Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)

To Reproduce

1. Download and unarchive the tarball for v1.2.1.
2. Create a simple markdown file that looks like this:

   # foo
   
   ## bar
   hello
   
   ## baz
   world

3. Run the following command:

   gh-md-toc ./your_doc.md

Expected behavior
TOC is rendered.

Environment (please complete the following information):

• OS: OSX (M1) and Ubuntu 22.04 (WSL2)
• Version 1.2.1

Additional context
Add any other context about the problem here.

[BUG] Can't work well when the text > 400KB

{"message":"This API renders Markdown text up to 400 KB in size. The requested text is too large to render via the API.","errors":[{"resource":"Markdown","field":"data","code":"too_large"}],"documentation_url":"https://docs.github.com/v3/markdown/"}

[Question] Hi,it had worked correctly before, but do not work now and prompt such information.

laoliu@anonemous:/mnt/c/Users/laoliu/Documents$ ./gh-md-toc tmp.md

Table of Contents

Header: Vary=Accept
Header: Access-Control-Expose-Headers=ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, X-GitHub-SSO, X-GitHub-Request-Id, Deprecation, Sunset
Header: Strict-Transport-Security=max-age=31536000; includeSubdomains; preload
Header: Referrer-Policy=origin-when-cross-origin, strict-origin-when-cross-origin
Header: Content-Type=text/html;charset=utf-8
Header: Cache-Control=public, max-age=60, s-maxage=60
Header: X-Frame-Options=deny
Header: X-Content-Type-Options=nosniff
Header: Etag=W/"8f02416ae1ffe52316586208420aa1472f865feba8e4f1a8ad86c2f4f78dd577"
Header: X-Ratelimit-Limit=60
Header: X-Github-Request-Id=27AF:64C2:4C8D70:4F9C04:637430A9
Header: X-Ratelimit-Reset=1668562617
Header: X-Ratelimit-Used=1
Header: X-Commonmarker-Version=0.23.6
Header: X-Github-Media-Type=github.v3; format=json
Header: X-Ratelimit-Remaining=59
Header: X-Ratelimit-Resource=core
Header: Access-Control-Allow-Origin=*
Header: X-Xss-Protection=0
Header: Server=GitHub.com
Header: Date=Wed, 16 Nov 2022 00:36:57 GMT
Header: Content-Security-Policy=default-src 'none'

Created by gh-md-toc
laoliu@anonemous:/mnt/c/Users/laoliu/Documents$

[Feature] --insert flag

Is your feature request related to a problem? Please describe.

The none golang version has the ability to insert the generated TOC into the markdown file.

It would be nice if the golang tool also did that.

Describe the solution you'd like

A clear and concise description of what you want to happen.

Like so:

gh-md-toc --insert examples/02/README.md
gh-md-toc: error: unknown long flag '--insert', try --help

Describe alternatives you've considered

I could do it manually but well i am hoping this is something everyone might need.

Additional context

The released gh-md-toc.linux.amd64.tgz prints http headers

Describe the bug
I download the latest release from https://github.com/ekalinin/github-markdown-toc.go/releases/download/1.2.0/gh-md-toc.linux.amd64.tgz. When I execute it, it prints not only toc to my console, but also some header strings like this.

Table of Contents
=================

Header: X-Commonmarker-Version=0.21.0
Header: X-Frame-Options=deny
Header: Referrer-Policy=origin-when-cross-origin, strict-origin-when-cross-origin
Header: Server=GitHub.com
Header: X-Ratelimit-Limit=60
Header: X-Content-Type-Options=nosniff
Header: X-Xss-Protection=0
Header: X-Ratelimit-Remaining=37
Header: Access-Control-Allow-Origin=*
Header: Content-Security-Policy=default-src 'none'
Header: Access-Control-Expose-Headers=ETag, Link, Location, Retry-After, X-GitHub-OTP, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Used, X-RateLimit-Resource, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval, X-GitHub-Media-Type, Deprecation, Sunset
Header: Strict-Transport-Security=max-age=31536000; includeSubdomains; preload
Header: Vary=Accept-Encoding, Accept, X-Requested-With
Header: Date=Wed, 07 Jul 2021 12:41:49 GMT
Header: Content-Type=text/html;charset=utf-8
Header: X-Ratelimit-Reset=1625662491
Header: X-Ratelimit-Used=23
Header: X-Ratelimit-Resource=core
Header: X-Github-Request-Id=83A2:32F4:3A83D97:6ECFA15:60E5A10C
* [heading1](#heading1)

Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)

But when I use the binary executable file built from the source by myself, it prints correctly without the headers.

To Reproduce

1. Download the binary file from https://github.com/ekalinin/github-markdown-toc.go/releases/download/1.2.0/gh-md-toc.linux.amd64.tgz
2. Extract the tar ball
3. Execute the binary file gh-md-toc path/to/the/readme/file

Expected behavior
Do not print the headers.

Environment (please complete the following information):

• OS: Ubuntu
• Version 20.04.1 LTS with kernel 5.4.0-73-generic

Additional context
None.

Don't Create Backups

Would it be possible not to create backups as a command switch? We're already using git so to me it doesn't make sense. But what do I know :)

[Feature] Replace TOC comment in place on a folder

Looks for an annotation in a markdown file that represents the TOC

Use markdown comments to indicate where the TOC is to be placed in a file.

A markdown file would look like this:

TOC START comment
the actual toc
TOC END comment

The logic steps are:

1. Walk files

2. For each .md

3. Find the TOC comment annotation in that .md

4. Create the toc.

5. Inject into the markdown one line below the TOC and another annotation of TOC END

• The TOC END is important because it tells the logic where the insert ends.

Seems to be generating blank ToCs ..

$ wget https://raw.githubusercontent.com/ekalinin/envirius/f939d3b6882bfb6ecb28ef7b6e62862f934ba945/README.md
[...]
2017-04-21 15:53:27 (10.1 MB/s) - ‘README.md’ saved [10028/10028]

$ ./gh-md-toc README.md 

Table of Contents
=================


Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)

I get the same with the bash version:

$ ~/git/github-markdown-toc/gh-md-toc README.md 

Table of Contents
=================



Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)

Interestingly, this one did work the first time I ran it.

$ ~/git/github-markdown-toc/gh-md-toc --version
0.4.8
$ ./gh-md-toc --version
0.6.0

Hmm, these do work (remote pages):

$ ./gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md
$ ~/git/github-markdown-toc/gh-md-toc https://github.com/ekalinin/envirius/blob/master/README.md

[Feature] Sends data to github.com (should be able to send to internal github enterprise instead)

Describe the bug
Sends data to github. This should be made clear somewhere that the tool is doing this. It should also be possible to send to an internal github enterprise installation instead.

Additional context
See here:

github-markdown-toc.go/internals.go

Lines 105 to 111 in 8928564

	func ConvertMd2Html(localpath string, token string) (string, error) {
	url := "https://api.github.com/markdown/raw"
	if token != "" {
	url += "?access_token=" + token
	}
	return httpPost(url, localpath)
	}

[Feature] support `go install`-based installation

Is your feature request related to a problem? Please describe.
New standard in Go is to be able to install executables directly with go install

Describe the solution you'd like

• go install https://github.com/ekalinin/github-markdown-toc.go ...
• update README in light of it

Option to Not Output TOC Heading

This would prevent the program from outputting:

Table of Contents
=================

Build instructions.

"Compiling from source" section refer to make get-deps

This target is no more available in Makefile.

The "Compiling from source" section should be reworked or removed.

[ BUG ] Unable to generate TOC

Describe the bug
unable to generate TOC from markdown

To Reproduce
run gh-md-toc and is nothing. guess regex expression is unmatched.

source_code

Environment (please complete the following information):

• OS: Mac
• Version Big Sur 11.6

bug report

Mac OSX 10.11

$ wget https://github.com/ekalinin/github-markdown-toc.go/releases/download/0.4.0/gh-md-toc.linux.amd64.tgz
$ tar xzvf gh-md-toc.linux.amd64.tgz
x gh-md-toc
$ ./gh-md-toc --version
-bash: ./gh-md-toc: cannot execute binary file

Escape _ and *

Great code. It would be nice if it would escape special characters that are in titles.

For example, this readme

https://github.com/opscode-cookbooks/iis

There is a field called

mod_*

The underscore and * should be escaped like:

    * [mod\_\*](#mod_)

markdown-toc escaping chars in sections

it seems it escapes chars like '-', '.' when in sections.

for example

• The event-driven paradigm
• Basic built-in handles
  * request.method
  * request.headers
  * request.data
  * request.query
  * request.path

some editors have a way to navigate through markdown documents, vy uses the text between [title] to navigate to sections in markdown docs. is possible to remove that behavior of escaping those chars from the toc?

TOC With No 1st Level Heading is Output as Code

Given:

## Foo

### Bar

The following is output:

Table of Contents
=================

    * [Foo](#foo)
      * [Bar](#bar)

Given the leading space, the TOC is code formatted. This is because my document has no H1.

In this case the documents are on GitHub's wiki, so the H1 is supplied by them.

Running setup is racecy and doesn't write an MBR reliably

I thought I fixed this but quite often you have to run setup <device> twice in order ot get a proper install. For some reason this seems to be racey and the MBR or SYSLINUX Boot Loader doesn't get written correctly?

[Feature] Write the TOC somewhere in the markdown

Hello,
thanks for the tool.

There's one feature I'd really like in it: the ability to directly manipulate a Markdown file and inserting the TOC in a specific place, in order to make the update automatic.

Let's suppose a README.md like

## Hello

asdasdasd

## Table Of Contents

xyahdyshasyhd

### Other title

I'd like to do something like

gh-md-toc insert-toc-at "Table Of Contents" README.md 

And I would get on stdout the FULL README.md, with whatever was inside the "Table Of Contents" replaced by the TOC:

## Hello

asdasdasd

## Table Of Contents

* [Hello](#hello)
* [Table Of Contents)(#table-of-contents)
  * [Other title](#other-title)

### Other title

I suppose I could achieve a similar result in bash with awk/sed/similar tools, but IMHO this feature would be quite in line with gh-md-toc purpose.

I'm no go expert, but if you think you don't have time to do it but you would accept a PR for it, I can try coding it myself.

Indentation of TOC items prevents github wiki markdown from parsing the links

This will not work (because it is treated as a code block?):

    * [Process](#process)
    * [Preparing your workstation](#preparing-your-workstation)
    * [Known Issues](#known-issues)
      * [ERROR\! Unexpected Exception: [Errno 12] Cannot allocate memory](#error-unexpected-exception-errno-12-cannot-allocate-memory)

This will work:

* [Process](#process)
* [Preparing your workstation](#preparing-your-workstation)
* [Known Issues](#known-issues)
  * [ERROR\! Unexpected Exception: [Errno 12] Cannot allocate memory](#error-unexpected-exception-errno-12-cannot-allocate-memory)

Your code is completely broken now

I've installed the latest version with go get and it won't work with any files, e.g

gh-md-toc https://github.com/aminb/rust-for-c/blob/master/hello_world/README.md

What was changed recently? It's completely broken now.

Option for start depth

This would allow someone to skip the first header

Can't display normally in gitbook

pc：windows64
download：gh-md-toc.windows.amd64.tgz
powershell：./gh-md-toc.exe html.md
result：

• HTML
  * 概述
  * 空元素
  * 标记文本
  * HTML特殊字符
  * 列表 Lists
  * HTML表格
  * HTML表单
  * 参考资料
  * MDN

copy it in my html.md
show in github is ok：https://github.com/taohy88/gitbook_learning/blob/master/font/html.md
Can't display normally in gitbook：https://taohy88.github.io/gitbook_learning/font/html.html

How to resolve it ?

?access_token will stop functioning in the GitHub API soon

github-markdown-toc.go/internals.go

Lines 105 to 111 in 8928564

	func ConvertMd2Html(localpath string, token string) (string, error) {
	url := "https://api.github.com/markdown/raw"
	if token != "" {
	url += "?access_token=" + token
	}
	return httpPost(url, localpath)
	}

The GitHub emails that have been going out say that this will soon stop being supported, and consumers should move to Basic Auth.

Can't deal with the Remote files

Just like this issue #13 (comment),it can't deal with the remote files.

For example,(the sample code in README.md)

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

Table of Contents
=================


Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)

My environment:

$ git --version
git version 2.21.0.windows.1

$ ./gh-md-toc --version
1.0.0

New release

@ekalinin could you please make a new release that would include the #24 fix?

Can this tool generate a TOC if the input file does not contain a 1st-level head?

I don't specify a 1st-level head in markdown files because Jekyll creates one for me when I use the title: directive. My typical markdown file looks something like this:

---
layout: post
title: My Title

---

### Saturday, May 28

#### KIN ➜ BOS
Amtrak Northeast Regional #66 departs Kingston Station at 6:17 am and arrives in South Station, Boston at 7:58 am.

MBTA transit to Logan Airport.

#### BOS ➜ ATL ➜ SFO
Delta Airlines #1801 departs at 11:00 am and arrives at 1:43 pm.  
Delta Airlines #1923 departs at 2:35 pm and arrives at 4:45 pm.

Here is the output from gh-md-toc:

Table of Contents
=================


Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)

I expected to see a TOC. Am I doing something wrong?

[ Report ] Can't create a TOC because GitHub API's response has changed

Not a bug of gh-md-toc, but currently it can't create a TOC because the GitHub API response has changed.

It is not clear when this started. It appears that the anchor tag now contains the "aria-hidden" attribute.

- <h1><a id="user-content-one" class="anchor" href="#one"><span class="octicon octicon-link"></span></a>One</h1>
+ <h1><a id="user-content-one" class="anchor" aria-hidden="true" href="#one"><span aria-hidden="true" class="octicon octicon-link"></span></a>One</h1>

To Reproduce

$ # Markdown to be ToC
$ cat sample.md
# One

Uno

## Two

Dos

### Three

Tres

$ # Print ToC
$ gh-md-toc ./sample.md

Table of Contents
=================


Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)

Expected behavior

$ # Print ToC
$ gh-md-toc ./sample.md

Table of Contents
=================

* [One](./sample.md#one)
  * [Two](./sample.md#two)
    * [Three](./sample.md#three)

Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)

Environment:

• OS: macOS Catalina (OSX 10.15.7)
  • gh-md-toc Version: 1.2.0 (via homebrew and go install)
• OS: Alpine (Docker, golang:alpine)
  • gh-md-toc Version: 1.2.0 (via go install)

Additional context

$ gh-md-toc --debug ./sample.md

Table of Contents
=================

2022/08/24 13:54:59 Convert2HTML: start.
2022/08/24 13:54:59 IsRemoteFile: false
2022/08/24 13:54:59 Convert2HTML: local file: ./sample.md
2022/08/24 13:55:00 Convert2HTML: converted to html, size: 487
2022/08/24 13:55:00 Convert2HTML: write html file: ./sample.md.debug.html
2022/08/24 13:55:00 Convert2HTML: done.
2022/08/24 13:55:00 GrabToc: start, html size: 487
2022/08/24 13:55:00 GrabToc: matching ...
2022/08/24 13:55:00 GrabToc: processing groups ...
2022/08/24 13:55:00 Including starting from level 0
2022/08/24 13:55:00 GrabToc: done.

Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)

$ cat sample.md.debug.html
<h1><a id="user-content-one" class="anchor" aria-hidden="true" href="#one"><span aria-hidden="true" class="octicon octicon-link"></span></a>One</h1>
<p>Uno</p>
<h2><a id="user-content-two" class="anchor" aria-hidden="true" href="#two"><span aria-hidden="true" class="octicon octicon-link"></span></a>Two</h2>
<p>Dos</p>
<h3><a id="user-content-three" class="anchor" aria-hidden="true" href="#three"><span aria-hidden="true" class="octicon octicon-link"></span></a>Three</h3>
<p>Tres</p>

If changes to the API response are permanent, it may be necessary to modify the regular expression.

github-markdown-toc.go/ghdoc.go

Lines 145 to 148 in 92ed8d0

	re := `(?si)<h(?P<num>[1-6])>\s*` +
	`<a\s*id="user-content-[^"]*"\s*class="anchor"\s*` +
	`href="(?P<href>[^"]*)"[^>]*>\s*` +
	`.*?</a>(?P<name>.*?)</h`

0.7.0 SIGSEGV

This bug is caused by fd65dd8 and goes away if I revert that commit.

Running
gh-md-toc ../README.md crashes.

iMac-TMP:github-markdown-toc.go joe$ /usr/local/Cellar/github-markdown-toc/HEAD-3959e2c/bin/gh-md-toc  ../README.md

Table of Contents
=================

panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x0 pc=0x12ba246]

goroutine 1 [running]:
main.(*GHToc).Print(0x0)
	/private/tmp/github-markdown-toc-20170703-12178-5ub0au/src/github.com/ekalinin/github-markdown-toc.go/main.go:28 +0x26
main.main()
	/private/tmp/github-markdown-toc-20170703-12178-5ub0au/src/github.com/ekalinin/github-markdown-toc.go/main.go:265 +0xa9a

(lldb) r ../README.md
Process 12715 launched: '/usr/local/Cellar/github-markdown-toc/HEAD-3959e2c/bin/gh-md-toc' (x86_64)

Table of Contents
=================

Process 12715 stopped
* thread #1: tid = 0xae9b72, 0x00000000012ba246 gh-md-toc`main.(toc=(len <parent is NULL>, cap <parent is NULL>)).Print + 38 at main.go:28, stop reason = EXC_BAD_ACCESS (code=1, address=0x0)
    frame #0: 0x00000000012ba246 gh-md-toc`main.(toc=(len <parent is NULL>, cap <parent is NULL>)).Print + 38 at main.go:28
(lldb) bt
* thread #1: tid = 0xae9b72, 0x00000000012ba246 gh-md-toc`main.(toc=(len <parent is NULL>, cap <parent is NULL>)).Print + 38 at main.go:28, stop reason = EXC_BAD_ACCESS (code=1, address=0x0)
  * frame #0: 0x00000000012ba246 gh-md-toc`main.(toc=(len <parent is NULL>, cap <parent is NULL>)).Print + 38 at main.go:28
    frame #1: 0x00000000012bc1ea gh-md-toc`main.main + 2714 at main.go:265
    frame #2: 0x000000000102bb8a gh-md-toc`runtime.main + 522 at proc.go:185
    frame #3: 0x0000000001054ee1 gh-md-toc`runtime.goexit + 1 at asm_amd64.s:2197
    frame #4: 0x00000000012bc1ea gh-md-toc`main.main + 2714 at main.go:265
    frame #5: 0x000000000102bb8a gh-md-toc`runtime.main + 522 at proc.go:185
    frame #6: 0x0000000001054ee1 gh-md-toc`runtime.goexit + 1 at asm_amd64.s:2197
    frame #7: 0x000000000102bb8a gh-md-toc`runtime.main + 522 at proc.go:185
    frame #8: 0x0000000001054ee1 gh-md-toc`runtime.goexit + 1 at asm_amd64.s:2197
    frame #9: 0x0000000001054ee1 gh-md-toc`runtime.goexit + 1 at asm_amd64.s:2197
(lldb) 

[BUG] TOC picks up YAML

Describe the bug
When running the tool on a .md file, for some reason, it generates a TOC item for the YAML I have at the top of my file. When I was using the shell script, it didn't pick up the YAML and generate a TOC item.

To Reproduce
Use a .md file with YAML at the top and run the tool. The output shows the YAML code ad depth=1

regression test failure with github-markdown-toc 1.2.0

Problem

Run into some regression test failure when trying to build the new bottle for macOS Ventura, the error is the heading processing is not working as expected.

How to reproduce

• brew install github-markdown-toc
  -echo "# Header" > README.md
• gh-md-toc --debug README.md

$ gh-md-toc README.md

Table of Contents
=================


Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)

Debug mode

|$ gh-md-toc --debug README.md

Table of Contents
=================

2022/11/07 21:16:37 Convert2HTML: start.
2022/11/07 21:16:37 IsRemoteFile: false
2022/11/07 21:16:37 Convert2HTML: local file: README.md
2022/11/07 21:16:37 Convert2HTML: converted to html, size: 237
2022/11/07 21:16:37 Convert2HTML: write html file: README.md.debug.html
2022/11/07 21:16:37 Convert2HTML: done.
2022/11/07 21:16:37 GrabToc: start, html size: 237
2022/11/07 21:16:37 GrabToc: matching ...
2022/11/07 21:16:37 GrabToc: processing groups ...
2022/11/07 21:16:37 Including starting frome level 0
2022/11/07 21:16:37 GrabToc: done.

Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc.go)