jekyll-toc

by N7K4 GitHub

Table of Contents

• Installation
• Usage
  • 1. Basic Usage
  • 2. Advanced Usage
• Generated HTML
• Default Configuration
• Customization
  • TOC levels
  • Skip TOC
  • Skip TOC Section
  • CSS Styling
  • Custom CSS Class

Installation

Add jekyll-toc plugin in your site's Gemfile, and run bundle install.

gem 'jekyll-toc'

Add jekyll-toc to the gems: section in your site's _config.yml.

plugins:
  - jekyll-toc

Set toc: true in posts for which you want the TOC to appear.

---
layout: post
title: "Welcome to Jekyll!"
toc: true
---

Usage

There are three Liquid filters, which can be applied to HTML content, e.g. the Liquid variable content available in Jekyll's templates.

1. Basic Usage

toc filter

Add the toc filter to your site's {{ content }} (e.g. _layouts/post.html).

{{ content | toc }}

This filter places the TOC directly above the content.

2. Advanced Usage

If you'd like separated TOC and content, you can use {% toc %} tag (or toc_only filter) and inject_anchors filter.

{% toc %} tag

Generates the TOC itself as described below. Mostly useful in cases where the TOC should not be placed immediately above the content but at some other place of the page, i.e. an aside.

<div>
  <div id="table-of-contents">
    {% toc %}
  </div>
  <div id="markdown-content">
    {{ content }}
  </div>
</div>

⚠️ {% toc %} Tag Limitation

{% toc %} can be available only in Jekyll Posts and Jekyll Collections. If you'd like to use {% toc %} except posts or collections, please use toc_only filter as described below.

<div>
  <div id="table-of-contents">
    {{ content | toc_only }}
  </div>
  <div id="markdown-content">
    {{ content | inject_anchors }}
  </div>
</div>

inject_anchors filter

Injects HTML anchors into the content without actually outputting the TOC itself.

They are of the form (usage of octicons as icon collection):

<a class="anchor" href="#heading1-1" aria-hidden="true">
  <span class="octicon octicon-link"></span>
</a>

They are of the form (unicode symbol):

<a class="anchor" href="#heading1-1" aria-hidden="true">
  &#128279;&nbsp;
</a>

This is useful when the TOC itself should be placed at some other location with the toc_only filter.

The second usecase is when you want to share a link to the page and link directly to the headline / section.

There is a new configuration inject_anchors_content key, possible values are (or what you prefer)

• 🔗  (default) to add a unicode symbol (chain) for an link
• <span class="octicon octicon-link"></span> to use the octicon icon
• an empty string or a space is for hide the anchor

Generated HTML

jekyll-toc generates an unordered list. The HTML output is as follows.

<ul class="section-nav">
  <li class="toc-entry toc-h1"><a href="#heading1">Heading.1</a>
    <ul>
      <li class="toc-entry toc-h2"><a href="#heading1-1">Heading.1-1</a></li>
      <li class="toc-entry toc-h2"><a href="#heading1-2">Heading.1-2</a></li>
    </ul>
  </li>
  <li class="toc-entry toc-h1"><a href="#heading2">Heading.2</a>
    <ul>
      <li class="toc-entry toc-h2"><a href="#heading2-1">Heading.2-1</a>
        <ul>
          <li class="toc-entry toc-h3"><a href="#heading2-1-1">Heading.2-1-1</a></li>
          <li class="toc-entry toc-h3"><a href="#heading2-1-2">Heading.2-1-2</a></li>
        </ul>
      </li>
      <li class="toc-entry toc-h2"><a href="#heading2-2">Heading.2-2</a></li>
    </ul>
  </li>
</ul>

Default Configuration

toc:
  min_level: 1
  max_level: 6
  no_toc_section_class: no_toc_section
  list_class: section-nav
  sublist_class: ''
  item_class: toc-entry
  item_prefix: toc-

Customization

TOC levels

The toc levels can be configured on _config.yml:

toc:
  min_level: 2 # default: 1
  max_level: 5 # default: 6

The default level range is <h1> to <h6>.

Skip TOC

The heading is ignored in the toc when you add no_toc to the class.

<h1>h1</h1>
<h1 class="no_toc">This heading is ignored in the toc</h1>
<h2>h2</h2>

Skip TOC Section

The headings are ignored inside the element which has no_toc_section class.

<h1>h1</h1>
<div class="no_toc_section">
  <h2>This heading is ignored in the toc</h2>
  <h3>This heading is ignored in the toc</h3>
</div>
<h4>h4</h4>

Which would result in only the <h1> & <h4> within the example being included in the TOC.

The class can be configured on _config.yml:

toc:
  no_toc_section_class: exclude # default: no_toc_section

Configuring multiple classes for no_toc_section_class is allowed:

toc:
  no_toc_section_class:
    - no_toc_section
    - exclude
    - your_custom_skip_class_name

CSS Styling

The toc can be modified with CSS. The sample CSS is the following.

.section-nav {
  background-color: #fff;
  margin: 5px 0;
  padding: 10px 30px;
  border: 1px solid #e8e8e8;
  border-radius: 3px;
}

Each TOC li entry has two CSS classes for further styling. The general toc-entry is applied to all li elements in the ul.section-nav.

Depending on the heading level each specific entry refers to, it has a second CSS class toc-XX, where XX is the HTML heading tag name. For example, the TOC entry linking to a heading <h1>...</h1> (a single # in Markdown) will get the CSS class toc-h1.

Custom CSS Class

You can apply custom CSS classes to the generated <ul> and <li> tags.

toc:
  # Default is "section-nav":
  list_class: my-list-class
  # Default is no class for sublists:
  sublist_class: my-sublist-class
  # Default is "toc-entry":
  item_class: my-item-class
  # Default is "toc-":
  item_prefix: item-