Github Table of Contents Hack Screenshot

A Github Table of Contents Hack

This was originally a StackOverflow question. And it was also turned into a Github Gist.

For large pieces of documentation, it's pretty much typical to create a Table of Contents (TOC) in Markdown — usually in the README.md file itself. This is usually automated through IDE extensions and the result ends up being a nested bulleted (<ul>) or numbered list (<ol>). It usually looks like this:

That's really not ideal, because the bullet points are just unnecessary noise, boilerplate. With CSS, you could add a list-style-type: none; and have the problem disappear. However, Github tries its best to cleanse the user's custom styling, lest they could completely distort Github's content and UI/UX, which completely reasonable. In the second item of Github Markup's process for each repository:

(...) aggressively removing things that could harm you and your kin—such as script tags, inline-styles, and class or id attributes.

Thanks to the Waylan StackOverflow user for pointing out Github Markup's existence and relevance to this specific problem.

However, they aren't doing that aggressively enough. After about half an hour trying to bypass these restrictions and trying every HTML/CSS way I knew to style this list, I stumbled upon a that almost did the trick. The only problem was that Github was leaving the style tag in-line on the final document as text — something like this: <style> #TOC ul { list-style-type: none; } </style>.

After insisting that there should be a hack somewhere, I tried examining the HTML code with the browser inspector. And there I found the hack, the user-content-toc ID. Maybe Github wanted to release this feature at some point for their Markdown "compiler" but couldn't for some reason. At any rate, the final hack/solution is to wrap your list with a <div> and then add the user-content-toc ID:

        <div id="user-content-toc">
  <ul>
    ...
  </ul>
</div>

Custom TOC — Less boilerplatey Table of Contents on Github.

Keep in mind that this will surely not be ideal. Because Github might change the id at any point in time, which would break your styling. Nevertheless, in the case this id disappears, at the worst, things will simply default to <ul> — which is not as bad as the case where they completely distort the <ul>'s behavior, so watch out!