jekyll-toc
Installation
Add jekyll-toc plugin in your site's Gemfile
.
gem 'jekyll-toc'
And add the jekyll-toc to your site's _config.yml
.
gems:
- jekyll-toc
Set toc: true
in your posts.
---
layout: post
title: "Welcome to Jekyll!"
toc: true
---
Usage
There are three Liquid filters available now, which all should be applied
to some HTML content, e.g. the Liquid variable content
available in
Jekyll's templates.
1. Basic Usage
toc
filter
Add 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_only
and inject_anchors
filters.
toc_only
filter
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.
inject_anchors
filter
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.
Generated Table of Contents HTML
jekyll-toc generates Unordered List. The final output is as follows.
Heads-up: As of v0.3, nested toc has been supported. If you update jekyll-toc from 0.2 to 0.3, please check upgrade guide
<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>
It looks like the image below.
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
.
That way, one can tune the depth of the TOC displayed on the site.
The following CSS will display only the first two heading levels and hides
all other links:
.toc-entry.toc-h1,
.toc-entry.toc-h2
{}
.toc-entry.toc-h3,
.toc-entry.toc-h4,
.toc-entry.toc-h5,
.toc-entry.toc-h6
{
display: none;
}