Summary: Unobtrusive Automatic Table of Contents Version: 20111019 Prerequisites: Status: Beta Maintainer: Petko Categories: Menus, TOC, Layout, WikipediaSuite Users: (view? / edit) Discussion: AutoTOC-Talk?
For an intranet wiki, I needed a really basic, simple and fast Table of contents, that:
- works in all existing pages without the need to edit them and add some markup,
- works even when the headings in the page are not in a logical hierarchy,
- works even when the headings in the page come from included pages or from pagelists,
- works with the TOC block either in the wiki page, or in the SideBar,
- can be disabled on some pages,
- can be moved to a different place in a page,
- can be shown or hidden by the users and their preferences can be remembered,
- wouldn't risk to break some complex local recipes on that wiki.
AutoTOC was inspired by the tables of contents in Wikipedia:
- a page with less than 3 headings is usually short and doesn't need a TOC
- it is possible to force a TOC for 1-2 headings with a special markup
- it is possible to disable the TOC for 3+ headings with a special markup
- the TOC is automatically inserted right before the first heading in the page and after the short introduction / summary
- it is possible to place the TOC anywhere in a page with a special markup.
- Copy autotoc.php Δ to your pmwiki/cookbook directory.
- Copy autotoc.js to your pmwiki/pub directory.
- Add to config.php such a line:
- A reader can show or hide the Table of contents with a show/hide link. The TOC state (open or closed) will be remembered when the reader opens another page.
- A page with 3 or more headings will have the Table of contents inserted right before the first heading.
- The wiki markup
(:toc:)at the beginning of a line places the table of contents there, even if there are less than 3 headings.
- The directive
(:notoc:)disables the Table of contents.
To select the levels of the headings included in the Table of Contents, set in config.php, before including the recipe, such a line:
$AutoTocMaxLevel = 3;
Setting 3 will mean !, !! and !!! headings will appear in the TOC; default is 6, ie. ! to !!!!!!.
To select the minimal number of headings in a page which enable Tables of contents, set in config.php, before including the recipe, such a line:
$AutoTocNbHeadings = 4;
Default is 3 headings, a page with fewer headings than this number will not display a TOC unless it has the
If you want TOCs appearing not automatically on all pages, but only in pages with the
(:toc:) markup, set the $AutoTocNbHeadings variable to a very big number like 999.
'Contents' => "Sommaire", 'show' => "afficher", 'hide' => "masquer",
Change log / Release notes
- 20111019 : fix bug with tables
- 20111018 : headings inside
(:markup:)blocks are now skipped from the table of contents.
- 20111008 : generated anchors changed from numeric incremental to a simple encoding of the heading text, outlined at PITS:00955, for example #Installation.
- 20111007 : fix HTML validation bug.
- 20111006 : fix indentation to the lowest common level of headings in the page.
- 20111005 : added
- 20111004 : first public release, ready to be tested.
Recipe written and maintained by Petko.
Tes~t with tab'les