WordPress SEO Table Of Contents

Jan 2, 2009   //   by Hackadelic   //   WordPress  //  228 Comments

This is the home of the WordPress SEO Table Of Contents plugin: A freely positionable, AJAX-ishly collapsible, CSS styleable, fancy table of contents box for WordPress posts and pages.

[toc style=”margin: 1em 12em”]

WordPress SEO Table Of Contents Features

  • Automatic recognition of headings up to any level.12
  • Table of contents wrapped in an aesthetically shaped box.
  • Dynamically collapsible to an unobtrusive size, to maximize space for content. (Click on the table of contents box header to see it.)
  • Freely positionable through a WordPress shortcode. (Where the shortcode is, there the table of contents box will appear.) Great if you want an intro chapter to be displayed before the table of contents.
  • Freely styleable via CSS classes and inline styles, all supplied via shortcode arguments.
  • Multiple table of contents boxes embeddable, through multiple shortcodes in the post. Useful for long posts.
  • As of version 1.1: Handling of hyperlinks in headings.
  • As of version 1.2: Support for multi-page posts.
  • As of version 1.5: Table of contents auto-insertion
  • As of version 1.5: Free choice of table of contents box title
  • As of version 1.5: Default values can be specified via settings for all shortcode parameters

See more live examples on the WordPress SEO Table Of Contents demo page.

Recent WordPress SEO Table Of Contents Releases

Please check out the post related to the WordPress SEO Table Of Contents version you are using or are interested in. It contains important information specific to the individual release.

WordPress SEO Table Of Contents Installation

  1. Download WordPress SEO Table of Contents.
  2. Extract the plug-in archive to your wp-plugins directory.
  3. Activate the plug-in as usual.
  4. Copy the CSS template fragment from below to your CSS file (either your theme’s style.css file, or, which I’d recommend, through the MyCSS plug-in), and adjust it to your liking. (It’s a live extract from my own my.css file.)
