I just uploaded the GitHub TOC Service version 0.2.0. Mostly because I needed a break from testing the next version of Marked, but also because it had a few bugs that needed fixing.

This is a Service that scratches an itch for me when working on long README files and other Markdown documents. From the original post:

…a script that works from the command line or as a Service. You can pipe Markdown to it, run it on a file, or select it and change it in place with the Service. You just put a [toc] tag in your document where you want the Table of Contents to go, and then run it. Any headers found after the point where the tag is will be indexed and linked

What’s new/fixed

  • You can use “mmd” in the tag
    • [toc 2 mmd] creates a 2-level-deep header using MultiMarkdown style header ids instead of github-dash-format
  • use mmd or no_mmd on the command line

    github_toc 2 mmd README.md
  • Remembers depth and header style (stored in HTML comment) for repeat runs
    • update an existing Table of Contents without having to specify settings again, just select and run
  • CLI arguments override “recorded” settings (no_mmd will erase mmd in tags)
  • If there’s more than one h1, it recognizes them as sections
  • Fixes for github header id generation formatting
  • Defaults to 2 levels instead of 1 if no depth is specified
  • Fixed outputting to a second file without needing redirection on the command line


The CLI version is updated, and the Service can be downloaded below (double click to install on OS XMountain Lion or higher).

GitHub TOC Service v0.2.0

A Service for generating tables of contents for GitHub readmes (and other Markdown files).

Published 07/01/14.

Updated 11/07/14. Changelog

DonateMore info…

As a side note, here’s another take on the process using only curl and awk to pull GitHub READMEs down and parse out a Table of Contents.