I'd like to have global TOC for number of files (say, chapter-1.md, chapter-2.md, etc) and place it in README or index.md (as we use gh-pages, we want index). Is it possible with your tool? Would it be possible to add this feature to your tool?

Was able to generate TOC yesterday -- today it is not working... Not sure if something changed on my end, or upstream GitHub changed something...

➜  ~ 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)
➜  ~ echo $?
0

Versions of utils:

➜  ~ uname -m
x86_64
➜  ~ curl --version| head -n 1
curl 7.47.1 (x86_64-pc-linux-gnu) libcurl/7.47.1 OpenSSL/1.0.1t zlib/1.2.8
➜  ~ grep --version | head -n 1
grep (GNU grep) 2.20
➜  ~ sed --version | head -n 1
sed (GNU sed) 4.2.2
➜  ~ sed --version | head -n 1
sed (GNU sed) 4.2.2
➜  ~ awk -W version
GNU Awk 4.0.2
Copyright (C) 1989, 1991-2012 Free Software Foundation.
...

Love the idea but all of our README's use the # H1, ## H2, etc style. Would be awesome to support that!

This is a great script when it works.
But some md file I have doesn't work.

eg,

./gh-md-toc https://github.com/rickyzhang82/concurrent-programming/raw/master/doc/NOTE.md

I saw another issue. Some guy reached conclusion that it is related to GNU awk version. Any suggestions to work around it? eg, use docker?

Hi

Thanks for making this solution!

I tried both for local and remote, all like below. is there some package I need to install?

I have all the dependency except bats

./gh-md-toc https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv

Table of Contents

Created by gh-md-toc

Does this project solve the basic problem:

Some kind of build step is needed to create the TOC.

I use this README to have a small wiki with version control.

I like editing the page via the github text editor (without local checkout and commit+push)

Can your project create a TOC without a build step?

This returns an empty TOC: $ gh-md-toc "x:-y.md".

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


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

This works: $ gh-md-toc x-y.md.

Hi,

First, thanks for this useful script. Second, it seems to me that there is a problem when a title has a backquote at the end. Here is an example with this simple markdown file:

# The command `foo1`

Blabla...

# The command `foo2` is better

Blabla...

# The command `bar1`

Blabla...

# The command `bar2` is better

Blabla...

I have this:

