Table of Contents Generator WordPress plugin

About

A WordPress plugin that scans through HTML headings inside post content and creates a "Table of Contents" list. Put <!--TOC--> inside your post content to trigger the Table of Contents generation.

Previously I have been hand-coding Table of Contents for my other pages in this blog. It is time consuming and you always need to remember to keep TOC and the actual content synchronised. Then I thought, maybe I should write a WordPress plugin that automates this process for me. Thus this plugin after an afternoon of coding.

It basically replaces every instance of <!--TOC--> with a table of contents generated from HTML headings in the post/page. It provides a permalink for each heading so you can jump to that section right from generated TOC.

Example? The Table of Contents list at the top-right hand corner of this page (as well as my other coding pages) is generated by this very plugin.

Download

Usage

  1. Download the plugin file, and unzip. Upload "ylsy_toc.php" into your WordPress' plugins directory.
  2. Activate the "Table of Contents Generator" plugin in your WordPress plugins administration page.
  3. For posts or pages that need to have table of contents generated, place <!--TOC--> at where you want the TOC to appear.
  4. Alternatively, add <?php echo $post->post_toc; ?> in your template, within "the loop" (or wherever $post has been defined) to paste in the same TOC list. It is useful if you wish to generate TOC on the sidebar.

When the TOC plugin is triggered, it would:

  1. Scan all the HTML headings in your post/page, and then assign an unique ID to each heading.
  2. Replace <!--TOC--> with a hierarchical ordered list.

For example, if you have the following HTML headings in your post:

<h3>Section 1</h3>
...
<h3>Section 2</h3>
...
<h4>Section 2.1</h4>
...
<h3>Section 3</h3>
...

Table of Contents plugin will then create the following ordered list with links pointing to each heading:

  1. Section 1
  2. Section 2
    1. Section 2.1
  3. Section 3

Customisation

Ordered list will be placed inside a <div/> with class name "toc". You can then use CSS to customise the look and feel of your table of contents. For example, this site has the following customisation in theme's style.css:

.toc {
  border: #ccc solid 1px;
  float: right;
  font-size: .9em;
  margin: 0 0 5px 12px;
  width: 200px;
}

.toc ol {
  margin: 5px;
  padding-left: 30px;
}

To-Do

A list of bugs and features that need to be addressed:

  • It currently does not work with mark up languages that have their own ways to generate heading. TOC Generator works by looking at the content before any markup is applied, and it checks only HTML tags. Therefore markups like Markdown and Textile.

Support

Feel free to contact me if you have any question regarding this WordPress plugin.

History

  • 0.3 (2006-06-26)
    • Add template syntax <php echo $post->post_toc; ?> (thanks to Scott Merrill)
  • 0.2 (2006-02-07)
  • 0.1 (2006-01-21)

License

GNU General Public License