Add Dynamic Table of Contents to a Series of WordPress Posts

Last updated November 15th, 2018 at 09:11 am

When I’m writing a series of posts on a subject — such as a multi-part tutorial — I like to include a table of contents for that series of posts. I think this helps readers navigate the content.

Here’s what I’m talking about:

I’ve searched unsuccessfully* for a plugin that would make this process easier than my old standard process:

(* Spoke too soon. See Update below for some plugins I found after publishing this post.)

My old standard process: As soon as I was publishing the second post in the series, I would manually hard-code a block of HTML with the title and permalink of each post and paste it in the desired place (usually up near the top) of each post. When I publish a new post in the series, I’d edit that HTML block, adding the permalink and title of the new post, paste that new HTML into the new post, and replace the HTML blocks in all the previous posts with the new HTML block. And so on.

There’s got to be a better way!

So, having failed to find a plugin, I patched together my own method. It’s not (yet) a distributable plugin. But maybe some day it will be, unless one already exists.

The solution I’ve come up with consists of two primary components:

• A custom shortcode that generates the necessary HTML
• the amr shortcode any widget plugin

The Custom Shortcode

function nwb_shortcode_toc($atts) {
	global $post;
	$atts = shortcode_atts( array(
		'ids' => '',
	), $atts, 'nwbtoc' );
	if ( empty($atts['ids']) ) {
		return;
	}
	$ids = $atts['ids'];
	$id_array = explode(',', $ids);
	$output = '<div class="nwb-toc">';
	$output .= '<h2>Posts in this Series</h2>';
	$output .= '<ol>';
	foreach ( $id_array as $id ) {
		$curr_other = ( $id == $post->ID ) ? 'current' : 'other' ;
		$output .= '<li class="' . $curr_other . '"><a href="' . get_permalink($id) . '">' . get_the_title($id) . '</a></li>';
	}
	$output .= '</ol>';
	$output .= '</div>';
	return $output;
}
add_shortcode('nwbtoc', 'nwb_shortcode_toc');

The shortcode would look like this when entered into a post:

[[nwbtoc ids="4327,4446"]]

The ‘ids’ parameter is a comma-separated list of post ID numbers.

The code in Line 15 tests whether the current item in the foreach loop corresponds to the “current” post. If it does, its li tag is given the class of “current”, which allows me to use CSS to change how that item is rendered. (Namely, I remove the text-decoration and change the cursor to “default”, so as to discourage the reader from clicking on the link for a post s/he’s currently reading.)

PS: I might extend to plugin to support variable h2 text as well as formatting of the list. Maybe later.

How the amr shortcode any widget Fits In

Note that I am not going to enter the above shortcode directly into each post in the series. If I did that, I would still have to edit each series post when a new one is added to the series. Do not want to do that!

Instead, I’m going to add the nwbtoc shortcode into the Widgets for Shortcodes sidebar. Once saved, the amr shortcode any widget plugin will assign that new widget its own shortcode (see below).

Now I can enter that shortcode into each post in the series.

When a new post is added to the series, all I have to do is add that post’s ID to the list of IDs in the Widgets for Shortcodes widget, and the table of contents in every post in the series will be updated.

Closing Thoughts

If you know of a plugin that performs this function, I’d love to know about it. Also, I welcome your feedback on the method I’ve come up with.

Update: Plugins Found

Turns out ya gotta know the right search terms to use!

When I searced for “series post list”, I found these:

https://wordpress.org/plugins/organize-series/
https://wordpress.org/plugins/series/
https://wordpress.org/plugins/post-series-manager/
https://wordpress.org/plugins/really-simple-series/
https://wordpress.org/plugins/post-series/