How to Manually Create Table of Contents on Gutenberg

Wondering how to manually create table of contents on Gutenberg? This tutorial is going to show you what you want to know. But before I start with the tutorial, let me ask you a question.

Why do you think you should have a table of contents on your blog posts? The simple answer to this question is “enhanced user experience.”

Guess what? User experience is now becoming an important metric for ranking. As Google is all set to roll out the new algorithm update, you should be ready.

Of course, core web vitals have nothing to do with a table of contents, but adding one is going to improve the experience for your users.

If you are using a table of contents for you blog posts, Google is going to show ‘Jump to’ link in SERPs or Search Engine Results Pages.

This is what it looks like:

The ‘jump to’ link help users to jump directly to the segments relevant to them instead of scrolling through an entire webpage.

This ability to locate the content that matters most improves user experience.

Okay, now that I have established why you should use table of contents, I will like to mention that while TOC or table of contents can improve user experience, they don’t have any real impact on the page ranking.

So, you may decide to ditch table of contents altogether. That’s fine! Google isn’t going to grab you by the neck and neither is it going to hit your website with reduced ranking.

Okay, time for the tutorial ladies!

Problems of Using a TOC Plugin

Let me get to the point straightaway. Here are the problems:

• You add an extra plugin, which consumes extra memory. This is not desirable if you are a shared hosting.
• The extra plugin that you add may be terribly coded, making your website vulnerable to online threats.
• The plugin developer may stop active development of the plugin, leading to conflict with latest version of WordPress you are using.
• The plugin may conflict with other plugins on your website.
• The plugin may not give you the ability to modify its design, and it may very well look out of place when compared with the rest of your website.

Since there are multiple issues that you can face, it is often wise to manually create table of contents on your WordPress site.

Yes, it is a manual process, and hence, a time-consuming laborious process that can frustrate you. But if you do this, no matter how mundane and frustrating it may feel, you will successfully eliminate every problem that comes with using a TOC plugin.

Steps to Manually Create a Table of Contents

There are several steps involved in manually creating a table of contents. Let’s start!

First Step: Write Your Content Properly

The first thing you need to do is write your content and break it in segments using headings. You can use H2, H3, H4, H5, H6 headings.

Usually, you should not include so many headings as that may turn out to be confusing. Here is a sample of how you should create your content:

Formatting your content is essential. You will use the H2, H3, etc. tags for creating the table of contents.

Second Step: Add HTML Anchor Tag

Every step from here is vital and requires your keen attention. If you make mistakes, the process will not work.

In this step, every heading (H2, H3, etc.) that you created will get an HTML tag.

For that, select the heading. On the right, the block element will be selected immediately. On that block element segment, click on the Advanced tab to expand it, and then add an HTML anchor.

You can use one or two words for the anchor. There shouldn’t be any space between the words. If you don’t know what words to use, simply write the entire heading with each word separated by an underscore. Make sure that all the words are in small letters.

So, if the heading in the example is This is the First Heading, the anchor text will be this_is_the_first_heading. You can add different words like my_first_heading or just about anything you want. Make sure that it is unique and there is no white space between the two words.

Do this for every damn heading you create irrespective of whether it is H2 or H3 or H4.

So, in this example, I will take four H2 headings and four H3 headings.

This is how I create HTML tags for each heading:

Heading (H2)	HTML Tag
This is the First Heading	this_is_the_first_heading
This is the Second Heading	this_is_the_second_heading
This is the Third Heading	this_is_the_third_heading
This is the Fourth Heading	this_is_the_fourth_heading
Final Conclusion	Final_conclusion
Heading (H3)	HTML Tag
This is a subheading using h3 tag	this_is_a_subheading_using_h3_tag
This is another subheading using h3 tag	this_is_another_subheading_using_h3_tag
This is third subheading using h3 tag	this_is_third_subheading_using_h3_tag
This is fourth subheading using h3 tag	this_is_fourth_subheading_using_h3_tag

Third Step: Create a List

Once you have added unique HTML anchor to all the headings hit the Save Draft button to make sure that you don’t accidentally lose everything you just did.

After you have done that, go to the location where you want to place the table of contents. I prefer it to be right after the title of the article. You may want it right after first introductory paragraph.

If you want it after the title, click at the end of the title and hit the enter button on your keyboard. This will create a new paragraph block.

