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
---
There are three Liquid filters, which can be applied to HTML content,
e.g. the Liquid variable content
available in Jekyll's templates.
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.
If you'd like separated TOC and content, you can use toc_only
and inject_anchors
filters.
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.
Injects HTML anchors into the content without actually outputing the TOC itself. They are of the form:
<a id="heading11" class="anchor" href="#heading1-1" aria-hidden="true">
<span class="octicon octicon-link"></span>
</a>
This is only useful when the TOC itself should be placed at some other
location with the toc_only
filter.
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>
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>
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
The toc levels can be configured on _config.yml
:
toc:
min_level: 2 # default: 1
max_level: 5 # default: 6
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-
The default level range is <h1>
to <h6>
.
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
.
Anchor injection can be customized with a liquid template:
toc:
injection_template: 'path/to/template.html'
The template is supplied with the original text content (heading_text
) and id (heading_id
) for each heading element:
<!-- Append an anchor pilcrow after the heading text, Sphinx style: -->
{{ heading_text }} <a class="anchor" aria-hidden="true" href="{{ page.url }}{{ heading_id }}">¶</a>
The above template, when injected on an <h1>
, yeilds html like the following:
<h1 id="this-is-a-heading">
<!-- Append an anchor pilcrow after the heading text, Sphinx style: -->
This is a heading <a class="anchor" aria-hidden="true" href="example.com/this/page.html#this-is-a-heading">¶</a>
</h1>