div.toc {
	border: 1px solid #ccc;
	font-size: .75em;
div.toc.toc-left {
	max-width: 22em;
	float: left;
	margin: 5px 5px 5px 0;
div.toc.toc-right {
	max-width: 22em;
	float: right;
	margin: 5px 0 5px 5px;

div.toc a.toc-header {
	display: block;
	background-color: #f8f8ec;
	border-top: 1px solid #fcfcfc;
	border-left: 1px solid #fcfcfc;
	border-bottom: 1px solid #f0f0e0;
	border-right: 1px solid #f0f0e0;
	color: #777;
/** Styling regarding TOC title: **/
	padding: 1px 2px;
	text-align: left;
	font-size: 1.25em;
	font-weight: bold;

div.toc a.toc-header:hover {
	border-top: 1px solid #ccc;
	border-left: 1px solid #ccc;
	border-bottom: 1px solid #fcfcfc;
	border-right: 1px solid #fcfcfc;
div.toc ul {
	list-style: none;

	margin: 0;
	padding: 5px;
	background-color: #fcfcfc;
	overflow: hidden;
	white-space: nowrap;
div.toc.auto-collapse ul {
	display: none;

div.toc li a {
	text-decoration: none;
	border: 0 none;
	color: #777;
div.toc li.toc-level-1 {
	font-weight: bold;
div.toc li.toc-level-2 {
	font-weight: bold;
	padding-left: .25em;
div.toc li.toc-level-3 {
	padding-left: .5em;
div.toc li.toc-level-4 {
	padding-left: .75em;

WordPress SEO Table Of Contents Usage

The WordPress SEO Table of Contents plug-in automatically recognizes the headings3 in your post, so there’s no need to specifically mark up the table of contents entries.

To position the table of contents box on the page, place the toc shortcode where you want the box to appear. Use the class or style shortcode parameter to make the table of contents box float to the left or right (it’s similar to positioning an image). Use the hint parameter to specify the text shown when the mouse hovers over the table of contents box header.


Note: A WordPress table of contents is never shown on the blog front page, only in single posts and pages. And of course: No headings – no table of contents. (That is, the table of contents shortcode will be ignored if there are no headings in the post.)


Parameter Description
title The title of the table of contents box
hint Hint shown when the mouse is hovered over the table of contents header. Particularly useful when the table of contents box is collapsed.
class Extra CSS classes for positioning and styling the table of contents in addition to its default CSS class, toc.
style Inline CSS style. To specify the width of an individual box, use for ex. style="width: 50%"
auto Should be set to off to suppress auto-insertion on individual posts. Has no effect when auto-insertion is turned off in the settings page.

All parameters except auto have default values supplied via plugin settings from the dashboard. (Note: In the dashboard page, don’t use quotes around the values.)

Predefined CSS classes

The main CSS class of a WordPress SEO Table of Contents box. Most CSS styling is bound to this class.
toc-left, toc-right
table of contents box styling for floating alignments. These are in addition to the above class. For example, to make the table of contents box float to the right, pass the shortcode parameter class=toc-right.

WordPress SEO Table Of Contents Tips And Tricks

RaftaMan reported that some themes (like iNove) contain CSS padding definitions in a way that interferes with the table of contents CSS styling. A workaround is to redefine padding-left in the table of contents CSS for all levels. There is an example is in his comment.

Other advice:

The Story Behind WordPress SEO Table Of Contents

I wanted a WordPress table of contents box similar to the one in MediaWiki, but to my surprize there seemed to be no WordPress plug-in for that.4 Besides, as I tend to prefer a short intro to precede the table of contents, I wanted one that’s freely positionable in the post, and “traditional” table of contents solutions seemed to have implicit positioning at the top only.

So there I was, engineering yet another WordPress plug-in of own, of which I hope it would be to the benefit and liking of a wider audience, too.

If you use this plug-in, please consider making a donation to support the further development. Donate whatever you feel appropriate. Any amount is appreciated.
Thank you.

Please note: technical support will be provided to donators only.

  1. The maximum heading level to include is configurable. []
  2. Headings are formatted with “Heading x” from the drop-down box in “Kitchen Sink Toolbar” of the visual editor, or wrapped in <Hx>...<Hx/> tags in HTML mode (where x is a number denoting the heading level). []
  3. The maximum heading level to include is configurable. []
  4. At least, not one that does only that. Some series plug-ins include a sort of a table of contents, but I consider it overkill to install a series manager plug-in to get a table of contents, in particular when I don’t quite like the way it’s done. []


  • Hi there,

    I was wondering if there’s a way to stop the plugin from adding anchors to pages that do not have a TOC on them? I ask this because I use some styling like h1:first-child to remove leading margins, but the fact that the anchors are added before the h1 breaks this.


    • Notr right now, but I will look into it for a future release.

  • Hi Hackadelic:

    I’m playing around with WP before I commit myself. Lovely plug-in, many thanks for your efforts.

    Two of your posters mentioned extra line spaces added before headings, such as this example from a test page of mine:

    Hi There! 

    The second poster (Saturday, 2009) mentioned that this was a WP artefact, and suggested a change to the TOC code.

    $anchor = ‘<a>BCOMPAT_ANCHORS) $anchor .= ‘‘; 

    I’m a php ingenue, but AFAICS, your current code does indeed already incorporate that suggestion, but the unwanted BR (and P) remain. Any suggestions as to how to tighten up the spacing?

    Thank you for your time.

    • Gosh darn. My html code examples dropped out. Sorry about that. I thought the code tag was meant to allow that. Clearly, I know a lot less than I thought about html.


    • Garry, WP modifies the original TinyMCE behaviour in various – and not always intelligent – ways. One of them is the insertion of line breaks and their replacement with P tags that has always had subtle but persisting issues. I think the reason for your observed behavior might be somewhere. In addition, that behavior may be modified by themes and plugins, making things even less predictable.

      I don’t mean to scare you off WordPress, especially because other CMS’s have issues of own. In fact, I’m afraid loss of predictability is the price of extensibility. regardless the CMS.

  • Has anyone else run into the issue where large posts will disappear when using the TOC? The summary page displays fine but as soon as I follow the <!–more–> tag the post shows up without any content.

  • Is there a way that the width of the TOC can be fluid so that it’s only as wide as the longest heading? Right now there’s a lot of empty space.

    • Paul, it seems you’ve worked it all out, including how to remove signatures. You don’t need my help.

    • Sorry about that…it affects SEO to have an unrelated outgoing backlink on every page. I didn’t think it’d be a big deal.

    • Paul, it won’t give me sleepless nights, but I consider it unfair use.

      P.S. FYI a page does not loose rank through outgoing links per se.

  • How can I include a blog post’s “comments” section in my TOC.

    • Honden, it’s automatically included when there are comments on the post.

  • I need to insert this TOC programatically on specific pages/posts, I can’t use the shortcode in the post-body and when having automatic-insertion empty and using
    do_shortcode([‘toc’]) it doesn’t work..

    • A., why don’t you use the auto-insert feature?

  • Hi!

    I desperately need your table of contents but I can’t make it work 🙁 I installed your plugin, activated it and copied the CSS template fragment in my CSS file, but it only messes my pages. I don’t have great knowledge of CSS. I’m not sure I copied it at the right place. Or is it a problem with the theme I’m using (Vina)?

    Thank you very much for your help!

    • Isa, I would love to help you, provided you are ready to appropriately compensate for my efforts. If you are ready to proceed, contact me, and we’ll schedule something.

  • Hi
    I am fairly new toy word press
    And my question might sound stupid to some of the readers as well as the author of this plugin .
    I love the way it look on your sample that is why I decided to use it.
    Ok here is my question
    where do I insert [toc=”2,3″ title=”Table of contents”]this
    My idea was to create a single page and that what I was hopping this code would generate content table of some kind to be displayed.
    Am I understood this wrong?
    Please in-light me

    • Lev, I can’t think of a better way to explain the usage of the plugin than I do on this page. The minimum you would enter is (literally) just [toc] anywhere in your page content, use headings to denote chapters, and that’s it. Can’t be any simpler.

  • Hello, I’ve read the link for auto-collapse, so you cant ignore my last post, sorry!

  • How I change the JS code so the TOC starts minimized, and when you click in the index box title it espands?

  • thanks for that code and info helped tons!

  • Thank you!

  • In my case it was a conflict with easy adsense plugin, I disabled EA and the menu works fine on all pages.

  • Hello, I have Michael similiar problem
    Plugin was working then in some posts the content dont load, just the toc with no content. In other posts no problems.

  • I am having very inconsistent luck with the shortcode, essentially, trying to add in a class breaks the shortcode. See this page for an example.

    • Zach, don’t know what you mean, I do see a TOC on that page, albeit one with no specific CSS styling it seems.

  • So, ‘scuse the probably-dumb question, but what does this plugin have to do with SEO? It’s in the name, but it looks like it’s more for HEO (Human Engine Optimization) ;-). Does this plugin do something to improve my search rankings? Also, how do you create a multi-page post in WP?


  • Hey, just wanted to say that I’m having some issues very similar to Artem’s problem: http://hackadelic.com/solutions/wordpress/seo-table-of-contents#comment-135

    The page was working fine for months, and then we noticed that something broken. Moving the toc tag just a few lines down seems to fix it, but it’s still quite strange that it works fine in some posts and not in others.

    Did you ever come up with a solution for this?


    • Michael, I believe Artem’s problem has been fixed long ago, so your issue is probably something else with a similar visible effect.

  • I’ve read information about the credits in the plugin on this site. I didn’t see anything that prohibited a user’s removal of the powered by portion. It would seem you’d like it there as some reciprocal benefit of your work. Here are some thoughts.

    The comparison to a theme designer are not comparable. The signature of “the designer’s work” is not like an artist signing his painting. It’s not a one off creation. For many designers its a way to sell a theme for a lower cost and getting a benefit back from users who don’t mind the backlink. The credit is unobtrusive in the footer and can almost always be removed for a small fee which compensates the creator. The problem with the link in the TOC plugin is that the first thing you see on the page is the plugin. If you have 2 headings, which is possible, then you’re seeing the equivalent of ad placement before the reader even sees anything. It’s doubly poorly received on a professional site.

    So I’m glad to provide something for the cause and understand you don’t want to administrate, but there really isn’t an easy way out for this one. If I would have to have a link right underneath my title I’d simply use another plugin or pay someone to write similar code. Perhaps I’d even sell my plugin the same way, branding removal for a small fee. It’s just the nature of the plugin.

    I’m sure you’d get more donations from people willing to do the right thing and, if it means keeping the list in Excel or a spreadsheet and just sorting the domains, you’re all good. Just request a submission from purchasers. Hope this helps.

  • TOC’s can play more than just a role in making websites more accessible. Google will insert links to page sub-sections if there is a table of contents with header anchors.

    <a href="http://googlewebmastercentral.blogspot.com/2009/09/using-named-anchors-to-identify.html&quot;

    <a href="http://googleblog.blogspot.com/2009/09/jump-to-information-you-want-right-from.html&quot;

    FYI Hackadelic, I may be reading this all wrong but it seems using name anchors is deprecating in html4; id anchors is where they wish people to go…

    Lastly, what is your position on making your injected anchor tag on the headings return the reader to the top of the page when clicked?

    Thanks for the plug-in. You have obviously done a great deal of excellent work.

    • Jim, thanks for your valuable input.

      Inserting such an anchor tag is something I’m experimenting with already, but simply turning the heading into a link is not to my liking, and otherwise it’s not trivial to do it in an unobtrusive way that doesn’t spoil the typesetting/looks of the page. I’m sure I’ll come up with something neat soon though. 🙂

  • I’m using your plugin with WP 2.9 and qTranslate.
    TOC appears correctly in English posts; it doesn’t in translated posts.
    Basically qTranslate posts are handled in this way:
    translated content is stored into the post content, delimited by HTML tags; when WP outputs the post, qTranslate filters out current language content.
    So the post content may be:

    [begin english tag]
    english content
    [end english tag}
    [begin chinese tag]
    chinese content
    [end chinese tag}

    That is, when using Hackadelick TOC, there will be multiple [TOC} quicktags into the post content:

    [begin english tag]
    [TOC] english content
    [end english tag}
    [begin chinese tag]
    [TOC]chinese content
    [end chinese tag}

    However, only the english (default) language will show correctly the toc.

    Can you help?

    • Hermann, I’d say that’s a problem with the qTranslate approach to keep all translations in the same post (separated by tags), instead of completely separating them. Such an approach has a particularly high conflict potential with other plugins. There may be a way to get around this, but it’d take a detailed examination of qTranslate’s code, and I’m afraid it’s effort beyond goodwill. Perhaps you’d like to try WPML, which seems to actually separate translations from each other.

  • Awesome plugin!

    I’d like to be able to specify, as a shortcode parameter, the level of heading I want to include e.g. level=”h3″ or level=”h4″ because on pages my headings often start at 2 and go down to 3, and on posts they often start at 3 and go to four.

    Also, sometimes I want to only give the top level outline, other posts, I want to show the whole structure.

    Like others, I would also happily pay to remove the attribution.

    • Tim, thanks! Your input is on my agenda now. 🙂

      Your offer to pay for attribution removal is fair enough. I will email you about details on it.

  • Hackadelic,

    The fix you suggested works fine on my blog. Thanks! 🙂

  • Hackadelic,

    I’ve uncommented the first line of collectTOC so that the problem is back. And also added the trace HTML comments for doHeader and doTOCShortcode, simply search for the word “trace” in the source.

    The problem page: http://shamsulamry.com/blog/fixing-mystique-theme-twitter-issue/
    The correct page: http://shamsulamry.com/blog/pgp-single-pass-sign-encrypt-dotnet-stream/

    Do email me / leave a comment anywhere in my blog once you are done so that I can re-fix the problem. Hope this helps. 🙂

    • Amry, thanks, I’ll have a look as soon as I can.

    • Amry, I have a clue now what causes your issue. 🙂

      Apparently, the WP filter ‘the_content’ (which is used to trigger heading collection in SEO TOC) is applied more than once on single post views, however the second/last time it must be applied with an empty content, so the found headers are reset in collectTOC(), but nothing is refilled.

      I remember a similar issue when the filter was applied twice with the same content, hence resulting in a double TOC. (That was the reason to reset the headings array in collectTOC().) I could reproduce this issue with Mystique as well.

      I didn’t bother to dive any deeper into Mystique and hunt the source of the issue. Rather, I have found a workaround that I will include in the next SEO TOC release.

      Thanks for leaving the problem page on.

      A word of warning about your fix: It will probably not work reliably, and may produce double TOC entries. You can test if my fix will work for you though:

      Replace $this->headers = array(); with if ($this->headers) return $content; Hope it helps.

  • Hi Hackadelic,

    I’m using this plugin in my blog. However there was this weird problem where it is showing the TOC in one post, and not showing the TOC in another post.

    I checked the source, it is already creating the anchor for each header correctly, just that the TOC is not appearing. Put in several echos in the plugin code to trace, noticed that the headers count is increasing correctly in the doHeader function, but is back to zero-length in the beginning of the doTOCShortcode function.

    Commented out $this->headers = array(); (first line of function collectTOC), and the problem is gone. Not sure how was this causing the problem, but personally I think this line is redundant even if it’s there since the headers variable is already initialized, and new instance of the plugin will always be created for each page execution, no?

    Anyway, great plugin. I’m using it along with your WordPress Tweaks and Discreet Text Widget. 🙂

    • Amry, thanks.

      Indeed, a weird problem. And a challenge… 🙂

      It would be great if you could provide the URL’s where the TOC didn’t work (and where it did). There must be a reason why it worked on one, and not on the other.

  • hi
    really thanks for the plugin.
    just a recommend: it will be a really greater plugin if it be able to insert “back-to-top” links into headers.

    • Kami, yep, that one’s on the road map, too 🙂

  • I agree with both in specific terms 😛

    And I’m developing a new theme and some plugins, I didn’t update old posts and pages yet. Only when everything’s finished I’m gonna review every single post, adapting them to my plugins and making them XHTML 1.1 valid.

    I’ve been working on your plugin and added some new nice features to it, now it’s fitting my needs perfectly 😀

    (Old plugin I used was also a mod and isn’t valid on XHTML 1.0 Strict, I was planning on developing my own TOC plugin but there was some stuff I didn’t know how to do. Your plugin solved most of them and I finished the rest 😀 )

    • Hikari, Cool. I’m looking forward to learning more about your changes. 🙂

  • Ryan, I agree with you regarding credit. Plugin developers have MUCH more work than theme designers, themes are 90% the same in structure, and once finished they never update them again, while each plugin is totally different from all others and we must keep them updated forever.

    But here’s not the ideal place for this subject. WordPress authorities don’t like plugin devs while they give everything to theme designers, we’ve had this discussion recently and they insist plugins must have an option to add credit and this option must be unchecked by default. I think all plugin devs should leave it checked, they can’t ban us all 😀

    And for a credits page, take a look at http://Hikari.ws/plugins-love/ , we all should have it 😉

    Well, back to topic! Hackadelic I loved your plugin! I have some needs it doesn’t fit, and I’d like to implement them. Are you interested in letting me work with you to enhance the plugin? 😀

    I believe I can add my code without breaking anything, it just needs a few extra options and I couldn’t understand how you store and load options on database, so for now I’m just gonna disable stuff I don’t need and add my code over it, but you could implement an option to choose between them, as you did with autoInsertTOC.

    If you’re interested, contact me on my email and we can talk better and share our work. ^^

    • Hikari, you puzzled me. You agree with Ryan on my opinion? 🙂

      But really, you are absolutely right. Plugin developers have much more ongoing work (though a theme probably takes some more to get the 1st version out the door than an average plugin). And I agree that selective treatment of plugin vs theme developers is a stinking unfairness.

      Your “plugins love” page is very nice, and rare enough, but real love would also include link love and dofollow the links to their sites, especially now that it makes absolutely no difference for your own site’s page rank if you nofollow links or not. Just a hint. 😉

      Regarding your proposal, I have no problem with integrating contributed code, and attributing credits to the author (I’ve already done that in the past). However, I’m in the middle of heavily restructuring the plugin code right now, so it’s not the best moment for it. I’ll contact you via email on details.

  • @hackadelic

    Meh. I release quite a bit of code online. I like getting credit for my work, but I don’t expect or demand credit, with the exception afforded to me by the software license I choose.

    If you want to get money for your work, offer paid support (works fairly well for me).

    I don’t do much WordPress development; otherwise, I’d probably fork your plugin, and offer a non-advertisement version.

    • @Ryan, so could everybody else fork yours. Forking is a (mal)practice open to everyone. If I wouldn’t accept that, I wouldn’t be releasing any open source code at all.

      So you don’t expect credit for your work… And you thought it’s something I needed to know because…? Should I stop expecting credit because you don’t? Well, guess what, I won’t. 😛

      Everyone to his taste.

  • @Hackadelic:

    Thanks for the great plugin. I’m surprised this isn’t something built into WordPress core. I’m so used to this functionality from MediaWiki, I was surprised it didn’t happen automatically in WordPress.

    That said, I’m really not a fan of the advertising banner. If every plugin did this, WordPress blogs would start to look like Nascar. I get the argument that Skin designers do this as well. It would be nice if there was a toggle to remove the advertisement. I would prefer if skin designers did this as well.

    Needless to say, I edited the plugin to remove the advertisement. I haven’t gotten a chance to do that with the skin I’m using, but will be doing that as well.

    Adding an option for this to be removed wouldn’t hurt. People who don’t care will leave it. People who do will either disable it via the option, if it is available, or will remove it via the PHP. Unfortunately, this means I’ll need to edit your plugin every time you release an update.

    You should push WordPress core developers to add something like a “Credits” page to future versions, where interested people can see all plugins and skins installed. This is how it works in MediaWiki. On Special:Version, all installed extensions/plugins are shown with a link to the extension, and credit to the author.

    • Hi Ryan,

      you must have been reading my mind about the “Credits” page… 🙂 Alas, I don’t think that a guaranteed “Credits” page will ever become reality with WP core. If ever, it will be a voluntary decision of the individual webmasters to include such a page (and I see from my donation account how “well” voluntary decisions work out for me).

      I expect the same “performance” from an option. Once it’s there, and the hurdle to remove the credits once and for all is lowered to almost non-existence, I don’t have high hopes in the number of users actually leaving it on.

      While it is always possible to hack into the code and remove the credits, like you did, why should I make that easy? No, I don’t think theme designers should provide such an option either. People who provide value should at least get credits in return. This is not a matter of opinion, or taste, but a matter of fair play. Sure, there will always be folks who will refuse to give anything back in return, but they are not my target audience anyway.

      However, you should have noticed that my upcoming version (already in use on my site) is introducing some changes to smoothen this controversial topic.

  • Actually the problem is related to lack of content in the link tags–apparently it is a known bug in IE8:

    IE8 Bug

    So I’ll resolve it and let you know my fix in case anyone else has an issue. Thanks for your prompt reply.

  • Hi:

    The SEO TOC seems to be adding double anchors: <!– –> (comment is added just so it would show in comment form). This is causing the links in the contents not to work with IE8–no issue with FF. Any solutions would be appreciated.
    The page of issue is in my website part of the signature to this comment.

    • Hi Wendy,

      sorry for the delayed response, your comment was in my spam queue, so I didn’t notice it first.

      Unfortunately the sample code you apparently supplied was stripped away (probably due to contained angle brackets).

      Anyway, if I understand you right, you mean there are two anchors prepended to each heading. This is by design as of version 1.5, but can turned off in the settings page.

  • Is it possible to customize the hierarchy with other fields apart from the header tags?

    For instance…..I wanted my TOC to go:

    Page title



    • John, it isn’t. While I can imagine adding ‘page title’ in the future (pointing to the top of article), I don’t see where ‘Category’ would point to.

  • I was taught a long time ago before css to create table borders by applying a background color of black to the table tag, setting its cellspacing and cellpadding to 1, then coloring all the internal cells by setting them white. This produced a nice looking table with a 1 pixel outline around the cells.

    However, if the page font is set to black, and the table background is set to black, even though the individual cells are set to white with black text on them, will that trigger a penalty from google as trying to hide text?

    • Leigh, this plugin is not using HTML tables, so I don’t understand how it relates to my SEO Table Of Contents plugin???

  • I had the same problem as khubuz with line breaks being automatically inserted between the toc-anchor and a heading tag. While you are right in the fact that your plugin does not insert line breaks, WordPress itself will do so in response to the plugin code. This is because unstyled anchors (from the plugin) automatically get thrown into paragraphs since inline elements are required to be nested in block level elements. My solution was to modify the following code, adding block level divs in hackadelic-toc.php:

    221. $anchor = ‘<a class="toc-anchor" name="'.$anchor.'"‘;
    222. if ($this->BCOMPAT_ANCHORS) $anchor .= ‘‘;

    My code now validates and no css hacks are needed to retain proper formatting.

  • Nice pluggin! Good work!

  • Love this plugin! Is there a way to get the TOC to appear on the front page (home page)?


  • This plugin has saved me a lot of work. And I wonder why I didn’t discover this earlier. Thanks a lot.

  • Great Plugin Hackadelic! It helps even a non-programmer like me have a great looking interface on my real estate site.

    One easy question I can’t seem to locate the answer for is how do I get the TOC box to appear on the home page? Right now it only shows up on the post page but not if the post is on the home page of my site…

    Can you please send me the code?


    • Bob, thanks!

      Unfortunately, the current version does not provide that feature. It has never been huge demand for it in the past, but it seems now it is growing. So I’ll see to it to include that feature soon.

      Edit: Contrary to my last statement, this is not going to happen soon, because it’s problematic to cover excerpts and multi-page posts on the front page w/o multplying the count of database queries, which would significantly affect front page rendering performance.

  • Great,..
    great heading usability is (are) great seo stuff.
    Thanks for nice plugins

  • nice plugin…!

  • Thanks Hackadelic 🙂

  • Great plugin, unfortunately the code produced isn’t XHTML valid because of the credit box. It needs to be enclosed in (LI) tag or put outside the (UL) tag.

    • Thanks Spiff! Will be fixed soon.

  • Hackadelic > your comment filter erase a part of my code.

    There are 2 majors problems with your code.

    First, on L.177, you have to (or not if you prefer a buggy results :)) change this in you regexp
    by this ((.|\n)+?)
    because, as I’ve already said, WP editor sometimes add new line after title (but before hn close tag). So, your HackadelicTOC don’t find concerned title.

    Second, you should avoid use of string ‘?>’, which is php close tag, because it could create big problem. So, just escape >.

    I’ve met both problems on production servers.

    • Alkyos, you mean that some PHP versions may have problems with the character sequence “?>” even when it is in a string??? Gee, that’s unbelievable. Must have been a pretty old and buggy PHP version. I don’t think it ever happens today, but thanks for the hint anyway.

      For the other thing: You are saying that WordPress turns




      I.e. it inserts a line break before the closing H tag?

      I don’t think it’s WordPress by itself, because than it would happen to everybody (and you are the first to report it to me). I think it’s another plugin that messes it up.

      Anyway, I’ll take your hints into account for the next release (though I will implement them differently).

      Thanks again.

  • Sorry, in the note above I omitted “” in the following text:
    I tried to combine the two so that the code [slider title="ACCOMMODATION"] was embedded in a header style, eg [slider title="ACCOMMODATION"]… so you misunderstood my question. Its the headings in the post body that I’d like to be collapsible. But I can’t find a way to make these both a sliding note & also automatically picked up by the SEO TOC at the top of the page.

    • Joan, if I get you right, you’d like to have (some of) your “chapters” collapsed in a Sliding Note, so that when you click the “chapter title”, the chapter would expand. If this was just a matter of visual appearance, you could style a normal text to look like a heading, but it is not. You need to have real headers (with real H tags, like <hx>Title<hx/>) so that they are listed in the TOC.

      Huh, that’s a rare use case, that much I can tell… 😉

      I’m afraid Sliding Notes was not meant for such usage, but here’s something that works for me, and comes as close to it as it can get. It needs to be entered in the HTML, not WYSIWYG editor, and every line break matters:

      [slider title="ACCOMODATION"]


      Text here


  • Hello Hackadelic
    Your two plugins Sliding Notes and SEO TOC are both fantastic.

    I tried to combine the two so that the code [slider title="ACCOMMODATION"] was embedded in a header style, eg [slider title="ACCOMMODATION"], so that the Table of contents showed the heading at the top of the page, but also at the heading location, the text under Accommodation could be collapsed.

    It didn’t work so I was wondering if you have any ideas on a work around ()?

  • Seems to be ok. Sorry for multiple (but moderate) post 🙂

    • Alkyos, what were you talking about???

      changed (L 177) $pattern = '@(.+?)@i';???
      But line 177 does not read $pattern = '@(.+?)@i';?!?

      ‘?>’ sequence could create big problem in php code???
      The plugin IS php code, and it is no problem at all?!?

      WP editor sometimes add new line after title (but before hn close tag)???
      I don’t think so, it never added one here. Maybe it’s another plugin that messes up?

      I’m really unclear what your problem was, how it manifested, and whether it is solved now or not.

  • Don’t work, sorry.
    Last try, with only part after first ( and before last ) :

    Original :

    Modified :

  • The code has been cut because of tag filtering…

    try to add space round first h :
    original :
    $pattern = ‘@(.+?)@i’;

    modified :
    $pattern = ‘@((.|\n)+?)@i’;

  • Hi,

    I’ve changed (L 177)
    $pattern = '@(.+?)@i';
    $pattern = '@((.|\n)+?)@i';

    1/ because original regexp don’t works with new line (WP editor sometimes add new line after title (but before hn close tag)
    2/ ‘?>’ sequence could create big problem in php code.

  • Hi Hackadelic

    Yeah, sorry, I was far too rude. I apologise. I was having a bad day and I took it out on you. Inexcusible.

    I have my own WP plugin, and I hate exactly the type of feedback that I gave you. I should have known better. I truly am sorry.

    I still dislike the link, but I know what you’re trying to achieve. You’re trying to get something back from all of the rude people like me.

    Something else to consider is requiring a donation to remove the link in the TOC. Or adding the TOC to the footer.


    • Hi Dan,

      apology accepted.

      Now you are making constructive proposals. (But it is not that I didn’t think of alternatives myself before making my decision about whether and where to add a signature. ;-))

      I found injection into the footer problematic, because it could destroy the footer design / layout. I have no control over the design and layout of a footer of an arbitrary site, but I do have control over the design and layout of a TOC box.

      Requesting a donation for a depersonalized version goes towards a “premium” plugin model. While it is definitely interesting, it is also more complicated to manage.

      LBNL: Where the signature is now is definitely the best place for me. If someone likes the TOC, (s)he can see immediately what it is and where to get it. Removing it or even just moving it to some other place would be a significant devaluation.

      I’d be interested in a more thorough discussion on this topic. I’ll post about it these days, and I’d like to invite you to join in. If you are a plugin author yourself, you know how little open source developers receive in exchange for their hard work. Finding ways to improve the situation is definitely worth spending time on it.

  • Hi Hack, that’s not the best analogy but I’m not such a troll that’d I’d insult you further by arguing it. I was just hoping for an option. Thanks for the great plugins.

    • Gravity, not only is an artist’s signature a good analogy, it is the only valid analogy. If it is acceptable to have a “Powered by Theme XY” in themes (i.e. the signature of the theme’s author), I see no reason why it wouldn’t be acceptable in other visible items.

      That said, I’m very open to proposal how to improve the placement and appearance of the signature to make it even less obtrusive. The one thing that won’t happen though is that I depersonalize my work again.

  • I hate the new signature below the TOC. Completely ruins the plugin now. Want the choice not to have that link there.

    Disagree that it’s an artist signature, more of spammy advertising. There are better ways to inject a link.


    • Dan, I’m not willing to take your braze, imprudent tone on my blog. Nor am I willing to tolerate your allegation I would do “spammy advertising”. An unsubstantiated statement like that only shows that you have no clear idea of what spam is, and what it is not.

      You WANT a choice??? Where do you think you are to put demands on me? I’m not your personal Santa Claus, dude!

      If you have a constructive proposal about whatever “better ways”, lay it on me. If not, you are free to move on. But don’t dare to accost me like this again! Understand?

      To everybody who feels the urge to emotionally discharge here: Take a deep breath and overcome it, or your comment will be silently deleted!

  • I really like your sliding notes and TOC plugins, but do not like the advertising you’ve recently added to the bottom of them. I could remove the code in the files themselves, but would prefer the CHOICE as an option if possible.

    • Gravity, it is like telling an artist that you don’t like his signature on his pictures. I’m providing great work for free, I never see a dime for it, now don’t expect me to do all that anonymously as well.

      Of course, you are free to modify open source software whatever way you choose. But again, it is like painting over the artist’s signature on a picture. If your conscience allows it, go ahead…

  • Hello!

    I tried your great plugin with 2.8.4 DE WordPress, but there’s no Output when using the Shortcode [TOC].
    (Its working with auto-TOC).

    I did a look in the sourcecode and found, that
    the shortcode (function renderTOC) is called
    before the filter (function collectTOC).

    So renderTOC returns nothing (”), because
    there are no headers identified with collectTOC.

    Do i have to change something in wordpress so that the filters are called before the shortcodes?

    Greets from Austria,

    • Woody, that’s very strange. It seems as if the default priority at which filters (and/or shortcodes) are added is not 10, as documented.

      To test my hypothesis, try this: Find the line where the pre-filter is added (add_filter('the_content', array(&$this, 'collectTOC'));) and replace it with:

      add_filter('the_content', array(&$this, 'collectTOC'), 10);

      Let me know if that changed anything.

  • Hello, guys!

    I would like a TOC in the articles listing mode (See the main page of my site). Do you have any idea how can I achieve this using your plugin?

    • Zlatko, if you mean the front page, the plugin currently does not support TOC’s there.

  • […] Plugin Home Page […]

  • […] Hackadelic SEO Table of Contents – generates table of contents based on page headers, used on the Attractions, Island History & Culture, Services, and Recreation pages […]

  • […] SEO Table Of Contents is another really good option to try that has a handy control panel allowing to set the heading level, position on the page, the text preceding it, the look and feel, etc: […]

  • Works fine, thanks ! My project is hosted by the very problematic Amen. So, many things don’t work as it should.

  • Problem when I click on ‘Hackadelic SEO TOC’ :
    Warning: handleoptions(hackadelic-toc-settings.php): failed to open stream: No such file or directory in /home/.sites/88/site132/web/wp-content/plugins/hackadelic-table-of-content-boxes/hackadelic-toc.php on line 340

    Warning: handleoptions(): Failed opening ‘hackadelic-toc-settings.php’ for inclusion (include_path=”) in /home/.sites/88/site132/web/wp-content/plugins/hackadelic-table-of-content-boxes/hackadelic-toc.php on line 340

    • Bob, nobody has reported a problem like that before. Looks like something caused by an utmost peculiar PHP setting. Perhaps this would help:

      Open the file hackadelic-toc.php, go to line 340, and replace

      include 'hackadelic-toc-settings.php';


      include dirname(__FILE__) . '/hackadelic-toc-settings.php';

      Tell me if it worked.

  • Thanks, I’ll try that out 🙂

    I have no problems with typing a tag – but when you’re developing for a client, a lot of them forget, or don’t do it right… you know how it is…

    • Darfuria, the plugin provides an auto-insertion option. All you have to do is turn it on in the dashboard.

  • Is there a PHP tag I can use to embed this on a page template rather than typing the shortcode into a page?

    • Darfuria, no there is no tag. The plugin depends on the ordering and context in which different actions of it take place. Ordering and context are guaranteed by the WP callback system. In a page template, nothing guarantees that the right context is established and the right ordering is preserved when the tag function is called.

      In some cases (read “themes”) though, do_shortode('[toc]') might work.

  • Hi, I am new to use this plugin, you said “No headings – no TOC box”. SO how and where can I put “heading” in WordPress?

  • Yes, exactly. I’m playing around with your plugin to see how it works and to see if it is possible to setup a custom template tag so theme designers can put it wherever they want in their templates. Learning a lot about WordPress plugins in the process.

  • WOW! This is what I love so much about the WordPress community so much. People sharing their work for the greater good of the community. This plugin is just what I was looking for. Thank you so much!

    It could be improved by highlighting the current page you are on in the table of contents box, which would be a big help for multi-page posts. Here’s an example:

    Say you have a three page post and you’re viewing the 2nd page. The TOC box markup should look like this…

    <li class="toc-level-2"><a title="page-1" href="/#page-1" rel="bookmark nofollow">Page 1</a></li>
    <li class="toc-level-2 active"><a title="page-2" href="/2#page-2" rel="bookmark nofollow">Page 2</a></li>
    <li class="toc-level-2"><a title="page-3" href="/3#page-3" rel="bookmark nofollow">Page 3</a></li>

    I can see how the logic to figure this out is a bit hairy. But if it’s possible, it would be greatly appreciated.

    • Russel, good idea. For my understanding: What you mean is to add the class “active” to all links in the current page. So if you have 3 pages and 3 headings on each, items 4, 5 and 6 in the TOC would have the class “active” when you are on page 2. Right?

  • fantastic! plugins like this draws me more and more to wordpress and beginning to drop joomla and drupal. my life becomes easier.

    thank you so much!

  • Is there a way to auto indent the headings in the TOC depending on the heading? Something like this:


    If not, can you make this a feature to enable/disable in the options?

    For my specific site see:
    I want something like the top TOC (manual) with indenting whereas using the plugin results in the bottom TOC (plugin).

    Thanks for the great plugin and help!

    • Doug, there is a way. If you take a closer look at the sample CSS, you’ll find that for each heading level Hn, there is a CSS definition div.toc li.toc-level-n which sets padding-left (i.e. indentation) to a value that grows with the level. For example:

      div.toc li.toc-level-3 { padding-left: .5em }
      div.toc li.toc-level-4 { padding-left: .75em }

      The sample contains only clauses up to level 4, but you can add others at will, and adjust the padding to your liking.

    • I see that in the css, and I’ve tried increasing the size, but still all of my links have the same padding. I’m using H2 H3 and H4 tags, so they should be getting spaced out. Could there possibly be a conflict with my theme?

      I tried using the default 2010 theme and it works just fine, so it must be a conflict with my theme (catalyst).

      How can I fix this? Thanks!

    • Paul, try appending “!important” to the padding clauses in the CSS.

    • Thanks! That worked like a charm! I’ll have to remember that one…

  • You’re right. The br tag was inserted by another plug-in, TinyMCE Advanced. Thank you for your help 🙂

  • Loving the plugin. I’ve been looking for something like this for a while.

    On a couple of examples I notice you have rounded corners on the TOC box.
    Any clues as to how you managed to implement this? I’m presuming using some kind of image call in the CSS?


    • Rob, I’m not aware of rounded corners on TOC boxes?!? Anyway, here are the CSS statements to create rounded corners (replace $R by your radius):

      -moz-border-radius: $R;
      -khtml-border-radius: $R;
      -webkit-border-radius: $R;

      IE (what else) does not support rounded corners.

  • Hi,

    For some reason, the TOC boxes plug-in is adding an anchor and a br tag everywhere I’m using a heading even though I am not using a TOC on those pages. De-activating the plug-in will make my pages look normal again. Do you have any idea what’s causing that? The only solution I can think of is not using headings except where I need a TOC.

    I made sure the auto insert is off, I also added a [toc auto=off] to my pages but it’s still the same.

    Take a look at this page and notice the line breaks above the blue headings.

    Thank your for this awesome plug-in.

  • Using your nice plugin in my page (WP 2.8) I found a strange phenomena with a longer page (a bit more than 13.000 characters). WP just shows a blank page (like a page saved with no text). If I cut the text to be shorter at about 12.600 characters the saved page again looks normal (together with toc). It happens only if there is [toc] on page. With no shortcut there is no matter how long a page, looks normal.

    What is the problem, how can I cure it?

    • @Khubuz, my TOC box plugin has no code that inserts a BR tag. What it does insert is an anchor immediately before each heading, so that the TOC box has a reference to link to. What I see on your site are BR tags injected between anchor and heading. I assume it must be either another plugin, or your theme, that does that. You could check my assumption by deactivating the TOC plugin, and (in HTML mode) manually inserting an anchor immediately before a heading. (It should look something like <a name="XXX"></a><h2>Some Title</h2>.)

      @Geza, that seems very much like a PHP regular expression engine issue I’ve found earlier. See my post “Shadowchase Continued”, especially the chapter “The Proof Of Innocence”.

  • Hackadelic,

    Thanks. It’s not critical, but curious. I look forward to the update. BTW, will it be WP2.7.1 compatible? I’m waiting for some of the “bugs” to settle before upgrading to WP2.8, i.e. I’ve long since learned not to rush into first releases.

    BTW, I’m reconsidering the issue of a “toTOC” link from a header in the body to jump back to the TOC (see June 27th, 12:45 am).

    In your next version, would it be possible to add a unique name, such as name=”hackadelic-toc” to the $tochdr logic (line 264 of hackadelic-toc.php)?

    I tried it and it works but I hate tweaking someone else’s code, for a number of reasons.

    Thanks in advance.

    • Don, that doesn’t make much sense. The anchor named “hackadelic-toc” would be repeated for all headings. And the headings already have an anchor with a unique name, derived from the heading text.

      Anyway, wasn’t that a “back to top” link? Or is it “to TOC”?

  • Thank you for offering your help with debugging. You are, of course, right that the disease does not always show up immediately. I just hope that it is a mutation and not a virus that will spread 😉 I think I will try my own services before hiring you 🙂

    I guess that it is my code, as it seems as though it has to do with user-defined filenames. If a comma is inadvertently used in a list of space-delimited filenames, then …

    I overlooked your suggestion for using a filter on the return. I will test that for the next version of the plugin. Thank you.

  • Thanks for getting back to me. No, on WPMU.

    I’m currently developing my site with WP 2.7.1 and Atahualpa 3.3.3 … I installed TOC 1.5.2 the latest that I know of … Back end is MySQL 5.1, with PHP …

    I’m scratching my head because, unless I’m doing something really silly, I too thought I should have been able to “tweak” the default inline CSS style. (Even if the style sheet is probably the best place.)

    As I noted above, I tried every config I could think of to add two properties.


    • Don, soon I’ll release a new version of the plugin. Let’s see whether the issue will persist.

  • I have another question. Acknowledging that there is the CSS Template, which is the correct place to do most of this … nonetheless, I’ve been tinkering with default settings on the management page to learn more about what I can and cannot set here; in particular: “The default inline CSS style …” field.

    Initially, I tried pairing up properties, such as max-width and max-height (as a test, per your example above) and those were ignored — whether or not I put quotes around both, used a closing semi-colon or not, etc. So I shifted to entering single properties only.

    It seems that I can only pass one property: max-width (as pixels or percent). If I try to pass max-height: by itself, it’s ignored. If I try to pass color: that is ignored. Similarly for other properties.

    Are there some rules about what can and cannot go in “The default inline CSS style …” field, and how many?

    Thanks in advance.

    • Don, there is no limit to the count of CSS properties you can set. I would have said it’s a bug, but the same thing works just fine here.

      Are you using WPMU by chance? The back end of the current version does not work well in WPMU (but one where it does is underway).

  • Hackadelic,

    Thank you for the settings correction … (paint my cheeks pink). I’ll be adding these clarifications to my “how to” doc on using your plugin (which, to be sure, has links back to your site).

    As an FYI, so far I have a series of more than 28 such docs, I call them TechNotes. They range from setting up IIS on an XP Pro dev environment all the way to the other end of fine tuning the site … written as I did it. (I just added my URL to the Website field as it will be in its “just open for business” production mode in a couple of days).

    As regards “nofollow” … this was a key area that I clearly did not understand. But. It makes sense now. I think I finally have a clear picture of what this setting is for specifically, and the subject in general.

    I appreciate the time you’ve spent. Being an engineer and “IT guy” (though a non-blogger until now) it drives me “nuts” when I can’t figure something out. Your help has been invaluable. 🙂

  • Hackadelic,

    You are welcome on the tip, and the donation (its well deserved).

    re: default settings
    As a follow-up question, if you wished to have more than one CSS setting, would you comma separate them and would you need to put the entire string in quotes? For example, and I don’t know that I would ever actually do this: “max-width=200px,max-height=300px”. Yes/no?

    re: nofollow
    Ahhhh hahhh! I think. … On multi-page posts (i.e. split pages) if you set nofollow in your options panel, Google will scan them but will lower their ranking … Is that a good thing? …

    If there is a piece of “crucial” information on the second or third or fourth page of a post, wouldn’t that make it harder for someone to find it on the Internet. … Doesn’t it?

    I’m not sure why this is so difficult to comprehend … maybe its because I’m a blog-site newbie with no real life experience in page ranking … but I can’t see the value in setting nofollow on multi-page posts. … Unless I’m missing something still, which is quite possible.

    re: navigation on multi-page posts
    I’ve installed the wp-pagenavi plugin. It works great for pages with multiple posts listed on them. Home, or a Category page will eventually fill up with (hopefully) many dozens of posts … so, setting the number of posts per page, or post excerpts per page, and installing wp-pagenavi to allow visitors to move through those pages and keep track of where they are more easily, makes the site a lot friendlier — in my humble opinion.

    However, the author of the plugin (based on the one comment I was able to find on his site) seems to have a severe bias against splitting a post into multiple pages and since he doesn’t split posts he’s not going to modify his plugin to add navigation for them.

    I, on the other hand, will have quite a number of technical posts that, in MS Word, are 20 or 30 pages long. It seems to me that it would be easier for folks to navigate these documents if they didn’t have to scroll endlessly down the post page. Your TOC plugin helps, a lot. But. I’d also like to have a professional looking set of page numbers at the bottom … like the page numbering scheme in wp-pagenavi … so there is a common navigation “look and feel” for my readers across the entire site. …

    Unfortunately, no one has done this. We’re stuck with “Page 1 2 3” or a very minor variant of that. … Sigh.

    Again, a superb plugin, Hackadelic. Thank you. And I’m looking forward to installing the Sliding Notes and Series plugins. 🙂

    • Don,

      Settings: You use “;” to separate CSS statements. (Hence: style=”max-width=200px ; max-height=300px”) There are excellent CSS tutorials on w3schools.com.

      Nofollow: I’d personally prefer to pull attention to the 1st page, because I want readers to start reading at the beginning of a post, not in the middle of it, especially as it may contain prerequisite information. And if Google finds matching keywords on the 2nd page but not on the first, it will show the second one in its search results anyway. But of course, it’s up to you to decide that you want page rank spread uniformly amongst all pages of a post. It’s a matter of how your landing page strategy looks like.

  • P.S. I don’t suppose you have a really nifty “NextPage” plugin that would get me well beyond “Page 1 2 ..” hanging around doing nothing, would you. ?

  • Hackadelic,

    Never mind about the “toTOC” question. I just finished testing using the nextpage and toc tags in tandem (the toc tag comes after the nextpage tag of course) and … it works beautifully!

    By sizing my pages to something reasonable the TOC on each page is close enough that getting back up to it is not an issue. 🙂

    Very nice plugin Hackadelic. It worked as advertised. Thank you.

    P.S. I just sent a donation your way via PayPal. … Just don’t tell my wife. 🙂

  • Hackadelic,

    Just saw your response after writing my “tip” post about setting default values.

    Thank you for the example for showing me how to add a “back to TOC” capability. 🙂

    And clearly I missed the obvious about how to enter special characters such as “<” in comments Thanks for clarifying that for me.

    But, on the subject of “nofollow”, I’m now even more confused (easily done with SEO I’m afraid). If Google will find and scan the second, third, fourth, and so on, pages … whether “nofollow” is set or not … then, what value does including “nofollow” have?

    Sorry to dump this question on you, but this whole “nofollow” thing has been confusing from the start. Every time I think I begin to understand it … I find I don’t.

    Thanks in advance.

  • Hackedelic,

    I have a tip that might help future newbies. I’ve been working with this plugin for couple of hours now and … it works great with WP 2.7.1 and Atahualpa 3.3.3. … but …

    It took me a bit to figure out how to set the default values on the plugin managment page. I was over complicating. What works is (as an example):

    “The default CSS class …”: toc-right … no quotes, no class=, no square parentheses, nothing else.

    “The default inline CSS style …”: max-width:200px … no quotes, no style=, no square parentheses, nothing else.

    Hope this helps.

    • Dan, thanks for the tip. I added an explanatory box to the parameters table.

      And many thanks for the donation! I really appreciate it. (And I won’t tell anyone 😉 )

      Google has to scan every page for search purposes. Nofollow only affects their page rank calculation.

      I don’t have a pending “Next Page” plugin in my drawer, but if you would elaborate on your idea in more detail… 🙂

  • I’m setting up the TOC plugin and I have a question about the “nofollow” option for it as, while I (think) I understand the concept of wasting SEO juice, I’m not an expert at SEO (or even close).

    So my question is, whether it makes sense to set “nofollow” when I have multi-page posts (using the nextpage tag) when there is unique data on each page … which is sort of why I needed a TOC plugin.

    The question revolves around the concept of SE’s and multi-page posts. Do they only scan the first page (if you set nofollow) or are they actually seeing the entire post whether one has nextpage set or not?

    Thanks in advance.

    • Don, “nofollow” does not mean Google won’t find your secondary pages. Leaving “nofollow” in the TOC links is perfectly unobjectionable.

  • Hackadelic,

    Thank you for the info. I’ve downloaded the TOC, the slider and the series plugins. These will be great tools for me.

    As soon as I get some extra cash (my donation pool is empty at the moment from other plugins) I’ll be sending some your way.

    Question: until such time as you add a “top” capability, if you do, could I add something like this manually at each heading (without left and right arrows or tags):


    (I looked up your ref on HTML entities but, unless I missed something, it didn’t show how to escape those for use in text.)

    • Don, to write “<“, you must write “&lt;”.

      To manually add references to the top, write at the beginning of your post something like <a name="top-of-post"></a>, and add to your chapter headers <a href="#top-of-post">[&uarr;]</a> (yields: “[↑]“).

  • Hi. One more question:

    While perusing your site I noticed a slick feature. How did you do the “This entry is part of a series …” for your Tips and Tricks articles? That was way cool too! Some of my technical posts will be part of a (lengthy) series and this would be a nice feature to add.

    BTW, I’m using WP 2.7.1 and Atahualap 3.3.3.

    Thanks in advance.

    • Don, the “This entry is part of a series” thingy is generated by my other plugin, Hackadelic Series.

  • Hmmm, try again … without the tag code “… after every nextpage tag? …”

    Sorry for the clutter, I embedded it in the code tags but it “ate” it anyway.

  • Oops.

    Question 1 was supposed to say “… after every <!–nextpage–> tag? …

  • Hi,

    I really like how this TOC works. It will be a major asset for me as I will have quite a number of long technical articles. Two questions if I may:

    1. How does this handle multi-page posts? Do you have to insert your tag after every tag? Or does the TOC span all pages (or could it span all pages of a post)?

    2. How would I, or can I do a “back to top” tag by each header item included in the TOC to return to the TOC itself?

    Thanks in advance.

    • Hi Don,

      your question #1 is answered in the release announcement for version 1.2, which first included support for multi-page posts.

      Inserting “back-to-top” links into headers is not quite in the scope of this plugin, I’m afraid. At least from my current point of view. (I could implement one that does this though. 🙂 )

  • Did you modify the version on the site to include comments as the last TOC entry?

    • Yes, the new code I’m working on (on this site only) includes comments. I’ll be releasing a new version soon.

  • Hi,

    I have extended a little plugin for showcasing the themes available on my WordPress portal: http://wordpress.blogos.dk/showcaseext.

    When I run it on a page with a TOC shortcode, all the Showcase output disappears. The Hackadelic TOC Boxes seems to work, unless I activate the show readme links function (line 301 in my source).

    $showcase = $showcase . '' . __('Read the readme file:','showcaseext') . ' ' . $readme . '';

    I am not sure why your plugin does not like it, but perhaps you can help?

    Thank you and all the best,


    • Georg, that’s too little information for a serious analysis, but it seems more likely to me that your code doesn’t like the TOC shortcode, not the other way around. 😉

      Anyway, that line seems pretty innocent to me. Sometimes, it is one place where the symptom shows, and another where the “disease” is. If you need help, I offer troubleshooting / debugging services.

  • Sorry, it’s ok but my structure is a little unconventionnal. So I had !is_category() on line 157 to permit TOC on category page.

  • Hi,
    does it work on 2.8 ? Because nothing append when I add [toc] to a post (with Hn of course !).

  • Hi, can anybody make the box of content defaut collapped. Just expended it when the visitors click on the title? I have tried but no results. 🙁

  • Dave, have a look at v1.5.2 and see if it’s still happening. If it is, feel free to send me a sample and I’ll see if I can help Hackadelic fix it.

    Send it to ad[ignorethisantispam]min {at} beerpla.net

  • I think I found a problem with header elements like h3, h4, etc. embedded in fieldsets. I poked around a bit here and there for anyone else with the same problem, haven’t found anyone yet.

    I’ll poke around a bit more, and if I can’t find anything relevant, I’ll do up a screencast or screenshot and explanation to show what’s happening. It’s hard to explain but easy to see.

    If I can hack in a patch, I’ll send it to you.

    Overall, great plugin, it solves some layout and navigation issues very nicely.

    I do have a lot to say about FOSS, having written a chunk of it myself, but that’s a different conversation.

    Take care,

    ps: My issue may be as simple as just ignoring h3/4 in the case where the header element follows . Firebug showed me an empty tag in there taking up about a line and a half of vertical space.

  • Posted 2 solutions to the problems I found:
    – Incorrect (out of order) bullets – patch included at http://wordpress.org/support/topic/268259
    – Extra tags within tags unstripped – patch included at http://wordpress.org/support/topic/268568

    • Thanks a lot, Artem. I’ll have a look at them and incorporate them shortly.

  • Hackadelic,

    finally got around to sending you an email via the contact form outlining current issues (btw I forgot to mention I’m using the svn trunk version). Let me know if you received it.


  • […] usage hints, have a look at the Hackadelic Table Of Contents Box plugin home Author: RaftaMan Categories: Uncategorized Tags: Comments (0) Trackbacks (0) Leave a […]

  • Maybe you should consider to set ‘padding-left’ for all levels (including level-1).

    div.toc li.toc-level-1 {
    font-weight: bold;
    padding-left: 0em;

    There are some themes (e.g. iNove) that use padding-left in their style.css and inheriting those values without overwriting creates some ugly effects (e.g. level-1 headings are far more right than level-2 headings).

    Great plugin btw.

    • RaftaMan, thanks for the hint. I included it under “Tips And Tricks”.

  • As long as it is the voodoo of computer science, I am fine.

    It does not look as good as the Hackadelic TOC (well, perhaps I should style it …), but I wrote some extra lines of code in the Showcase plugin, so now it generates a TOC section at the beginning. I can live with that until I see whether you come up with something more clever! Thank you, in any case!

    • 😀 No, I don’t use puppets to develop plugins, Georg 😉

      I wasn’t aware that changing [showcase]’s code is an option for you. Try this in [showcase]’s handler:

      Assuming the handler returns the string $s, instead of
      return $s;
      return apply_filters('the_content', '[toc]' . $s);

      I hope that’ll work for you.

  • Yes, the download page looks fine.

    It is Temaer that does not. I have a small paragraph of text and then



    The second shortcode is for the on the fly generation of the showcase. The TOC-shortcode does not generate anything (or, perhaps, it generates nothing). I wonder whether it first sees the page after the H3-headers are inserted by the showcase plugin. If so, is there anything that I can do?

    • Georg, I know what the problem is. At the moment the TOC plugin is active, it doesn’t see the generated content, just the blank shortcode “[showcase]”.

      What you want can’t be done with concurring shortcodes, when the output of one shortcode depends on the output of the other. Or if it could, it would be real voodoo.

      I’ll see if I can do that voodoo. 😉 (But I’m not making any promises)

  • Hi again,

    I just noticed that Hackadelic TOC seems to have some problems with the Danish characters, at least “å” (å). See http://easycaptures.com/4394427994 – the options page – and http://easycaptures.com/3141018677 – the output at the page mentioned above. Or rather, the one I should have mentioned at the first link. Replace “/temaer” with “/wpdadkdownloads”. Sorry.

  • Your TOC plugin is marvellous. I will write a post about it shortly on my Danish WordPress portal.

    Now, I have a page that it does not work on. It does work on http://wordpress.blogos.dk/temaer/.

    It does not work on http://wordpress.blogos.dk/temaer/. This page is generated on the fly by WordPress Theme Showcase Plugin.

    Is this because the page is generated on the fly, or because links are embedded within the H3-tags? Is there any work around, perhaps?

    • Georg, thanks!

      Does the page generator for that page generate the [toc] shortcode, too? It is required to display the toc box.

  • […] Of Contents In The Sidebar This entry is part of a series, TOC Boxes Advice» Hackadelic TOC Boxes work in the sidebar out of the box. You can see a live demo on my blog by going to any post’s […]

  • If you set up the plugin to automatically put TOC @start+end clicking on either TOC slider only opens and closes the TOC at the start of the article

    e.g. http://saltaire-aa.org/blog/?page_id=1857

    and I can provide many more examples – its NOT browser specific nor is it specific to theme or whether its a page or a post.

    • DavyB, thanks a lot for the hint. I already know how to fix it. Expect an update soon.

  • Hi man ! Just want to tell you how much I appreciate your plugin ! And its appreciated by my readers (they told me). Thanks again !

  • Thanks for the plugin! I’ve just installed it and it’s working great.

  • […] out the plug-in homepage for in-depth information about the plug-in… …..read more Download Plugin! Plugin Owner: Hackadelic Homepage: Visit Plugin’s Website Version 1.2.0 […]

  • I really like this plugin!

    Is it possible to create TOC 100% automatically? Because I don’t like the idea of add [toc] tag to all the long posts. If the program can determine when to add toc or not, that will be perfect!

    • Jfly, thanks. I’m glad you like it.

      The shortcode is meant for placement of the TOC box. when you look at my post, you’ll see that the TOC box placement is a matter of compromise between placing it near the top, and placing it in a way that does not get in the way with images embedded in the post. While I can imagine ease criteria when to automatically insert a box, I have much stronger concerns about the where.

      Hey, I’ve just got the idea that I could insert one at some predefined position (specified via options) if none has been inserted by shortcode. 🙂

      Any other suggestions (that won’t require “rocket science”)?

  • What controls the order of the links in the toc – I seem to have 2 NOT in the order of the headers in my Links Page ? I doubt its browser specific – shows up in both Safari and FF

    • Davy, the links are in the order found in the content. (Not necessarily in the order they appear visually – that could be obscured by floating elements).

      I would gladly check out your issue if you provide me an URL where it occurs.

  • Thanks Hackadelic, I haven’t had a chance to look at it all week but now I see that the problem has been resolved. I feel a bit sheepish not thinking about the browser cache. I don’t know how many times I have told users to clear their cache before they see the changes.

    Thanks again for the help.

  • Hi Hackadelic

    Hope your flu is getting better.

    I copied you css to try fix the issue (Figured yours was working so it should solve the problems) When it didn’t resolve the issue I decided to ask the question.
    I have reverted my.css back to just the sample css, and the problem persists. I think searched for what you refer to the .entry clause and found it in style.css. I then added the background: inherit to the ul clause in my.css, that didn’t work. So I added div.toc ul li { background: inherit; } to the end of the file, no luck there. Then I went into the style.css and removed the background … from there. Still that didn’t work. I have also gone to my theme’s images directory and renamed the bullet.gif. Still it shows up in my TOC.

    I made the site live yesterday and all my posts will now have the TOC code on it.

    Thanks for your help thus far.

    • Orthotomeo, thanks. I really am getting better.

      When I read your comment, I immediately thought: Browser cache! You need to clear it before you can see CSS changes.

      Then I visited your website, and there it was… or… wasn’t. An issue, I mean.

      I would guess it was gone with the first change you described already. You just couldn’t see it because you were watching stuff in your browser’s cache.

      Because it’s a detail so easy to forget, I suggest configuring your browser to clear the cache upon either startup or shutdown. (I know you can do that with FF, not sure about IE.)

  • Hi Hackadelic

    You have some really great plugins which I am dying to use. I am stuck on the TOC plugin though (haven’t even gotten to trying series yet). I must admit I have absolutely zero clue about how CSS works but I am a technical person so I have been trying this on and off for three days now.
    Today I got frustrated with it and viewed your page source and copied your my.css verbatim into mine (removing the test import at the top).
    I still get the same issues on Firefox 3, Google Chrome as well as IE7.
    The page that I am trying this on is http://www.orthotomeo.co.za/costs/
    What it does is put little dots over the text.
    I have the list-style set to none which I think means that there should be no dots. Here is my ul section of my.css:
    div.toc ul
    list-style: none;

    margin: 0;
    padding: 5px;
    background-color: #fcfcfc;
    overflow: hidden;
    white-space: nowrap;

    Do you have any tips as to what I could be doing wrong?


    • Othotomeo, copying my my.css verbatim was not the best idea. Now there are so many CSS interferences with your other stylesheets that I can’t tell what’s what.

      One thing I can tell though: The dots you are getting are not from the list-style. I suggest you undo the CSS changes, and just include the sample CSS from this page, so that other interferences are excluded, and I’ll check it out.

      Update: I’ve got it now – it’s from the clause .entry ul li { background: ... }. Adding the CSS clause div.toc ul li { background: inherit; } should help.

  • […] Hackadelic TOC Boxes […]

  • Is there a shortcode parameter to have the toc box closed on page load? Please

  • Well a[name] was my first idea, but you know: IE6.
    I guess i know why my theme has that behavior, it uses border-bottom to underline the links when hovering the .entry-content block.

  • that’s right, but with firefox 3 (and 3.1beta2) they are visible. I already was that issue on another blog. see screenie:
    Anchor Bug

    • Daniel, I use FF3 myself, as well as TOC boxes on my blog, and I don’t see empty anchors. I’m pretty sure it’s an issue with your theme’s CSS. I would guess that it’s due to suboptimal usage of :before and/or :after pseudo-elements.

      Note that you can use a[name] to specify named anchors only, which are usually not links anyway, and remove link-specific styling from them. I think this would be more appropriate then removing link-specific styling from TOC-related named anchors, but leaving it on other named anchors (possibly coming from other plugins).

      You can also attach link-specific styling to real links only in the first place, using a[href].

      Your hint is nonetheless a good one, and I’ll integrate it with the next plugin version.

  • you are talking about the TOC, which is easily skinnable. What I was talking about are the links generated by the plugin:
    <a name=”toc-anchor-21-3″/>

    AFAIK you can’t select them with CSS 2 so they are skinned like all other links in the post. A class attribut here allows me to hide them.

    • Daniel, I’m puzzled !?!?

      Those anchors are empty, and shouldn’t appear at all:

      '<a name="'.$anchor.'"></a>'.$match[0];

  • Ok third and last comment, sorry it’s getting really late here in france, i’m all tired and i’m doing shit.

    Just add the class=”toc-anchor” to the anchor links created by the plugin. so you can unstyle them via your theme’s CSS

    • Daniel, you could have accomplished the same thing w/o changing plugin code, by adjusting the div.toc a clause from the CSS for the plugin. (Yes, CSS is a powerful monster 🙂 )

  • oh seems like the the < and > were eaten by the blog XD

    I post the patch again

    line 72

    - return '<a name="'.$anchor.'" class="toc-anchor"></a>'.$match[0];
    + return '<a name="'.$anchor.'" class="toc-anchor"></a>'.$match[0];

  • Damn good plugin, like the two others in fact. Simple and efficient.

    I’d like to suggest a small patch for it
    I had trouble with the links created by the plugin, because they were styled like the real links, it was a bit ugly, so to unstyle them i made the following mod:

    line 72

    - return ''.$match[0];
    + return ''.$match[0];

    voila, now you can unstyle these links via your CSS.

    Again great plugins, thanks very much.

  • Hi!

    Thank you for both your plugins!!

    I have a question. Somehow the TOC is generated in wrong order. It has only happened in one of my posts, but it is weird.

    This is the order it should be:
    Forløsning av følelser, den ubehagige blindveien
    Erstatningen til forløsning av følelser
    Eksempel på balansert tankegang
    Teknikken start

    But instead, it arranges them this way:
    Forløsning av følelser, den ubehagige blindveien
    Eksempel på balansert tankegang
    Teknikken start
    Erstatningen til forløsning av følelser

    Do you have any idea? In the post, the text is in the right order of course.

    Thank you
    Svein Daniel

    • Hi Svein,

      can you point me to the URL of that post? I couldn’t find it on your blog.

  • Hi,

    I would like to display different text depending on the selected language.
    How to modify it so this would work: toc hint=[lang_br]”text”[/lang_br][lang_pl]”tekst”[/lang_pl].
    The same in the case of all the other entries?

    Is this possible at all?


    • Hi MarkD,

      no, that’s not possible with the current version.

      What exactly is your context? Are you referring to a multilingual blog in conjunction with the qTranslate plugin?

      If so, my best guess would be to place one TOC box per language section, with corresponding hint values in that language. But I never tried this myself. If you do, I’d be interested in the outcome.

  • @Hackadelic
    I’ve been a bit busy, finalizing the automated wp dev/staging environment clone tool, so right now my staging environment is a bit blown up. I definitely have you on the list to contact soon.


    • @Artem,

      😮 oops, my spam blocker had blocked your comment so haven’t noticed it until now.

      Sure, you’re welcome to contact me.

  • Hi,
    It’s working. Thank you.

  • Hi Cornel,

    I’ll answer your question gladly, but just for the records: Your questions are not really on the plug-in. They are general CSS questions. I heartily recommend this excellent introduction to CSS at w3schools on that.

    Coming back to your problem:

    You can either use list-style: disc inside, or you need to increase the left padding, by adding padding-left: 20px (or whatever padding suits you) after the padding:5px directive. (Or you can combine both directives in padding:5px 5px 5px 20px.)

  • Hi,
    I have upgraded to the new version. Now links in heading works. Thank you.
    I have tried to add “disc” for bullet points, or “decimal” for numbers to my TOC but it doesn’t show any changes. Bellow you can see the changes I have added to my CSS:

    div.toc ul {
    list-style: disc;
    margin: 0;
    padding: 5px;
    background-color: #fcfcfc;
    overflow: hidden;
    white-space: nowrap;

    I’m doing somthing wrong?

  • Hackadelic,

    I’ve installed the plugin and started observing odd behavior. If I put the code in certain places, like in the beginning of the post, all the content disappears once I load the page. The code I’m putting in is just [toc class=”toc-right”] on this page: http://beerpla.net/2008/11/08/building-the-perfect-htpc-media-pc-capable-of-playing-1080p-h264/.

    I’ve taken out the code for now and set up a dev version of the blog where you can observe the problem. Do you have IM?

    Otherwise, thanks for the plugin – it’s a great idea.


    • Artem, from your question if I had IM, I assumed you don’t want to publicly disclose your test blog URL. So I contacted you by email on that, but there’s been no response so far, which is a pity, because I would have gladly investigated the effect.

  • Cornel, good news: As of just now, hyperlinks are handled correctly in TOC boxes.

  • Cornel,

    I’ll check out the links in headings thing.

    You can’t make a heading fit a certain width, but you can adjust the width of the TOC box.

    Neither you can make it skip headings, but you can format a line in a way that it looks like a heading, but really isn’t. I’d use a CSS class for that, so to not have to do the formatting all over again each time.

    And, hey, you don’t have to say hi, or thank me. Just keep pouring your questions on me with no further courtesies. 😉

  • If a title is too long how can I make it to fit into my TOC
    How can I make TOC to skip some headings?

  • When I bring a link to any h style heading content it will show twice on the TOC
    It’s there any way to bring a link to a h style content without destroying the TOC?

  • Cornel, I’m not sure I know what you mean. Entries in the TOC are generated automatically from headings.

    If you want the TOC entries to have bullet points perpended, you need to modify the list-style CSS directives in the div.toc ul clause. (You can use “disc” for bullet points, or “decimal” for numbers.)

  • how can I add bullets to my toc?

  • hi jackle, enter [toc class="toc-right"] at the very beginning of your post. If your headings are long, and you want to increase the width of the box, enter [toc class="toc-right" style="max-width:200px"] (replacing 200px with the width that suits you best)

  • hi problem with the code… I want something similar to the first table of content on this page on the right just below the date calender thing. what exactly do I type in the post?

  • oups…that was it! 🙂 thanks

  • Hi Shenzo, have you included the toc shortcode as instructed above?

  • Hi,

    thanks for this great plugin! Was just looking for something like that…
    I can’t make it work though. Seems that for some reason the headings are not detected. I activated the plugin, put the CSS in style.css, made a test post with h1, h2, h3 and h4…did I miss any step? (can’t link to the site though, it’s still on local…)

  • Hi Carlos,

    I couldn’t reproduce your issue myself (WP 2.7 + PHP 5.2.0). If you point me to a page where it occurs, I’ll check it out.

  • Hi, thanks for the plugin.
    I get the headers “duplicates”:

    >>HeaderA:Header A:
    >>HeaderB:Header B:

    (wp 2.7 and php 5)

    Some sugerence?

  • baron, Bernhard, koz, thanks a lot for your positive feedback. You really made me feel good 🙂

  • Your plugin is really great. I used to place anchor manually, and the result was just casual.

    Moeover, I liked your styling : I did not even had to change the css !

  • Super plugin


  • hi. Thanks for plugin



  • Hi SuperMAG, thanks a lot for the hint. Fixed it.

  • the demo page is not working.

Blog Categories

I have come here to chew bubblegum and kick ass...
and I'm all out of bubblegum.
-- Nada in They Live