If you want to create the table of content after the first introductory paragraph, do the same. Click at the end of the paragraph and hit the enter button on your keyboard to create a new paragraph block.

In the paragraph block, just type in Table of Contents, or whatever name you prefer for your TOC. I prefer to keep it simple, and hence, I will use Table of Contents. This name you give will be the heading of your table of contents. Make sure that you are keeping it as a paragraph block, and that you are not converting it to any heading.

This is what it should look like:

Once you give the name, hit enter and click on the small Plus sign you see on the right to find the list block and select it.

Once you select the list block this is what you should see:

Now, start writing the list. This list will have all the headings that you created. This is how this sample list will look like:

For H2 headers, the list will be a normal list. But if you have H3 and H4 tags, you have to use indentation buttons to appropriately create the list.

Since I have only H2 and H3 tags in the sample, I used them all.

Fourth Step – Group TOC Heading and List

This is a very important step. You have to select the table of contents name block and the list block and group them together.

To select the two blocks at once, click on any one of the two blocks and hold down the shift key on your keyboard and then click on the other block. Once you do that this is what it will look like:

Once the two blocks are selected, you will notice the option for changing the type of those two blocks.

Click on the small icon you see on the top (highlighted using a red box) and then select Group.

Once you click on the Group option, the two blocks will be converted into a Group block. Do that!

When you do that, this is what it will look like:

Notice the small Plus button inside the group. That indicates a new paragraph block inside the group. That should not be there. Unfortunately, it is a bug that automatically adds the appender. It is a recent bug and expect it to be removed with subsequent updates. Here is a Github thread about the issue.

Fifth Step: Add CSS Class Names

Once you have created the group, you need to add CSS class names to three things:

• Whole Group block.
• Table of contents name block.
• List block.

Here are the different blocks that need CSS class name:

Adding CSS Class to Group Block

Let’s start with the group block. Select the entire group block and then in the right panel, switch to advanced tab and in the Additional CSS Class(es) area, enter the following:

base-table-of-contents

I used the term base. You can use anything else. You can use your website’s name. A few things to notice here:

• The words you use to give the CSS class name should not have any white space between them.
• The words should be in small letters.
• The words should be separated by a hyphen.

Adding CSS Class to Table of Contents Name Block

Now click on the name block of table of contents and add a CSS class in the Additional CSS Class(es) field.

Again, I used the term base. You can use your website’s name. Make sure that the term you are using is same as that of the group block.

This is the CSS class name I used:

base-toc-heading

As before, there shouldn’t be white spaces between the words and they should be separated using a hyphen. Also, they must be in lowercase.

Adding CSS Class to List Block

Finally, add a CSS Class name to the list group in the same way. Click on the list block and add the name in the Additional CSS Class(es) field.

The CSS Class that I used here is base-toc-contents. The same rules of no white space, lowercase, and hyphens apply here.

Sixth Step: Link Insertion

This is the last step for the table of contents. However, if you want, you can go ahead and style the table of contents to make it more pleasing visually.

Before I show you how to style your table of contents, let’s finish making the table of contents first. As I said, the last step is to insert links into the list block to ensure that each item becomes clickable.

To do this, go to the list block and click on any individual list item and select the entire item. Then click on the hyperlink icon that appears.

Clicking on the icon will bring up the option of inserting the link. This is where you insert the HTML anchor tag for that particular item and prepend it with the hash or the pound symbol.

This is what I mean:

DO NOT make the link open in a new tab. That’s now a desirable thing to do. Clicking on table of contents’ link should keep you on the same page. DO NOT mark the link as Nofollow or Sponsored.

Once you added the link, click on the back arrow symbol you see next the link. This will insert the link and make the item clickable.

In the image above, you will notice that the first item is now a link. On the frontend, it will be a clickable item.

Follow this for all the other items on the list. The end result should look like this:

Now, publish your post and view it (or save draft and preview it). The table of content should appear on the post.

This is how the frontend looks like:

You may decide to keep it like this, or if you want, you may beautify it to follow the overall design language of your website.

I prefer to design it!

Let’s go through the design part!

Beautifying the Manually Created Table of Contents

The reason why I added CSS class names in the fifth step above was for this part. If you don’t want beautification, you can completely shun the fifth (5^th step above) and jump directly to the sixth step.

