/jekyll-toc

A GitHub Pages compatible Table of Contents generator without a plugin or JavaScript

Primary LanguageHTML

Jekyll Pure Liquid Table of Contents

Build Status

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 the 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 ❤️.

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

Usage

Alright, so how do you use it?

  1. Download the latest toc.html file

  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 %}

Parameters

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

Parameter Type Default Description
html string * the HTML of compiled markdown generated by kramdown in Jekyll
sanitize bool false when set to true, the headers will be stripped of any HTML in the TOC
class string '' a CSS class assigned to the TOC; concat multiple classes with '.'
id string '' an ID to be assigned to the TOC
h_min int 1 the minimum TOC header level to use; any heading lower than this value will be ignored
h_max int 6 the maximum TOC header level to use; any heading greater than this value will be ignored
ordered bool false when set to true, an ordered list will be outputted instead of an unordered list
item_class string '' add custom class for each list item; has support for %level% placeholder, which is the current heading level
baseurl string '' add a base url to the TOC links for when your TOC is on another page than the actual content
anchor_class string '' add custom class(es) for each anchor element

* This is a required parameter

Performance

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

License

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