If you'd like to provide updated information and do not have access to directly edit, please contact the site admin; thanks!
For latest release info, see History, below.
Contains one tag,
soo_toc, which will produce a linked and nested table of contents for an article, based on the article’s headings (h1, h2, etc. tags).
The first five are standard Textpattern attributes; only the last two (
full_url) are plugin-specific.
Label to precede the contents list. Optional; default is unset.
(X)HTML element (without brackets) for the label. Optional; default is unset.
(X)HTML element (without brackets) or text for separating list items. Optional; default is
li. If you change this, you should also change the
(X)HTML element for enclosing the list. Optional; default is
ul. If you change this to something other than
ol, you should also change the
(X)HTML class attribute to be applied to
wraptag. Optional; default is
Number in the range 1–6, indicating the highest heading level to include in the table of contents (see Level, below). Required; default is
6(include all headings).
true, use absolute instead of relative URLs. Optional (but see Relative vs. Absolute URLs, below); default is unset (false).
Can be used in an article body, in a page, or in a form. If used with relative URLs (the default setting) it requires an individual article context. If used in an article list, or on a page in which the
base element indicates anything other than current page, the
full_url attribute must be set to
true (or anything other than
0). (See Relative vs. Absolute URLs, below.)
The article headings
Only headings that have an
id attribute will be included. This is to give the links in the table of contents something to point to. In Textile, you can apply the
id attribute like this:
level attribute allows you to restrict which heading levels to include in the table of contents. For example,
level="3" will restrict output to
h3 headings. The default value is
6, show all headings.
Relative vs. absolute URLs
The default output uses same-page relative URLs (e.g.
href="#id_name"), which will only work correctly in an individual article context. To get absolute (full) URLs instead, set the
full_url attribute to
true (or any value other than
If you use a
base tag to point to the site root (or anything other than the current page), you will also need to use full URLs. (N. B., such usage of
base is, strictly speaking, incorrect.)
ul (the default value) or
ol, and if the article has different levels of headings, the table of contents will be a nested list. For example, given the following article headings (shown in Textile):
h2(#foo). Foo ... h3(#bar). Bar
the plugin will produce, using default attributes:
<ul class="toc"> <li><a href="#foo">Foo</a> <ul> <li><a href="#bar">Bar</a></li> </ul></li> </ul>
For this nested output to make sense, the article’s heading structure must also make sense. In particular:
- do not jump upwards more than one heading level at a time (e.g., go directly from
- the first heading should be at the lowest heading level (e.g., if the first heading in the article body is
h2, there should not be any
h1s in the article body)
Because the plugin ignores headings with no id attribute, you could get unexpected results (and possibly XHTML validation errors) if you are inconsistent about assigning id to headings.
The plugin runs a
preg_match_all search on the article’s HTML body, and another
preg_match on each heading. Theoretically this could be a performance concern in some situations, particularly in an article list context.
This plugin is very similar to the
cbs_article_index plugin (didn’t realize this when I wrote it), but with more options for output and control.
Version 0.1, 2008.1.26
- Automatically generate a linked table of contents for an article
- Nested output for (X)HTML lists
- Option to filter results with the
- Option to use full URLs
Version 0.1.1, 2008.1.29
- Fixed bug re headings containing HTML tags
Version 0.1.2, 2008.2.03
- Fixed bug (design flaw, actually) re nested list output — thanks to Dejan for spotting this
Version 0.1.3, 2008.2.03
- Code cleaning, plus valid XHTML output even for articles with unsemantic heading structure