Home > Wordpress Table of Contents Plugin

Wordpress Table of Contents Plugin

Download the Plugin

You can download the plugin directly from the Wordpress plugin directory.

What Does It Do?

The Table of Contents plugin builds a table of contents from the header structure (h1-h6 html elements) in the content of your posts and pages.

The Table of Contents is built as a list (either an ordered or unordered list as you prefer) of links to each section in the post content.

For example, take the following html:

  1. <h1>Level 1</h1>
  2. <h1>Level 2</h1>
  3. <h2>Level 2.a</h2>
  4. <h3>Level 2.a.1</h3>

The table of contents built from that html would look like this:

  1. <ul>
  2.     <li>Level 1</li>
  3.     <li>Level 2
  4.         <ul>
  5.             <li>Level 2.a
  6.                 <ul>
  7.                     <li>Level 2.a.1</li>
  8.                 </ul>
  9.             </li>
  10.         </ul>
  11.     </li>
  12. </ul>

To see an example of what this looks like when it’s rendered, just look at the table of contents on this and other pages on this site. They’re all generated automatically using the plugin. Keep in mind that you can style it (using CSS) to look however you like.

So, as you can see, the plugin interprets the section hierarchy from your content based on the nesting of html header tags (h1-h6) within it.

The plugin actually does a little more than just that. First, it actually inserts anchors into the content of your post, making each it possible to link directly to each section within your content. It also makes each of the elements in the actual, generated table of contents link to the appropriate header. So, it really makes your content much easier to navigate. And it does it all for you, basically for free.

A Subtle Point

The plugin will always start building the table of contents based on “importance”. What’s importance? Well, <h1> is more important than <h2>. <h2> is more important than <h3>. <h3> is more important than <h4>. And so on through <h6>.

So, if you have an <h1> tag after an <h2> tag, and no <h1> tags before the <h2> the <h2> tag won’t show up in your table of contents because the <h1> is considered the most important element on in the page, and is therefore made to be the root of the table. Make sense? So just be aware of that.

Another Point

It’s also probably worth mentioning that any headers found within HTML comments will not be included in the table of contents. There are other ways of excluding sections of content from the table of contents which are explained below.

Usage Instructions

Installing

We’ve tried to make the plugin as easy and flexible to work with as possible.

Before you can use the plugin you have to install and enable it. You do this the same way you would any WordPress plugin.

First, download the plugin from one of the links above. Then unzip the file you downloaded onto your local computer.

Next, you need to upload the contents of that folder to the wp-content/plugins folder in your WordPress installation. After you do this you will have a folder named wp-content/plugins/wptoc-1.1.9.

The next thing to do is to open up your WordPress administration screen (/wp-admin). Go to the plugins section and enable the plugin named “Table of Contents”. After doing this you’re ready to add the TOC to your templates.

Adding it to Your Site

General Rules and Recommendations

The TOC is added to your site by including some code (which I’ll show you) inside your theme templates.

There are really only two rules for placing the Table of Contents:

  1. The TOC code must be placed within “The Loop”.
  2. The TOC code cannot be included from within the content of a page or post itself. Doing so would require a plugin to allow you to execute PHP code from within your posts (such as Exec-PHP). And including the TOC code in your post would then cause an infinite loop.

I would also make the following recommendations.

  1. Don’t display the TOC on a page that lists multiple posts, such as your blog index page (index.php)

And lastly, it’s important for you to know that the plugin assumes that each header will be unique. Equal means that the type of header and the text of the header are the same.

With that all out of the way, let’s show you how to display the TOC on your site.

Displaying Always

To add the TOC to a template you need to put the following code in your template.

  1. <?php wptoc_show_toc_as_ulist(); ?>

or

  1. <?php wptoc_show_toc_as_olist(); ?>

Displaying Conditionally

You might want to conditionally display the TOC. Here’s an example.

  1. <?php if(TRUE === wptoc_has_toc()) { ?>
  2.     <div id="toc">
  3.         <div id="contents">Contents</div>
  4.         <?php wptoc_show_toc_as_ulist(); ?>
  5.     </div>
  6. <?php } ?>

This ability is really handy if you’re going to wrap the TOC with some kind of formatting that you don’t want to be shown if no TOC will be shown.

Recap

So, just to summarize, 3 functions are available to you

  1. wptoc_has_toc()
  2. wptoc_show_toc_as_ulist()
  3. wptoc_show_toc_as_olist()

Disabling the Plugin

Disabling Programmatically

You can disable the plugin from your template code. Let’s, say you want to disable it when is_home(), is_front_page() or some other WordPress condition is met. You can do this within your template code like this:

  1. <?php wp_disable(); ?>

Disabling Within Content

To disable the TOC for a post you need to just include the following code anywhere in your post.

  1. <!-- [wptoc_disable] -->

If you include this in the content of your post or page calls to wptoc_has_toc() will return FALSE. And the wptoc_show_toc_as_*() functions will not print anything.

Leaving Enabled, but Excluding Some Content

You can also exclude only some of the content of your post out of the table of contents for whatever reason. To do this you need to enclose the text you want to exclude in the following code.

  1. <!-- [wptoc_notoc] -->
  2. The content you want to exclude from inclusion in the table of contents
  3. <!-- [/wptoc_notoc] -->

Frequently Asked Questions

Does the plugin properly handle headers with embedded markup, like <a> or <strong> tags?

Any html in the header will be stripped out of the TOC allowing just the text of the header to render. The html tags will not be altered within the_content() however.

If you’re not sure what this means, it’s pretty much just what you’d expect. Your content won’t change and the toc will not have <strong>, <a> or any other embedded markup within it.

Can I use the plugin to generate a table of contents for any content?

Yes you can. The instructions above address the “typical” usage scenario. However, you can use the plugin to generate a table of contents for any content at all.

For example, here’s how you would generate a table of contents for content you load from a file:

  1. // You'll need to require/include the plugin first.
  2. require_once('/path/to/wptoc.php');
  3.  
  4. // Load the content from a file
  5. $wptoc_contents = file_get_contents('mycontent.html');
  6.  
  7. // Be sure the plugin functions you'll need are available
  8. $wptoc_exists = function_exists('wptoc_toc') && function_exists('wptoc_as_ulist');
  9.  
  10. // If the plugin is available,
  11. if($wptoc_exists) {
  12.     // Extract the table of contents from your content
  13.     $wptoc = wptoc_toc($wptoc_contents);
  14.  
  15.     // Generate the table of contents html for that content
  16.     $wptoc_toc = wptoc_as_ulist($wptoc['toc']);
  17.  
  18.     // Replace our original content with the content plus named anchors
  19.     // to allow linking to sections from the table of contents.
  20.     $wptoc_contents = $wptoc['html-with-anchors'];
  21. }
  22.  
  23. // To display the toc now you just:
  24. // echo $wptoc_toc
  25.  
  26. // To display the content of the file with named anchors added to allow linking from the toc you:
  27. // echo $wptoc_contents

Pretty easy eh?

Any Questions?

We’re committed to providing our clients and the world at large with high-value software tools. But even the best tools need good documentation to be useful.

If anything isn’t clear, you need some help with a particular usage scenario, or you’d like to see a new feature added we encourage you to ask for help.

Happy Blogging!