Joli Table of Contents is a table of contents plugin for WordPress. It stands out by its high potential in customization.
The default look of the table of contents is rather simple and will blend well with most themes. However, under the hood Joli Table of Contents has been designed to be fully customizable.
In this article, I will customize an exemple table of contents from scratch, by leveraging Joli Table of Contents’ advanced customization features.
The default table of contents
In our example, we will use the default “Basic Light” theme. This is how it looks like with the default settings:
Basic styles: borders / rounded corners / colors
The first we are going to do to get a more custom look using the plugin’s settings is the following:
- Add a border
- Round the corners
- Change some colors
Custom border
To add a border, let’s go to the settings page. Under STYLES > TABLE OF CONTENTS, let’s set the Border to 3px on each side.
Next, we are going to set the Border radius to 12px on each corner. This setting will make the corners rounded.
Now let’s give a custom color to the border, and this is how the settings look like so far:
At this point, our table of contents looks like this:
Table of contents colors
For our style, we want to have a blue colored header with the table of contents title in white and a white background for the table of contents body (behind the headings).
Under STYLES > TABLE OF CONTENTS, let’s set the table of contents Background color to our custom blue color (#5838e9). This will make the whole table of contents blue.
Under STYLES > TABLE OF CONTENTS TITLE, let’s set the table of contents Title color to white (#ffffff).
What we want to do now, is to set a different body color. Let’s make it white, and slightly transparent to bring out a tiny bit of a blue shade.
Under STYLES > TABLE OF CONTENTS BODY, we are setting a white, with an opacity of 96%.
If you are wondering why I did not just change the Header background color, it’s because of the table of contents border that we set. In this particular case, the anti-aliasing from the rounded corners was creating a small, but noticeable hair thin white line near the corners. So by setting the blue background color at a deeper level (the TOC root), it prevents this visual defect from happening.
The table of contents now looks like this:
Because of the blue color around the heading area, the space between the TOC title and the headings looks narrower. Let’s fix this by setting a Margin bottom to the Header.
Under STYLES > TABLE OF CONTENTS HEADER, we are setting the bottom Margin to 14px.
Finally, let’s change the headings color to match our table of contents color.
Under STYLES > HEADINGS TEXT LINK, we are setting the Color to our custom blue.
This is what the table of contents looks like at this point:
Increase spacing between headings
In order to make the table of contents look less packed, we are now going to increase the space between the headings.
Under STYLES > HEADINGS TEXT LINK, we are setting the Padding top and bottom to 5px each, to keep it even. We are using padding instead margin in this case because it will provide more area to the heading to click on.
The table of content now looks like this:
Custom background image
Let’s push the customization a little further now by using some custom CSS. The goal here is to set a custom background pattern on top of our slightly transparent white body background.
To make things simple, we are going to use an SVG pattern generator like Pattern Monster, and all we have to do is to pick a pattern, customize colors (make sure to adjust transparency).
The website lets you copy the corresponding CSS code by a click of a button but because it is not possible to save HTML in the settings, we need to encode the SVG in base 64.
The website fffuel.co lets you do that easily. Just import or paste your SVG, and it will generate automatically the corresponding URL string that we can use for our CSS.
To make our table of contents body have this custom background, we need to target it with CSS using the .wpj-jtoc--body class. All we have to do now is to paste the base 64 encoded CSS code generated and here we have our CSS rule:
Under STYLES > CUSTOM CSS, let’s just paste this custom CSS.
.wpj-jtoc--body {
background-image: url("data:image/svg+xml;base64,PHN2ZyBpZD0ncGF0dGVybklkJyB3aWR0aD0nMTAwJScgaGVpZ2h0PScxMDAlJyB4bWxucz0naHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmcnPjxkZWZzPjxwYXR0ZXJuIGlkPSdhJyBwYXR0ZXJuVW5pdHM9J3VzZXJTcGFjZU9uVXNlJyB3aWR0aD0nMjAnIGhlaWdodD0nMjAnIHBhdHRlcm5UcmFuc2Zvcm09J3NjYWxlKDIpIHJvdGF0ZSgwKSc+PHJlY3QgeD0nMCcgeT0nMCcgd2lkdGg9JzEwMCUnIGhlaWdodD0nMTAwJScgZmlsbD0naHNsYSgwLCAwJSwgMTAwJSwgMCknLz48cGF0aCBkPSdNMC0xMEMtLjAxMS00LjQ5LTQuNDg1LjAzLTEwIC4wMy00LjQ4NS4wMy0uMDExIDQuNDkgMCAxMCAuMDExIDQuNDk4IDQuNDkzLjAwMSAxMC0uMDEgNC40OTMtLjAyLjAxMi00LjQ5OCAwLTEwem0wIDIwYy0uMDExIDUuNTEtNC40ODUgMTAuMDMtMTAgMTAuMDMgNS41MTUgMCA5Ljk4OSA0LjQ2IDEwIDkuOTcuMDExLTUuNTAyIDQuNDkzLTkuOTk5IDEwLTEwLjAxQzQuNDkzIDE5Ljk4LjAxMiAxNS41MDIgMCAxMHptMjAtMjBDMTkuOTg5LTQuNDkgMTUuNTE1LjAzIDEwIC4wM2M1LjUxNSAwIDkuOTg5IDQuNDYgMTAgOS45Ny4wMTEtNS41MDIgNC40OTMtOS45OTkgMTAtMTAuMDEtNS41MDctLjAxLTkuOTg4LTQuNDg4LTEwLTkuOTl6bTAgMjBjLS4wMTEgNS41MS00LjQ4NSAxMC4wMy0xMCAxMC4wMyA1LjUxNSAwIDkuOTg5IDQuNDYgMTAgOS45Ny4wMTEtNS41MDIgNC40OTMtOS45OTkgMTAtMTAuMDEtNS41MDctLjAxLTkuOTg4LTQuNDg4LTEwLTkuOTl6JyAgc3Ryb2tlLXdpZHRoPScxJyBzdHJva2U9J2hzbGEoMjU5LCA1OSUsIDU5JSwgMC4wNCknIGZpbGw9J25vbmUnLz48cGF0aCBkPSdNMTAgMEM5Ljk4OSA1LjUxIDUuNTE1IDEwLjAzIDAgMTAuMDNjNS41MTUgMCA5Ljk4OSA0LjQ2IDEwIDkuOTcuMDExLTUuNTAyIDQuNDkzLTkuOTk4IDEwLTEwLjAxLTUuNTA3LS4wMS05Ljk4OC00LjQ4OC0xMC05Ljk5eicgIHN0cm9rZS13aWR0aD0nMScgc3Ryb2tlPSdoc2xhKDI1OSwgNTklLCA1OSUsIDAuMDQpJyBmaWxsPSdub25lJy8+PC9wYXR0ZXJuPjwvZGVmcz48cmVjdCB3aWR0aD0nODAwJScgaGVpZ2h0PSc4MDAlJyB0cmFuc2Zvcm09J3RyYW5zbGF0ZSgwLDApJyBmaWxsPSd1cmwoI2EpJy8+PC9zdmc+");
}
Here is our table of contents with a custom background:
Custom styles for specific headings depth
Let’s keep pushing our customization journey by leveraging another built-in capability of Joli Table of Contents.
For each generated heading, Joli Table of Contents automatically “tags” it with a specific depth class. This way, it is easy to target different depth for styling.
The way it works is the following: if the heading is of type H2, it will get the .--jtoc-h2 CSS class. if the heading is of type H3, it will get the .--jtoc-h3 CSS class, and so on until H6 depth.
From there, and because of the way Joli Table of Contents works, we need to create a specific CSS rule to target specific heading depth. We cannot just use the .--jtoc-h2 class by itself or it will give an unwanted result.
Here is the rule that you need to follow: .--jtoc-h2>.wpj-jtoc--item-content a
This rule targets all headings of type H2, and all links contained within .wpj-jtoc--item-content, directly after the .--jtoc-h2 element.
In the following example, we are going to style every heading of type H2, and make the font weight to be bold.
The custom CSS needs to be pasted in the Custom CSS section of the settings.
.wpj-jtoc .--jtoc-h2>.wpj-jtoc--item-content a {
font-weight: bold;
}
This is what the Table of contents looks like now:
Custom HTML after specific headings
Now, to go even further, we are going to create a visual “separation” between each heading of type H2. For simplicity’s sake, we are going to create a simple horizontal line.
To achieve this, we are going to leverage the built-in action hooks and insert custom HTML dynamically.
For this specific task, the most appropriate hook is joli_toc_before_begin_item_content. When the hook is triggered, it comes with a variable ($args) containing the current heading information while it’s being processed.
$args is an Array and contains the following offsets:
$args['id'] // The heading id (its html anchor)
$args['title'] // The heading title as it will show
$args['counter'] // The heading counter (1, or 1.1, or 2.1.1, etc)
$args['depth'] // The heading depth (from 2 to 6)
$args['url'] // Optional url that would override the idWe can the use this to have a fine control over the way our custom HTML will be inserted.
Our goal is to insert an horizontal line before each heading of type H2, except for the first one.
To do that, we are making sur that the counter must be different from “1” which corresponds to the very first heading. The second condition will be matched against the depth. We only want depth of level 2.
The following snippet must be placed in your theme’s functions.php.
add_action('joli_toc_before_begin_item_content', function ($args) {
//Skip first heading and only process H2 headings
if ($args['counter'] != '1' && $args['depth'] == 2){
echo '<hr>'; //Horizontal line
}
}, 10, 1);
Here is our table of contents now with the horizontal lines:
Custom bullet points instead of standard numeration
To give a more unique look to our table of contents, we are going to get rid of the numeration, and instead, we want to have custom bullet points shaped as a pill.
First of all, we need to turn off the numeration in the settings:
The next step is to use another action hook in order to inject custom HTML right before each heading.
The hook that we need for this is joli_toc_after_begin_item_link.
The following snippet must be placed in your theme’s functions.php.
add_action('joli_toc_after_begin_item_link', function ($args) {
echo '<span class="pill-bullet"></span>'; // Custom HTML that will be inserted before each heading
}, 10, 1);
The second step in this process is to give some styles to the .pill-bullet class so that our pill shaped bullet point actually show up.
In the Custom CSS section, we are going to add this rule that will render a “green pill” :
.pill-bullet {
display: inline-block;
width: 20px;
height: 8px;
background: #34ddb4;
margin-right: 10px;
border-radius: 10px;
}
We can see here that the numeration has been replaced by our custom HTML. If we wanted to, we could add more complexity and have different colors or shapes per heading depth.
Add a custom link at the bottom of the Table Of Contents
Still using action hooks, let’s see how we can add a custom link to the bottom of our TOC. This link will be present on every single TOC.
The hook that we need for this is joli_toc_after_headings.
In this example, out link will be wrapped in a div with some inline styles to make the link centered. The following snippet must be placed in your theme’s functions.php.
add_action('joli_toc_after_headings', function ($args) {
echo '<div style="text-align:center;width:100%"><a href="https://my-custom-link.com" class="ext-link">External link</a></div>';
}, 10, 1);
Still in the Custom CSS section, we are going to give some basic style to our text link :
a.ext-link {
text-transform: uppercase;
font-size: 10px;
font-weight: 700;
color: gray;
}
And voilà ! Here is our table of contents with the link at the bottom:
Altering headings
This is another advanced feature that you can use to have full control over your headings.
Whether you want to target a specific keyword or add a random string, you can use the joli_toc_headings filter hook to alter the actual output.
In the following example, we are going to remove the vowels from every heading. It is not really useful, but it is just to demonstrate how it’s done and so you can use the same pattern for a more useful application.
The following snippet must be placed in your theme’s functions.php.
add_filter('joli_toc_headings', 'filter_headings', 10, 2);
function filter_headings( $headings ){
$headings = array_map(function($heading){
//Remove vowels from titles
$heading['title'] = preg_replace("/[aeiouAEIOU]/", "", $heading['title']);
return $heading;
}, $headings);
return $headings;
}
Here is the table of contents with the vowels removed from the headings !
Another similar example, but this time the function will remove any combination of a number and a dot at the start of a heading.
For instance, “2. Top 5 pets for a big backyard” would become “Top 5 pets for a big backyard”. This would give a cleaner look at the table of contents when there is already the numeration activated and you have some random headings in the page that contain numbers.
add_filter('joli_toc_headings', 'filter_headings', 10, 2);
function filter_headings( $headings ){
$headings = array_map(function($heading){
//Remove first number and dot from titles
$heading['title'] = preg_replace("/^\d+.\s+/", "", $heading['title']);
return $heading;
}, $headings);
return $headings;
}
Conclusion
As you can see, there are many ways to customize Joli Table of Contents. Some customizations require a little bit of code but there are already plenty of customizations available from the settings.
Joli Table of Contents bundle a large array of hooks that allow for extensive customization. Make sure to have a look at the documentation to have a good outlook of what’s possible to achieve.
Keep in mind that all the customizations shown in this article work for both the Free and the Pro version of Joli Table of Contents.