Table of Contents Plus

A powerful yet user friendly plugin that automatically creates a context specific index or table of contents (TOC) for long pages (and custom post types). More than just a table of contents plugin, this plugin can also output a sitemap listing pages and/or categories across your entire site.

Description

Built from the ground up and with Wikipedia in mind, the table of contents by default appears before the first heading on a page. This allows the author to insert lead-in content that may summarise or introduce the rest of the page. It also uses a unique numbering scheme that doesn’t get lost through CSS differences across themes.

This plugin is a great companion for content rich sites such as content management system oriented configurations. That said, bloggers also have the same benefits when writing long structured articles. Discover how Google uses this index to provide ‘Jump To’ links to your content.

Includes an administration options panel where you can customise settings like display position, define the minimum number of headings before an index is displayed, other appearance, and more. For power users, expand the advanced options to further tweak its behaviour – eg: exclude undesired heading levels like h5 and h6 from being included; disable the output of the included CSS file; adjust the top offset and more. Using shortcodes, you can override default behaviour such as special exclusions on a specific page or even to hide the table of contents altogether.

Prefer to include the index in the sidebar? Go to Appearance > Widgets and drag the TOC+ to your desired sidebar and position.

Custom post types are supported, however, auto insertion works only when the_content() has been used by the custom post type. Each post type will appear in the options panel, so enable the ones you want.

Translations

  • Australian English (default)
  • Dutch – Renee
  • French – Jean-Michel Duriez
  • German – Ben
  • Polish – Jakub
  • Simplified Chinese – icedream
  • Slovak – Boris Gereg
  • Ukrainian – Michael Yunat

Translations are more than welcome. The translation file can be found in the languages folder of the plugin, or online in the WordPress repository.

If you have any advice in making it easier to translate, please let me know.

Screenshots

Scenarios / FAQs

The simplest approach

For the impatient, all you have to do is enable the plugin.

The plugin will apply default settings and produce the table of contents before the first heading on pages (not posts, nor custom post types) with four or more headings.

No shortcodes needed.

How do I disable the table of contents for a certain page?

Simply add [no_toc] anywhere on the page to suppress the table of contents.

My site has 100 pages but I only want the table of contents to appear on 10 of them

You could put [no_toc] on the 90 pages but that wouldn’t be fun… so try the following:

  1. Go to Settings > TOC+ and disable the auto insertion option for pages (or the content type you’re working with).
  2. Add [toc] onto the 10 pages that need them. Note that the table of contents will appear where you placed the shortcode.

Alternatively, you could also experiment with the restrict path option if the pages you want to include the index on all fall within a certain section of your site (eg /wiki/).

I want to ignore certain headings

Use the ‘exclude headings’ option if you would like to ignore certain headings. Separate multiple headings with a pipe |. Use an asterisk * as a wildcard to match other text. Note that this is not case sensitive. Some examples:

  • Fruit* ignore headings starting with Fruit
  • *Fruit Diet* ignore headings with Fruit Diet somewhere in the heading
  • Apple Tree|Oranges|Yellow Bananas ignore headings that are exactly Apple Tree, Oranges or Yellow Bananas

Can I have the table of contents in the sidebar?

Use the TOC+ widget and drag it into your desired position. If you want the table of contents to only be displayed in the sidebar, then make sure you tick that option in the widget.

Unlike Wikipedia, I want all my anchors to be lowercase and use hyphens rather than underscores

There are two options that allow you to adjust the casing and use of hyphens. If you still require more, you can massage it a little more by attaching into the toc_url_anchor_target filter. See the developer help section for an example.

I would like to incorporate a sitemap

  1. Create a page for your sitemap (if you have an existing one, use that instead).
  2. Add [sitemap] into your page and save.

The above is the simplest example of integrating a sitemap listing all pages and categories. You can customise the sitemap options under Settings > TOC+ or check out some of the more advanced uses with the sitemap related shortcodes below.

You could also incorporate a sitemap using a text widget and pasting any of the sitemap shortcodes.

Install / upgrade

Install the plugin by searching for Table of Contents Plus from the plugin add menu, or directly from the WordPress plugins repository.

There are no special upgrade instructions (woohoo!). Overwrite your existing folder with the latest or use the streamlined approach in the plugin menu. Your options will not be lost.

