Fix TOC in the README.md

[bwood]

Tasks:

1. Find automatic way of generating a table of contents for GitHub-style markdown. The preference is for a script that can be run from the command line.
2. Use the script to update the README.md and make a pull request.

[bwood]

@honzi writes:

I found a Chrome userscript at https://github.com/tomancaklab/tomancaklab.github.io/blob/master/gfm-add-toc.user.js that seems to generate an accurate TOC for markdown files. It's limited to the wysiwyg editor for GitHub repository wiki files, as that seems to be drastically different from the wysiwyg editor for files within the repository. Copying and pasting the README.md file into a wiki file editor will generate a pretty accurate TOC that can be copypasted back into the README.md file. I'll try to create a Chrome extension that does this for all GitHub files, but the complex editor that GitHub uses for repository files may be too complex.

[bwood]

@honzi: My preference would be to find a script that can be run from the command line. This way it could be easily called from a script like rebuild.sh. That would allow us to automate the TOC creation as part of a release build.

[honzi]

@bwood: I had a feeling that a GUI-approach wouldn't be ideal, so I did some more digging. I found isaacs/github#215 which is an unofficial issue related to this issue, which may have the answer.

They mention a few command line based options, such as:

• https://github.com/ekalinin/github-markdown-toc
• https://github.com/thlorenz/doctoc
• https://github.com/amaiorano/md-to-toc

According to isaacs/github#215 (comment) GitHub already supports AsciiDoc, which can easily display a table of contents automatically. This would mean nothing would have to be added to any build scripts, but it would mean that the readme would have to be modified with AsciiDoc markup. The TOC being rendered only when viewed via GitHub or other markdown renders would mean that the TOC wouldn't be in the readme file, however.

[bwood]

Thanks for the links! This sure is an ongoing issue! On a super-quick look this one looks good to me: https://github.com/thlorenz/doctoc Want to try that out and maybe compare it to any others you think are good?

[honzi]

Sure. I'll have a chance to try out various options over the weekend of the 24th.

[honzi]

Of the three I found, I definitely agree that https://github.com/thlorenz/doctoc is the easiest to use. Installation was a breeze and it generated TOC's for README.md as well as CHANGELOG.md. It changes the files without committing anything via git, so it can easily be integrated into build scripts in any way you would like.

[bwood]

Thanks Jan. I'll give this a try. Appreciate your help!