TOC Boxes 1.5 With Auto-Insertion

Finally I got around to finish this new major release of my TOC Boxes plugin, with a bunch of long wanted new features.

Actually, there are so many new features and improvements, that I decided it deserved to fast-forward to version number 1.5. Hence the “unofficial” name of the release: Warp 3.

Overall, the plugin now provides a bunch of settings, partly related to existing, partly to new features.

Download it as usually at wordpress.org, and find out in the rest of this post about the exciting new features and improvements. [toc class=toc-right]

New Options For Existing Features

Settings that cover existing features are:

• The maximum heading level included in a toc: By default, headings H1–H4 are included, but you can change that now.
• Default CSS class: When you omit the shortcode paramter class, the value specified here is used. (Before, an empty string was implied.)
• Default inline CSS style: The same with regard to the paramter style.
• Default hint: Dito for paramter hint.

TOC Box Auto-Insertion

One major new feature is the ability to automatically insert TOC boxes into posts. Settings are available for:

• TOC Box location: Currently it’s possible to place it at the beginning, or the end of a post, or both. Leaving the location empty disables auto-insertion.
• What CSS class should be used for auto-inserted TOC boxes: If nothing is specified here, the default CSS class is used (see above).
• What CSS style should be used for auto-inserted TOC boxes: Similar handling as with the auto-insertion CSS class setting.

Note that when a shortcode is present in a post, it takes precedence over auto-insertion. That is, you can still individually position your TOC on posts where auto-insertion settings don’t fit well.

In addition, I’ve added a mechanism to disable auto-insertion on individual posts, by using the shortcode form [toc auto=off].

A word of warning about the auto-insertion feature: Unless your posts are very similar in structure, I recommend individual TOC placement with the toc shortcode, or you risk messing up your post’s text / image layout. For example, I tend to insert eye-catching images aligned to the left or right at the beginning of my posts. Adding a left or right aligned TOC in addition to the image would totally mess up the typesetting aesthetics. Hence I would always prefer manually placing the TOC at a location that fits well visually with the rest of my post.

However, if you don’t use images near the top of your posts, it’s reasonable to enable auto-insertion, and only use explicit placement in the few posts it is needed.

Pretty Heading Anchors

Another major change is the new naming scheme for heading anchors. Before, they have been generated by a simple numbering scheme. Something like “toc-37-3”. Thank to a great idea by John Blackbourn, they have a much more readable form now, derived from the heading text itself. A positive side effect is – you guess it – improved SEO.

One interesting challenge arose from changing the anchor naming scheme: When a post explicitly links to headings using the old-style anchors (be it in the same or in another post) those links would break after changing the naming scheme. To prevent from this, the plugin generates both anchor forms. An option exist to turn this behavior off, if it’s not needed. New users should turn it off immediately after installation.

Conclusion

This release is a major leap forward in the evolution of the plugin, and, as I sincerely hope, a significant increase in its usefulness for you.

Cheers and happy structured writing.

2 Comments

• 
  Aleisha March 29, 2009 at 1:34 pm

  Hi there

  I just downloaded the TOC and I dont know how to make it work for multi-pages. I have had a look at the PHP file, but I dont really know what I should do to enable it to work for multi-page TOC (all of my links in the TOC will go to different pages).

  Is there somewhere I can find this information? It would be really useful to have it for people like me (who need more slower step-by-step instructions in this area).

  Other than that, your plugin is really great… if only I can make it work how I need it.

  Thanks
  Aleisha 🙂
  • 
    Hackadelic March 29, 2009 at 2:58 pm

    Hi Aleisha,

    actually, the toc shortcode should work on multi-page posts right away, with no special setup. Auto-inserted TOCs must be enabled first via settings, but after that they should work on multi-page entries, too. If not, there might be a problem with your theme. I could check it out if you provided me the URL of your site. (You can use the contact form if you don’t want to display it publicly yet.)