Shortcodes

The plugin was designed to be as seamless and painfree as possible and did not require you to insert a shortcode for operation. However, using the shortcode allows you to fully control the position of the table of contents within your page. The following shortcodes are available with this plugin.

When parameters are left out for the shortcodes below, they will fallback to the settings you defined under Settings > TOC+.

[toc]

Lets you generate the table of contents at the preferred position. Also useful for sites that only require a TOC on a small handful of pages.

  • label: text, title of the table of contents
  • no_label: true/false, shows or hides the title
  • wrapping: text, either “left” or “right”
  • heading_levels: numbers, this lets you select the heading levels you want included in the table of contents. Separate multiple levels with a comma. Example: include headings 3, 4 and 5 but exclude the others with heading_levels="3,4,5"
  • exclude: text, enter headings to be excluded. Separate multiple headings with a pipe |. Use an asterisk * as a wildcard to match other text. You could also use regular expressions for more advanced matching.
  • class: text, enter CSS classes to be added to the container. Separate multiple classes with a space.

[no_toc]

Allows you to disable the table of contents for the current post, page, or custom post type.

[sitemap]

Produces a listing of all pages and categories for your site. You can use this on any post, page or even in a text widget.

[sitemap_pages]

Lets you print out a listing of only pages. The following parameters are accepted:

  • heading: number between 1 and 6, defines which html heading to use
  • label: text, title of the list
  • no_label: true/false, shows or hides the list heading
  • exclude: IDs of the pages or categories you wish to exclude
  • exclude_tree: ID of the page or category you wish to exclude including its all descendants

[sitemap_categories]

Similar to [sitemap_pages] but for categories.

[sitemap_posts]

This lets you print out an index of all published posts on your site. By default, posts are listed in alphabetical order grouped by their first letters. There are CSS classes for each section, letter and list allowing you to customise the appearance.The following parameters are accepted:

  • order: text, either ASC or DESC
  • orderby: text, popular options include “title”, “date”, “ID”, and “rand”. See WP_Query for a list
  • separate: true/false, when set to false, does not split the posts by first letter.

Versioning scheme

I have adopted the same Ubuntu versioning scheme so the first release is 1107.

Other releases in the same month will be dot releases, eg the second release in July 2011 is 1107.1.

I love it, how can I show my appreciation?

If you have been impressed with this plugin and would like to somehow show some appreciation, rather than send a donation my way, please donate to your charity of choice. Feel free to leave a short note here if you’d like.

I will never ask for any form of reward or compensation. Helping others achieve their goals is satisfying enough :)

Questions or suggestions?

If you have questions or suggestions, please place them below.