CSS stands for cascading style sheet. This is the coding that you use for beautifying a website. Thinks like adding borders, colors, etc. can be done using CSS.

I will be using the CSS Class names that I added in the 5^th step.

Here is the CSS code I use:

/* Table of Contents Styling */

.base-table-of-contents {

border: 1px dotted #009edd;

background: #fff;

}

.base-toc-heading {

font-weight: 500;

font-size: 26px;

}

ul.base-toc-contents {

margin-top: -1em!important;

}

.base-toc-contents li {

list-style-type: none;

position: relative;

margin-bottom: 5px;

}

.base-toc-contents a {

font-size: 20px;

color: #009edd;

}

.base-toc-contents a:hover {

color: #rfe572;

}

.base-toc-contents li:before {

content: “»”;

margin-right: 1em;

color: #585858;

left: -20px;

position: absolute;

}

Just copy and paste the code in the Additional CSS or Custom CSS segment in the live customizer. You can access live customizer from WordPress Dashboard >> Appearance >> Customize.

The above CSS code transforms the mundane looking table of content into this:

You are free to play with the CSS code and change parameters to make it more suitable for your website.

IMPORTANT THING TO NOTE: Slight Automation

Guess what? If you want to manually enter TOC for every post, you have to repeat this process. But when it comes to the fifth step (adding CSS Class Names to the Group Block, Table of Contents Name Block, and List Block), keep the CSS Class Names identical.

I will repeat! DO NOT CHANGE THE CSS CLASS NAMES.

By not changing the CSS Class Names you will ensure that you don’t have to style each TOC separately. The styling you add for the first time becomes universal and it will automatically apply to all TOCs you create in the future.

This is an example of a different TOC using the same CSS Class Names:

Further Customization: Smooth Scroll

Now, the table of content you just made works perfectly fine expect that there is one detail missing. When you click on a link in the table of content, it will abruptly jump to the relevant segment. That is perfectly fine. It doesn’t impact readability or user experience in any way.

However, there is a scope of enhancing the user experience even further. You can create smooth scroll so that when someone click on a link in the table of contents, it smoothly scrolls to the relevant segment instead of making an abrupt jump.

But remember, achieving smooth scroll will mean that you have to add additional code to your site. It is better not to do that.

Adding Smooth Scroll to Any Site

If you still insist for smooth scroll, here is a small script developed by Chris Ferdinandi:

<script src = “https://cdn.jsdelivr.net/gh/cferdinandi/smooth-scroll/dist/smooth-scroll.polyfills.min.js”></script>

<script >

var scroll = new SmoothScroll(‘a[href*=”#”]’, {

speed: 500,

speedAsDuration: true,

offset: 70 // Set offset if you are using fixed header

});

</script>

You need to add this script to the footer of your website. It really doesn’t matter which WordPress theme you are using. You can always add this script.

As of today, some themes come with the built-in ability to add scripts to the header or the footer segment of the site.

If your theme doesn’t have that option, you can install a simple plugin called Insert Headers and Footers.

But this is quite ironic! You will add a plugin to add smooth scroll to your manually created table of contents. In such a case, don’t you think that using a table of contents plugins is much better? That will save you a whole lot of time.

Anyway, if you are installing the plugin, just add the code in the Scripts in Footer section and hit the save button! That’s it!

If you are unhappy with the scroll speed for some reason, just change the default speed (which is set to 500) in the script.

Adding Smooth Scroll to GeneratePress

In case you are using GeneratePress theme, you don’t need to add any plugin. The theme will allow you to add the script using the Hook element. To use the Hook element, you need to have the premium version of the GeneratePress theme.

Assuming that you are using the premium version of GeneratePress, first activate the Elements module.

Once you activate the module, go to WordPress >> Dashboard >> Appearance >> Elements.

Click on the Add New Element button on the top and then select hook and then click on the Create button.

Name the element as Smooth Scroll and copy and paste the script above in the field you see. Also, in the settings segment below, select wp_footer. Leave everything else untouched. This is what you will see:

Now, go to the Display Rules segment and in the location field, select entire site. This is what I mean:

Now, hit the Publish button! That’s it! Smooth scroll is now active on your site and your table of contents should follow the rule. Go ahead and test it! It looks nice. The abrupt jump will be gone and the page will not scroll smoothly when anyone clicks on a link in the table of contents.

Table of Contents FAQ