Presentation

This filter creates a table of contents on the top of your page. It uses the HTML header tags to select the elements of the TOC. Look at the example page to see how the table is generated from your article's content, it's rather straightforward.

You don't have to use all the header tags. If for one reason you use h1 for your categories and wish to have h4 subcategories (instead of, say, h2) it's perfectly possible. However, you will not be able to use h2 or h3 later on, since you decided that subcategories will be using h4. Therefore the following structure is false and will produce unexpected results:

<h1>Category1</h1>
<h4>Subcategory 1.1</h4>
<h4>Subcategory 1.2</h4>
<h2>What is that. There is nothing between Category and Subcategory!<h2>

Features

• The filter is configurable, through the input format configuration panel. You can select header tags to avoid (comma-separated list). So if for one reason, you don't want to include h1 tags in your TOCs, just add it to your exclusion list.

• If you're massively using the header tags, you might want to limit the depth of your TOCs. This is possible too in the configuration of your input format. So if you, for instance, set this field to 1, only the categories will show up on your TOC, no subcategories whatsoever.

• The TOC's content is in a div block with class set to "toc". You can therefore change its appearance by appropriately modifying your CSS files.

Known issues

• Some of the descriptions are ridiculous (Bla bla, or something of that sort). I'll change that... One day...

• In order to be able to make the TOC links, every header tag of your articles body will have an id field set by the filter. If there is already an id, it will be (brutally) removed so as to remain (X)HTML compliant. I have an idea on how to fix this, it should be soon resolved.

• Logically enough, filters are called also for the trimmed version of your articles (aka the teasers). This will lead to a rather unpleasant result (at least in my opinion) with a mini-TOC on every teaser. I don't see a rather easy way to fix this, since it's filter independent. I'm currently planning to extend my Teaser management module to avoid this kind of behaviour. More info on the related page, once if decided what will the strategy be.

Future

• Add support for a textile markup in order to create TOC (not using the header tags).

• Allow exceptions within content itself, for instance something like: <h1 __notoc__> will exclude this header tag from the table of content.

• Add a warning when the headers aren't used correctly (see example given above)

• See what happens with articles divided onto several pages (there doesn't seem to be a settled solution to achieve multi-page articles, so for the moment I won't bother with this).