How to Add Table of Contents to Jekyll Blog

In lengthy blog entries with a lot of depth, a table of contents is a useful component to include. It's one of the most effective strategies to allow your readers to skim through your content. With headlines, it provides a good overview of the entire article. How long will it take readers to find the area that interests them the most if they don't have that? If you're using WordPress, you can use plugins to get it easily. However, if you are using Jekyll, use this tutorial to add a Table of Contents to your Jekyll website.

Why Jekyll posts need Table of Contents?

If you are a regular reader of books or read articles and tutorials on websites, you will not be surprised to come across the Table of Contents section. It might look something like this:

So what is the benefit of adding TOC to blog sites, especially Jekyll Blog? Let's find out together:

• Enhancing user experience: If the article is really brief, a table of contents for Jekyll, or any blog for that matter, is not actually necessary. A TOC section, on the other hand, is useful for a long thorough article because it allows people to skim through your postings and read the parts that interest them.
• Improving your Jekyll blog's SEO: If you are a web developer and want to grow to be able to make money by installing Adsense on your website, then SEO is one of the issues that need to be prioritized. According to the CyberSprout study, TOC has an effect on SEO scores. When search engines (Google Bot, Bing Bot, …) crawl through your post and discover all of the necessary links to various headings at the start, it gives you a higher ranking.

Add Table of Contents to Jekyll Blog

After reading the benefits of TOC, would you like to add Table of Contents to your blog site? If yes, then you can continue reading. There are many ways to do it, but in this tutorial, I will go through three ways, choose the ways that work for you:

Option 1: Creating Table of Contents section on Jekyll using Kramdown

Implementing TOC is one of the features provided by Jekyll if you used Kramdown as your markdown processor. This is pretty simple because you needn’t have any JavaScript knowledge. To implement TOC you can follow these steps:

1. Set Kramdown as your markdown processor of choice. Jekyll on Github pages is set up to parse and convert Markdown to HTML for blog post pages using Kramdown by default. But in case, you changed it, you can reset it by replacing this line in your _config.yml:

markdown: kramdown

2. Whenever the Kramdown is set, you can now add the Table of Contents to your Jekyll posts by adding this line to the post file (ends with .md extension)

{:toc}

Now, Jekyll will replace the list with a TOC automatically generated from the headings in the content. You can also make it prettier with CSS:

#markdown-toc {
    border: 1px dash black;
    padding: 1rem;
    display: inline-block;
}

Option 2: Adding Table of Contents to Jekyll website using plugin

As you saw, my blog is built on the Jekyll platform. I chose it because it has many benefits such as speed, easy to setup, … and because Jekyll has various plugins you can install to improve your website style, performance and more. It also has a plugin called jekyll-toc. To add it, you will need to

1. Add this plugin to your Gemfile, which helps Jekyll to scan all plugins to serve.

gem 'jekyll-toc'

2. Starting the config process by adding these to the _config.yml file. This is one of the most important step, if you forget to add this line, it can take you hours to find the mistakes.

plugins:
  - jekyll-toc

3. Install this Jekyll plugin. Once you've added these lines of code, you're ready to run bundle install, this will add the project's required dependencies.

4. Adding this line to your post layout, in my case is _layout/post.html

{% toc %}

5. Tell the plugin which posts we'd like a TOC to appear in. This can be accomplished by including this line in the first paragraph of each blog post.

---
toc: true
---

In this option 2, I introduced a way to add a Table of Contents to Jekyll blog by using its plugins. You can also style it with CSS to make it more beautiful. If you don’t know how to do it, you can leave a comment below to contact me, I am very glad to help you.

Option 3: Adding Table of Contents to Jekyll with JavaScript

Compared to the two methods above, this way can help you customize the TOC in the most detail, so to do this you need to have a little knowledge of JavaScript. But don't worry, because in this tutorial I will help you to add TOC even if you don't know JavaScript. You can follow this procedure:

1. Downloading the project jekyll-table-of-contents from GitHub using this git command:

git clone https://github.com/ghiculescu/jekyll-table-of-contents/

2. Place the toc.js inside your repository. But I recommend you to put it in a directory contains all the javascript files, which will help you manage them easier.

3. To use the script, go to your Jekyll website and paste it in. Put this JavaScript file in the location where you want the TOC to appear. In most cases, the TOC is required for all posts. So I think you can call it in the post layout _layout/post.html. Place this line anywhere in that file:

<!-- change src value to path to file javascript -->
<script src="toc.js”"></script>

4. Calling TOC in each Jekyll post. To call it, we will need to add this line to every post file ends with .md extension.

--- 
layout: 
image: 
title: 
description:
---

<!-- Add this line -->
<div id="toc-post"></div>

5. Building the Table of Contents

Because TOC relies on headers, they are loaded prior to the start of TOC. So, add this line of code to the post layout that waits till the page is entirely loaded. If you don’t know where to put, you can put these lines to _layout/footer.html

<script>
    window.addEventListener('DOMContentLoaded', function () {
        $("#toc-post").toc();
    })
</script>

You can also use CSS to style it

#toc-post {
   padding: 0.5rem 0;
   margin: 1rem 0;
   line-height: 1.5; 
   background-color: #f6f6f6!important;
   border-radius: 6px;
   border: 2px solid #616161;
}

You can customize title, headers to show, … in toc.js with need JavaScript knowledge, if you want to customize it, you can learn that programming language or contact me, I will help you.

Conclusion

I hope this guide assisted you in adding a table of contents to your Jekyll blog. You can reach out to me in the comments section below if you require assistance. I look forward to seeing you in the next post.