795 thoughts on “Table of Contents Plus”

  1. Like your plug however PRIVATE post are showing up in the SiteMap that I use in a PAGE, In advance section the Exclude headings section is also being ignored. Thanks so much.

    1. Private posts are being included by WP if you are logged in and have access to them, otherwise it’s only publicly available posts for everyone else.

      Also, exclude headings apply to the TOC, not sitemaps.

  2. In my case, the construction of the index is configured with the option to display the index when two or more headings are present, to include in the index only heading level h2 and display an index flat (without hierarchy).

    Unfortunately, when the text is only one heading h2 and hn (n>2) one or more, the index is also shown with a single item (the orphan h2).

    Of course I can fix by adding another h2 heading or removing the existing one. The problem is that I should check over 4000 articles. Do you have any idea to solve or to get a list with the TOC with orphan h2? Thanks

    1. Thanks for reporting this. Without inspection, sounds like the count of headings should be done later, till after unqualifying headings have been removed. I’ll take a look for the next release.

  3. Hi, thanks for a great TOC plugin. I’ve tried to speed read the comments but didn’t come across a solution. I would like the anchor to be above the heading and not below the heading so that the heading is displayed, rather than the text below the heading. I hope you understand what I mean.

    1. The anchor surrounds the heading in a span tag so should be giving focus to the start of the heading when tabbing or for assistive technology.

      Do you have a persistent toolbar across the top (like the WordPress admin bar)? If so, enable the smooth scroll option and it’ll accomodate the toolbar. If you have a larger toolbar, you can customise the height difference in the advanced options.

    1. You’ll need to edit the is_eligible() function (line 1479) to add that check in but I wouldn’t recommend it as you’ll need to reapply the changes with every update.

      You can achieve a similar effect through CSS:

      #toc_container { display: none; }
      .logged-in #toc_container { display: block; }

  4. Hi, First of all I want to express how much I love this plugin, I love it.

    I do seem to have one problem, when I select “Show the table of contents only in the sidebar” in the widget, my table of contents for my pages do not display?

    Any suggestions welcome

    1. Nice to know it’s still useful for others.

      When you have that option checked in the widget, the TOC will no longer appear inline within the content but will only show in your sidebar where you placed the widget. Make sure you have pages enabled for auto insertion in Settings > TOC+ as the use of shortcodes would be useless in this scenario.

      1. Hi Mike, yes I have the pages enabled in the options section, but the table of contents still does not wok when the widget is used with “Show the table of contents only in the sidebar”

      2. Ok let’s start again. Try the following tests:

        0. Turn off the “Show the table of contents only in the sidebar” setting from the widget, save, then remove the widget. We’re just resetting this setting so we can do the following tests.

        1. No widget, all settings to default (eg minimum 4 headings, auto insert pages): does the TOC appear before the first heading of the page?

        2. If yes, is it the correct number of headings? There aren’t any missing headings?

        3. If ok, drag the widget to one of the sidebars that is produced on pages, leave the “Show the table of contents only in the sidebar” option unchecked. I expect you to have two TOCs, one within your content and another in your sidebar.

        4. If ok, enable “Show the table of contents only in the sidebar” and recheck. You should only have the TOC in the sidebar.

      3. I did everything you suggested and the results all were as expected, in fact everthing works fine. I suspect you misundertsatnd my problem.

        “Show the table of contents only in the sidebar” and recheck. You should only have the TOC in the sidebar.

        Yes, and thats exactly what occurs, the only issue is at this point is that a soon as I check the display toc in the sidebar, it does exactly that for all the POSTS, but what happens is the TOC then no longer displays in the PAGES, posts are still fine.

        If I uncheck the Show the table of contents only in the sidebar (for POSTS) the PAGES displays once again.

        I hope this makes sense.

      4. Hmm, I tried just now but the TOC appears in the sidebar for both posts and pages when I have that option set in the widget. I’ve tested using Twenty Eleven, Twenty Twelve, Twenty Thirteen and Twenty Fourteen themes. Which theme are you using? Can you quickly try switching to another theme to test if it is the current theme you’re using?

      5. Now that you have mentioned themes, I’m sure the problem is tied into the fact that I am using Thesis Themes 2.1 and further to that a skin called Bizlife Pro.

        I haven’t yet switched to a wordpress default theme as I don’t want to risk affecting my settings. How ever if you need me to do so, I most certainly will do so.

      6. I setup a scenario on my test site, activated the twenty twelve theme and get exactly the same result. I am opting for the no sidebars option for pages which is available on twenty twelve and on my Thesis theme setup, that is where the problem is. If I choose the default template for pages, no problem, TOC displays.

      7. That sounds to me that the theme is doing what it’s intended to do (that is construct the page without any sidebars). It kinda makes it hard for widgets to be added when there’s no sidebar present for the page. My only suggestion would be to select a page template that has a sidebar for those that require it.

    2. Actually I would like the pages to be full width and the TOC to display in the content, by me placing the shortcode there manually, and the TOC in the sidebar for the posts.

      So it seems this cant be done then?

      1. Not with the available admin options available.

        But if you can modify your theme, then you can position the TOC however you want. As an example, for one of my projects, we have inline TOCs printed normally but then position it absolutely to the left as you scroll down past the TOC. Furthermore, the heading in the TOC is highlighted as you continue down the page past where they appear. It’s very similar to the Bootstrap documentation pages, eg http://getbootstrap.com/css/

        Unfortunatley, this is highly theme dependent so I won’t be able to put make them available via admin options.

    3. OK, The thing is that everything works well until I enable the widget “display in sidebar option” then the shortcode or default options to display the TOC stops working.

      Might you consider modifying “Table of Contents Plus” so that the user may have the option to display the toc in the following manner.

      Display TOC in sidebar only:

      In the posts sidebar only (pages unaffected)
      In posts and pages (both posts and pages) for pages using the no sidebars template.

      Given I have seen many themes that use a no sidbars template for their themes

      1. Are you on WordPress 3.8 (or 3.8.1)? This version has added extra ‘visibility’ options to widgets allowing you to activate them in areas that match your criteria. Give it a go, I think it’ll do what you want.

      1. I’m going to try enhancing the widget options to allow you to control which page type to only show in the sidebar for (eg post, page, custom post type).

  5. You say:

    Translations are more than welcome. If you have any advice in making it easier to translate, please let me know.(Table of Contents Plus)

    My Question: How do I send the German language file?

  6. I am loving the plugin. There is just one problem that keeps bugging me. For some reason the TOC doesn’t have the show/hide option on pages, only on posts. I’ve tried to have the TOC automatically and manually placed on pages. It is always extended without an option to hide it.

    1. Sounds to me like there might be a javascript issue on pages. If you know what you’re looking for, check the javascript console on any of your pages to see what is causing it. Usually, when there’s a javascript error, it will break other queued javascript from running. The show/hide feature is inserted via javascript and is probably not getting called because of this.

      1. Awesesome. It’s an obvious check, but I didn’t think it through. You had the right hunch. It seems that an error caused by the absence of the sharebar on pages somehow blocked the TOC+ script. Problem solved. Thanks!

  7. is it possible to remove the numbers before the heading level in the TOC box? For example, instead of saying “2.1 Example Text”, it would say just “Example Text”?

  8. That sounds to me that the theme is doing what it’s intended to do (that is construct the page without any sidebars). It kinda makes it hard for widgets to be added when there’s no sidebar present for the page. My only suggestion would be to select a page template that has a sidebar for those that require it.

  9. Regan, I have waited many months to get an update that might fix my issue with TOC+. Although I love this plugin, it breaks Portfolio Slideshow Pro. it inactivates the thumbnail advancement (arrows) on the carousel. I had posted on the wordpress forum but I guess it got lost. so I will try this method. Yours is the best TOC out there! If I could only get it to work with Portfolio Slideshow. Thanks!

    1. I had thought I came across this somewhere and found the article in question.

      http://wordpress.org/support/topic/breaks-my-slideshow-plugin

      At the time, I tried the free version of Portfolio Slideshow but wasn’t able to replicate your problem on using TwentyTwelve as the theme. So right now, it’s either the Pro version of the plugin, a combination of all the other enabled plugins, or perhaps the theme you’re using.

      If I can’t replicate the problem using well coded defaults (themes, plugins, etc), then there’s not much help I can give!

  10. Thanks Mike for the plugin. Good work.
    I have a question, please. How can i use “1-” or “1_” instead of just “1” as a number ?
    And thank you.

    1. You can use CSS but you’ll probably want to add a space in there too as there’s currently a space separating the number with the heading.


      .toc_number:after {
      content: " -";
      }

  11. Hi thanks for this great plugin,

    I have a trouble with “Smooth scroll top offset” , it simply doesn’t work for me. I’ve tried many values but scroll is always the same.

    I precise that TOC+ is:
    – on my sidebar,
    – presentation: custom
    – exclude css: checked (with unchecked, no difference)
    – Smooth scroll top offset: 156 px

    Thanks for your help!

  12. Hi Mike Really like your plugin but …
    Is there any way to set up that the plugin list only h2 – h6 and skip h1 ?
    As most people who seo their website I try to put keyword in the heading and it usually in the title so more or less this heading is the longest of all and it really look ugly in table. Thats why im willing to skip it as its on top.
    There is any way to set up some code, option or where to edit php files to get ride of h1 from toc ?

    thx

  13. Is there a way to turn off TOC part way down a page so it does not index entries on a page past a certain point? LOVE this plugin.

    1. Two ways to exclude them: add the headings to an excluded pattern (advanced option); or mark them up with an unused heading level and exclude it (also an advanced option). There is no magic tag that says stop here.

    1. It’s not smooth scrolling because there are two other javascript errors on your page. Check your console, address them and it will start smooth scrolling with the correct offset you put in. There’s an error from ajax search form and the other one looks like custom javascript you’ve put in?

      Usually when there are javascript errors, then it will impact other delayed javascript code.

      1. Many thanks for your time, Mike. Unfortunately, I’m rather a javascript novice and I’m better at writing errors than spotting them, but I’ll have a go.
        Again, thanks.

  14. Mike,
    Just in case it pleases you to hear of people solving issues – I managed to fix the issue!
    As you pointed out, there was some rubbish custom JS on the page, which I deleted. The other error was hard to find – console was reporting an error in jQuery.js. Eventually, it turned out to be an error that the plugin Lightbox Plus Colorbox was throwing in. Didn’t really get to the bottom of that as a re-activate of that plugin seemed to fix the problem.
    PS Thanks for TOC+ – it’s great
    Cheers

  15. I start most of my articles with a heading “Info” and then follow it with a few bullets, as such…

    Info
    – Bullet 1
    – Bullet 2
    – Bullet 3

    I want the table of contents to appear “align left” after first heading. It looks great on the articles that I don’t have bullets for the first heading, but for the articles that do have bullets, it looks messed up. The bullets actually enter the table of contents box a little. How do i fix this? ‘

    Thanks

    1. I didn’t expect it to trigger as the plugin uses ‘the_content’ rather than ‘the_excerpt’ but upon further investigation, unfortunately WordPress applies ‘the_content’ when ‘the_excerpt’ is run. This is stupid in my opinion (why would you need the entire content when only the text above the fold is needed is beyond me).

      Basically when using the_excerpt, it fires wp_trim_excerpt which then pulls the full content and applies the_content shortly after. Also, there is no WordPress conditional that tells me it is about to run the_excerpt so I can’t use that to stop the TOC from firing.

      I’m not sure what recourse there is apart from seeking the WordPress core development team to consider placing a function similar to is_excerpt() which was suggested but got rejected.

  16. Hi!

    First: Thanx a lot for the great work on this plugin!

    I use sidebar-display of my TOC, but on a few pages i would like to display it in the post. Haven’t found a way to do this, and if it’s impossible, please make this a request for functionality.

    Perhaps I could be able to do a [no_toc][force_toc] to first remove it from sidebar on a post, but than force it in where i want it? Or some other way :) Just a thought.

    Again, thanx for the work on this plugin! :)

    Regards, Bard

  17. Hi,

    Thanks for developing Table of Contents Plus. I may have found 1 small bug or typo, but I can’t be sure, since I’m not familiar with WP code.

    In toc.php, somewhere around line 139 (can’t be sure, because I’ve been hacking a little) it says

    add_filter( ‘the_content’, array(&$this, ‘the_content’), 100 );

    This doesn’t play nice with the Shortcodes UI plugin. If I change that line to

    add_filter( ‘the_content’, array(&$this, ‘the_content’), 10 );

    or

    add_filter( ‘the_content’, array(&$this, ‘the_content’), 11 );

    everything seems to be working as expected.

    It could be that the Shortcodes UI plugin is wrong instead of TOC+. In that case I’m sorry for bothering you with someone else’s bug. I chose to fix it in TOC+ because my TOCs were missing. Never really looked at SUI, because it works now.

    Cheers,
    Rob

    1. Hi Rob – the number dictates the priority to run a swag of queued up code for a trigger. The lower the number, the earlier it runs. TOC+ runs late so that it can include extra content that shortcodes, or other plugins insert. Shortcodes run at 10 so would suggest you use at least 11.

      What happens with TOC+ when left at 100 and using Shortcodes UI? I don’t think you described it.

  18. I love this plugin. I will definitely volunteer more hours to the Audubon Society on behalf of the author and his charitable goals. My question is this — there is the character “<" in the "g" section that seems out of place. Did I do something to cause that? I only just noticed it and I've been using the plugin for a while. Keep up the great work.

      1. Thanks, I can see exactly what’s going on. There is a HTML span tag surrounding ‘gre’ to convert it to capitals so it is taking the first character “<” as the first letter. I’ll make sure HTML tags are stripped out of the generation.

  19. Hi there! Great plug-in which does exactly what it says it does — makes a sitemap for posts and pages. However, my site is a business directory and I have three content types: posts, pages, and listings. When I enabled the plug in, under settings, the auto-insert tick boxes show my options are to include posts, pages, and listings. GREAT! Just what I needed. However, when I render the sitemap with the short code, only the posts and pages show up. I used the sitemap short code, and then, tried using the page only short code, the post only short code, and then tried mimicking this for listings, too [sitemap_listings]. No dice, listings don’t show up. I enabled “2 or more” under headings, and basically tried every other setting as well. The listings are all tagged H1 in the title, so not sure what I’m doing wrong or why they won’t show. Any input? Thank you.

    1. Hi Kristina – Unfortunatley, I think there is a bit of confusion here.

      The main options (the ones where you can select all the types) relates to the automatic pulling of headings within your content and generating an index of them (a table of contents) at the top of your page. An example would be the one at the top of the page you’re reading now.

      A sitemap is usually a list of your pages, eg http://dublue.com/sitemap/ All sitemap related settings are under the sitemap tab.

      There isn’t a way to include custom post types in the sitemap but that is enough for a future enhancement.

  20. Hi,

    Thanks for a great plugin.

    We are using ToC on some huge pages with dozens of headings so the ToC itself becomes very long. I am thinking of ways it could be more accessible.

    1. Could you add an option to truncate long headings instead of wrapping? You could add an elipse at the end and show the full heading in a box when the cursor hovers over the top.

    2. Could you set a box height or a maxRows then show a [more] link at the bottom if there are too many rows? This would be an extension of the [hide] functionality I suspect.

    TIA

    Dani

    1. Hi Dani – nice suggestions but I won’t be putting them in as I believe they will interfere with the way Google creates direct links to sections of your site based on your headings (see article). That is, my belief is that Google would try to match the heading up to the ‘…’ part with the section within the content but fail. To do what you want would mean to insert extra HTML markup that may break the continuity of the headings.

      You also mention accessibility – forcing an ‘abled’ user without motor difficulties to apply an action before getting the full title would not be promoting accessibility in my opinion. It would only present further barriers to those sporting a disability. What if it was difficult to move the cursor to trigger the hover action?

      That said, I’ve worked on sites with many headings. Here are two examples with two different approaches to keeping the index relavant without imposing too much:

      1. http://aofm.gov.au/publications/annual-reports/annual-report-2012-2013/part-2-operations-and-performance/

      The table of contents is on the bottom left and hides all deep headings by default. It shows relevant and nested headings as the content is presented on screen (eg start scrolling and note the change in the index and the bolding). This is probably my favourite treatment so far.

      2. http://arpc.gov.au/news-and-publications/annual-reports/2012-13-annual-report/

      This one shows all entries within the content but collapses to the top level headings and fixed to the top left of the page as you scroll down so you can still jump between main sections.

      I didn’t alter any of the TOC+ plugin, the above was achieved with some CSS and javascript and you can do the same or better. Unfortunately, I won’t be adding any of the above as switchable options as they are very heavily theme dependent.

      Also, most people should be accustomed to long pages, thanks to Wikipedia.

    1. It’s a common question and asked a few times before with the same answer.

      http://wordpress.org/support/topic/anchor-text-in-other-language?replies=2
      http://wordpress.org/support/topic/disable-urlification?replies=3
      http://dublue.com/plugins/toc/comment-page-5/#comment-2039
      http://dublue.com/plugins/toc/comment-page-5/#comment-2046

      Due to the HTML specification, anchors are limited to ASCII characters and I haven’t been able to find if this has been updated to support unicode in HTML5. So I’m still waiting for someone to point me to the updated spec.

      1. Hi – as I mentioned before, I’m not supporting unicode until the HTML specification has been updated or someone points me to a reference indicating this. Also note that versions before 1108.1 actually supported unicode as found in the changelog:

        Anchor targets (eg anything after #) are now limited to ASCII characters as some mobile user agents do not accept internationalised characters. This is also a recommendation in the HTML spec. A new advanced admin option has been added to specify the default prefix when no characters qualify.

  21. Thank you for creating a spectacular product that has worked flawlessly for me thus far. It has helped me teach medical students in a very efficient way by making page navigation easier.

    I wish to donate to your hard work to keep TOC alive and well…. so if that is possible, please tell me

    Regards,
    Professor Raf
    UofM
    USA

Leave a Reply