~$ ./gh-md-toc /tmp/test.md 

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

 * [](#the-command-foo1)
  * [The command <code>foo2</code> is better](#the-command-foo2-is-better)
 * [](#the-command-bar1)
  * [The command <code>bar2</code> is better](#the-command-bar2-is-better)

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

Regards

# First
### Third

becomes

   * [First](#first)
         * [Third](#third)

and github renders it in one line (see https://github.com/elimohl/test/blob/master/README.md)

Awesome utility. It would be nice to be able to have this read from STDIN or from a --file attribute.

Hi, love this tool.
Is it possible to add an option to generate a list of items starting with a dash rather than an asterisk?

To automatize the TOC generation,
it would be nice that gh-md-toc generates the TOC inside the MD file, instead of generating some text that user has to manually insert at the desired position.

So, if the markdown file has a marker like:

<!-- TOC -->

gh-md-toc generates or re-generates the TOC at this position.
To re-generate the TOC, and delete the old TOC, the end of TOC could be marked by something like:

<!-- gh-md-toc end , generated at samedi 25 novembre 2017, 04:08:42 (UTC+0100) by jmv -->

Hi,
In sublime text there is a package called 'MarkdownTOC'. If can get that existing sublime package's python code to call and invoke this program, then it will auto-regenerate refresh the TOC on every save (Ctrl+S) in Sublime Text.

And that would be awesome.

Because currently MarkdownTOC does the hooks thing well. But not generate TOC correctly (which is very bad output actually). Need the best of both worlds.

I was using the direct insert flag --insert to directly insert the TOC into the readme.md. I've added the two lines

<!--ts-->
<!--te-->

into the readme but when running the script with the --insert flag I get the output:

You don't have <!--ts--> or <!--te--> in your file...exiting

I've found the part in the script that does the search for the tags

 if grep -Fxq "<!--ts-->" $gh_src && grep -Fxq "<!--te-->" $gh_src; then

which seems to fail. I've run the command manually on Linux Mint 19

grep -Fxq "<!--ts-->" Readme.md

and I get the error

bash: !-: event not found

For my workaround I had to escape the syntax to this form

if grep -xq "<\!--ts-->" $gh_src && grep -xq "<\!--te-->" $gh_src; then

Line 178 returns the following error

./gh-md-toc: line 178: [: =: unary operator expected```

should probably be changed to

 if [ "$no_backup" = "yes" ]; then

If I create some headers like:

# Top 

will be generated

## On <sub><sub>[Go to Top](#top)</sub></sub>

side of this page.

It does generates this:

- [Top](#top)
  * [On <sub><sub>[Go to Top](#top)</sub></sub>](#on--sub--sub--go-to-top---top---sub---sub-)

Instead of this:

- [Top](#top)
  * [On](#on-go-to-top)

This tool is great! I'd like to suggest this improvement: allow me to specify the deepest heading level I want to consider to build the TOC, e.g., --max-level 2, it will only consider # and ## headers, it will skip from ### or more.

GitHub wiki pages can have spaces in the name. This is not supported by gh-md-toc. Filenames cannot have spaces.

$ git clone [email protected]:ekalinin/github-markdown-toc.git
$ cd github-markdown-toc.git
$ ./gh-md-toc README.md > a.md

this command returned after least one minute on Mac OSX 10.10.3 .

The false space character is c2 in hexadecimal (194 in decimal).
In a title, it causes gh-md-toc to skip the title.

Example

## real space
## bad-space
The bad space is after the 2 sharp characters.

I don't know how I got that false space in the first place !

I have a README.md

I wanted to create TOC

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

Sometimes it shows the contents, but sometimes it return blank. I cant understand why sometimes it works and sometimes not

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.

Also opened for the go version.

On XXX #XX, 2020 at ##:## (UTC) your personal access token (...) using gh-md-toc v0.6.1 was used as part of a query parameter to access an endpoint through the GitHub API:

https://api.github.com/markdown/raw

Please use the Authorization HTTP header instead, as using the access_token query parameter is deprecated and will be removed July 1st, 2020.

Depending on your API usage, we'll be sending you this email reminder once every 3 days for each token and User-Agent used in API calls made on your behalf.
Just one URL that was accessed with a token and User-Agent combination will be listed in the email reminder, not all.

Visit https://developer.github.com/changes/2019-11-05-deprecated-passwords-and-authorizations-api/#authenticating-using-query-parameters for more information.

Thanks,
The GitHub Team

It would be nice to have a mode like --insert except instead of overwriting the existing file, the entire new contents of the file (not just the TOC) are output to standard output. Unlike --insert this could work on non-local files, and allow another script to upload the file. It would also let you work on local files saving the result somewhere else and avoiding the next to create the .orig. and .toc.` files which need cleaning up in scripts.

Thanks for this tool, I tried it out today. Maybe you want to tweak your build process for the binaries...
After unpacking the tgz then the tar file, I noticed that the windows binaries don't have a '.exe' on the end.

This confused me as I thought maybe there was a mixup and some unix binaries had got packaged instead.

I ended up testing the 386 windows binary and it works fine after I added the missing extension.

Hope it helps, Fazl

If my titles are URLs. E.g.:

My issue

Then the generated markdown will keep this URL in the TOC. So when I click on the TOC link I got redirected to the URL

I tried to generate TOC gh-md-toc https://github.com/pavelsr/coding_standarts/wiki/Perl

Seems like gh-md-toc return non-encoded uri, that's why TOC does not work.

E.g. istead of link #Как-быстро-выучить-perl- there must be #%D0%9A%D0%B0%D0%BA-%D0%B1%D1%8B%D1%81%D1%82%D1%80%D0%BE-%D0%B2%D1%8B%D1%83%D1%87%D0%B8%D1%82%D1%8C-perl-

So we need to add url escaping

I have a private repository and I want to use this generate a toc

problems

🤥 pushaowei🍭 15:04 ➜  skill git:(master) ✗ ./gh-md-toc ~/notes/skill/README.md

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

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: /Users/pushaowei/notes/skill/token.txt

version

🤥 pushaowei🍭 15:01 ➜  skill git:(master) ✗ ./gh-md-toc --version
0.6.0

./gh-md-toc: line 231: lsb_release: command not found
os:
cat: /proc/version: No such file or directory
kernel:
shell:  zsh 5.3 (x86_64-apple-darwin17.0)

curl : curl 7.54.0 (x86_64-apple-darwin17.0) libcurl/7.54.0 LibreSSL/2.0.20 zlib/1.2.11 nghttp2/1.24.0
wget : GNU Wget 1.20 在 darwin17.7.0 上编译。
grep : grep (BSD grep) 2.5.1-FreeBSD
awk  : awk version 20070501
sed  : sed: illegal option -- -
usage: sed script [-Ealn] [-i extension] [file ...]
       sed [-Ealn] [-i extension] [-e script] ... [-f script_file] ... [file ...]

It seems gh-md-toc(the repository version and other versions fails with it)

gh-md-toc https://github.com/iogf/untwisted/blob/master/BOOK.md

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 0523167dffc9cedcbc55996e3717716760bb4454

Running on the local source of stoptracking/windows10/blob/Virt/README.md

.\gh-md-toc.exe --debug C:\Users\xxx\xxx\xxx\xxx\xxx\README.md

Table of Contents
2020/05/11 14:51:41 Convert2HTML: start.
=================
2020/05/11 14:51:41 IsRemoteFile: true

2020/05/11 14:51:41 Convert2HTML: remote file. content-type:
2020/05/11 14:51:41 Convert2HTML: done.
2020/05/11 14:51:41 Get c:\Users\xxx\xxx\xxx\xxx\xxx\README.md: unsupported protocol scheme "c"

Am I doing something wrong here? No idea why file type is identified as "remote".

I'm not getting the expected results:

• MacOS 10.14.6
• .md files generated w/ Typora
• GitHub Desktop app used for git client
• the Github file

Here's what I've done:

1. curl https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc -o gh-md-toc
2. chmod a+x gh-md-toc
3. ./gh-md-toc /Users/seamus/Documents/GitHub/PiFormulae/CreatingRationalMusicLibrary2.md > new-with-toc.txt
4. cat new-with-toc.txt

Table of Contents

  * [Create a Rational and Portable File Server for Your Music Library](#create-a-rational-and-portable-file-server-for-your-music-library)
        * [0. Objective](#0-objective)
        * [1. Select the USB storage media](#1-select-the-usb-storage-media)
        * [2. Create and format a partition](#2-create-and-format-a-partition)
        * [2. Mounting a network storage device:](#2-mounting-a-network-storage-device)
        * [3. Copy/Sync Music repositories](#3-copysync-music-repositories)
        * [3.ALT Copy Music repositories using install](#3alt-copy-music-repositories-using-install)
        * [4. Serve!](#4-serve)
        * [Linux vs. Samba <em><strong>permissions</strong></em>](#linux-vs-samba-permissions)
        * [Samba profile for single user pi](#samba-profile-for-single-user-pi)
        * [Samba profile for read-only guest access, write access for user pi](#samba-profile-for-read-only-guest-access-write-access-for-user-pi)

Created by gh-md-toc

After a select+C&P into my .md file & uploading, this doesn't render properly on my github page:

(https://github.com/seamusdemora/PiFormulae/blob/master/CreatingRationalMusicLibrary2.md)

This is my first time to submit an issue.

Issue:
The first segment of code is into normal words in generated TOCs.

Example:
gh-md-toc should generate

* [Functions and Closures <code>def</code> <code>with</code> <code>as</code>](#functions-and-closures-def-with-as)

for

## Functions and Closures `def` `with` `as`

instead of
* [Functions and Closures def <code>with</code> <code>as</code>](#functions-and-closures-def-with-as)

Hello,

Thanks for such a convenient tool! Works great for me on multiple linux platforms.

Unfortunately in OS X the current version returns no TOC lines, even with input .md files that produce the expected output in linux. Looks like it may be related to argument to $GH_GREP in gh_toc_grab().Any ideas?

$ grep --version
grep (BSD grep) 2.5.1-FreeBSD

$ uname -a
Darwin macbookone.local 14.4.0 Darwin Kernel Version 14.4.0: Thu May 28 11:35:04 PDT 2015; root:xnu-2782.30.5~1/RELEASE_X86_64 x86_64

$ ./gh-md-toc ~/src.mywork.gitRepos/stowlerGeneralComputing/docs/setupBasicScriptingEnvironment.md

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



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

$

Hi. I just wanted to let You know that while this works perfectly for English-only characters, some letters with accents and other diacritical signs get "messed up" in the process.

For example, ň goes to %C5%88, and í goes to %C3%AD.

I guess the links still work, but it's ugly, and modern browsers can handle these special accentuated letters without a problem.

I suspect this has to do with character encoding, but I am not sure whether this is intentional, or, if not, how to fix this. Thus this issue.

Thank You for Your time and effort

Hi,

Your tool looks great and would save a lot of work for me.

However when I tried your tool with one of my wiki page

gh-md-toc https://github.com/box/TestScribe/wiki/FAQ

I got the following error

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

grep: unrecognized option `--null-data'
usage: grep [-abcDEFGHhIiJLlmnOoqRSsUVvwxZ] [-A num] [-B num] [-C[num]]
        [-e pattern] [-f file] [--binary-files=value] [--color=when]
        [--context[=num]] [--directories=action] [--label] [--line-buffered]
      [--null] [pattern] [file ...]


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

I got the same error when I run it with a local .md file.

What did I miss?

Would it be possible to not back up the README.md using a command line switch? We already have git?

Consider supporting ordered lists instead of assuming unordered lists. Wikipedia uses this TOC style.

Under OS X no TOC is returned. I tried the current master as well as version 0.4.4 as recommended in issue #15.

This is the output of version 0.4.4:

$ gh-md-toc README.md


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

grep: unrecognized option `--null-data'
usage: grep [-abcDEFGHhIiJLlmnOoqRSsUVvwxZ] [-A num] [-B num] [-C[num]]
    [-e pattern] [-f file] [--binary-files=value] [--color=when]
    [--context[=num]] [--directories=action] [--label] [--line-buffered]
    [--null] [pattern] [file ...]

(23) Failed writing body

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

The current master has no output at all.

Howdy, This isn't an issue, but I created a docker image that runs your script internally.
https://hub.docker.com/r/hipposareevil/github-markdown-toc/

I have it working for the cat version of your usage:

cat README.md | docker run -i hipposareevil/github-markdown-toc

• [foo] (#foo)
  .....

TOC creating from STDIN on Mac OS X without GNU coreutils will fail, the error raised out like below:

$ cat foo.md | gh-md-toc -
gh-md-toc: line 144: $gh_tmp_md: ambiguous redirect

It fails because the mktemp command shipped with Mac OS X comes from FreeBSD, witch has different behaviour from the GNU coreutils one.

$ mktemp
usage: mktemp [-d] [-q] [-t prefix] [-u] template ...
       mktemp [-d] [-q] [-u] -t prefix

I've send a pull request to fix this.

here is an example:

    root@myserver:~# cat /etc/redis/redis.conf | grep keep
    # TCP keepalive.
    tcp-keepalive 0

the above markdown snippet triggers an TOC entry:

* [TCP keepalive.](#tcp-keepalive)

which is wrong. the TOC should not generated based on the indent block.

I've been working on some dynamic blocks for Gutenberg (dynamic in that they output html in the render_callback of block registration). Any headings I insert into the content in this way are not picked up by Easy TOC. Not inserted into the TOC at all.

I'm using the shortcode, not automatic TOC insertion.

I think this is because the shortcode runs before the blocks are rendered and builds the TOC against the stored post content, not the actual final output.

Is there anything i can do to easily change easy TOC so that the shortcode just adds filters to insert the TOC that run on the final content?

Test case: https://github.com/trailofbits/algo/blob/master/docs/troubleshooting.md

$ ./gh-md-toc troubleshooting.md 

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



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

Really useful idea.

Unfortunately it doesn't seem to work on Arch Linux with either Bash/ZSH at the moment. I can try out the go-based version in the meantime, but just thought I would report in case it is an easy fix to extend support beyond Ubuntu.

Just let me know if there is any other info you need.
make_test_output.txt

$ gh-md-toc --version
0.4.6
$ bats --version
Bats 0.4.0
$ zsh --version
5.2
$ bash --version
4.3.42

make test

...
9 tests, 6 failures
make: *** [Makefile:6: test] Error 1

For example, for the document:

title
=====

h2
--

### h3

...

### h3 2

...

### h3 3

...

h2 2
----

...

The TOC generated is:

$ gh-md-toc test.md   

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

  * [title</h1>  <h2> <a id="user-content-h2" class="anchor" href="#h2" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>h2</h2>  <h3> <a id="user-content-h3" class="anchor" href="#h3" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>h3</h3>  <p>...</p>  <h3> <a id="user-content-h3-2" class="anchor" href="#h3-2" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>h3 2</h3>  <p>...</p>  <h3> <a id="user-content-h3-3" class="anchor" href="#h3-3" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>h3 3</h3>  <p>...</p>  <h2> <a id="user-content-h2-2" class="anchor" href="#h2-2" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>h2 2](#title)

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

I cant create for my nonstandard.js package
https://github.com/LestaD/nonstandard.js

If the title has . character, the link returned from the API(https://api.github.com/markdown/raw) will miss the . character.
For example,

# a.b

The related content of the link will be:

href="#ab

However, the right content should be:

href="#a.b