GitHub Pages can't run custom Jekyll plug-ins so when generating Tables of Contents (TOCs), you're stuck with either a JavaScript solution or using kramdown's {:toc} option. However, by using {:toc}, you are forced to have that code next to your actual markdown and you can't place it in a layout. This means every. single. post. will need to have the snippet. If you choose the JavaScript approach, that's perfectly fine but what if JS is disabled on someone's browser or your page is just really long and it becomes inefficient.

Instead, I wrote this solution entirely in Liquid and can be used as an {% include %} in any website you want, in any layout you want. Want to see it in action? Here are some awesome websites that I know of using this solution ❤️.

• the docs.docker.com website
• the UK Ministry of Justice Technical Guidance site
• "Minimal Mistakes" Jekyll Theme
• Apache's Beam and PDFBox websites
• JetBrains' OSS Jekyll Theme
• Bitcoin.org
• CloudCannon
• British Antarctic Survey
• Travis CI Docs
• the City of Amsterdam
• Intuit's Karate
• Duality's developer docs
• "Bulma Clean" Jekyll Theme
• The Google APIs team homepage, Google AIP website and API Linter project
• Shopify App CLI Extensions
• AWS' Open Distro for Elasticsearch Documentation

For more information regarding how this include works, read the blog post.

Want anchors next to your Jekyll headings without JavaScript or a plug-in?

Check out the sister project over at allejo/jekyll-anchor-headings.

Alright, so how do you use it?

1. Download the toc.html file from the latest release or the master branch

2. Toss that file in your _includes folder.

3. Use it in your template layout where you have {{ content }} which is the HTML rendered from the markdown source with this liquid tag:

   {% include toc.html html=content %}

This snippet is highly customizable. Here are the available parameters to change the behavior of the snippet.

^* This is a required parameter

• baseurl has been deprecated since 1.1.0, use base_url instead
• skipNoIDs has been deprecated since 1.1.0, use skip_no_ids instead

The performance impact of this snippet on your site is pretty negligible. The stats below were gotten from Jekyll's --profile option.

Filename                              | Count |      Bytes |    Time
--------------------------------------+-------+------------+--------

# performance on docs.docker.com from ~Feb 2017
_includes/toc.html                    |   813 |    524.17K |  6.422

# performance on the "Minimal Mistakes" Jekyll theme
_includes/toc.html                    |    94 |     29.43K |  0.413

This snippet may be redistributed under either the BSD-3 or MIT licenses.