Why Table of Contents?
I always liked the Wikipedia Table of Contents section which is present in almost every article. It gives a good insight to the whole article with headlines. Imagine, if that was not there; how hard it would be to find things that we are specifically looking for. Things like someone’s career, early life etc., Here is a sample page wikipedia page.
I have used a similar kind of TOC on my blog(at least it looks similar!). So here is the Table of Contents of this blog post.
- Why Table of Contents?
- How to add TOC for Jekyll posts?
Table of Contents for Jekyll blog or any blog for that matter is not really necessary if the article is very short. But, for a long detailed article, a TOC section provides a good insight and helps skipping to the desired topic.
How to add TOC for Jekyll posts?
There are plugins for Jekyll to generate TOC but, I have stayed away from them for one reason - I want the complete control on my website.
When I was using WordPress, there was a simple plugin called TOC and it worked like charm. It also had some color schemes available for it. But when we are dealing with Jekyll, plugins are very new and can be unstable. I’m not against Jekyll plugins or something but I’m just waiting for them to be simple to use.
Now, let’s dive in and install TOC.
You can make it look pretty by adding this style
For this to work you should be using kramdown as your markdown preprocessor. Mention this in the
_congif.yml file and restart the server to make it work.
But if this doesn’t work for you then you can follow the procedure below.
Step 1: Download necessary files
toc.js which is enough for creating Table of Contents.
Step 2: Install the script in Jekyll repository
toc.js inside your repository somewhere. Maybe inside a folder called js where all your scripts are placed.
Add this line of code in the layout file you would like the TOC to appear.
I’m using it only on my posts. So I’m calling it only on the posts layout. This is how it looks like
Step 3: Call TOC in the layout.
I personally like calling it in particular places of my articles. So I go into all my posts and paste the below line in certain places. So if you look at my posts, the Table of Contents does not belong to one fixed place. It can be in the first paragraph or second paragraph and so on.
But this is a tedious task if you have a lot of posts. It is better to place the code in the layout itself than individual posts.
Use this line of code in the layout and the TOC will load there.
I’m calling it in my post layout; just above the content.
Step 4: Initiate TOC
Before initiating Table of Contents, it is logical to wait till all the contents are loaded. Because TOC uses all the headers and it is necessary that all the headers are loaded before the initiation of TOC. So to the post layout, add this snippet of code that waits till the page is completely loaded.
Here is the complete post layout that is ready to load Table of Contents on your Jekyll posts.
This code will call the TOC function once the DOM is ready. After rendering, this is how it will look like
It may not look the same when you first set up TOC but I will give you the styling that I have used for this one which looks like Wikipedia TOC.
For some reason, the TOC section assumes the style
display: block which will cover the whole page. But I wanted it on one side of the page. So I have added the code
display: inline-block!important. I personally do not like using !important but here I had to.
Now, different markdown handlers process markdown differently. Table of Contents will create an anchor tag for every headline. But this is not supported by all the markdown processors. Kramdown is good with it but if you are using redcarpet or rdiscount you have to make some changes in the _config.yml file.
I suggest you change the markdown processor to kramdown as it is the only supported markdown engine by github pages.
Step 5: Configuration
Table of Contents by default will consider all the headers h1, h2, h3, h4, h5 and h6.
What if you don’t want any h4 or h5 displayed? Use this code in place of the one we used in Step 4.
This code will ensure that only the mentioned headers will be considered for TOC. There are also other things that you can change. If you want to know all the configurations then please visit this repository and go through instructions given.
I hope that helped you set up TOC on your website. Ask any doubts you have through comments.
Thanks for reading!
This article is written by sharath.dt Follow him @webjeda.