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
Step 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
Step 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
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:
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
Step 1: Add this plugin to your
Gemfile, which helps Jekyll to scan all plugins to serve.
Step 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.
Step 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.
Step 4: Adding this line to your post layout, in my case is
Step 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.
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.
Step 1: Downloading the project jekyll-table-of-contents from GitHub using this
Step 2: Place the
_layout/post.html. Place this line anywhere in that file:
Step 4: Calling TOC in each Jekyll post. To call it, we will need to add this line to every post file ends with
Step 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
You can also use CSS to style it
You can customize title, headers to show, … in
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.