Table of contents

A basic table of contents (TOC) and Numbered headings (NH) are included in PmWiki 2.2.119 and can be enabled with the following in config.php:

$PmTOC['Enable'] = 1;

Usage

The feature is based on the recipe Cookbook:AutoTOC but is somewhat simpler.

• The table of contents is automatic, there is no need to add some markup in the wiki page.
• It is inserted right before the first heading in the wiki page.
• By default, only pages with 3 or more headings will have a table of contents.
• The visitors can close or open the table of contents, and their last choice will be remembered by their browsers in "localStorage". It is then used also for other pages. And it is used, if the Wiki is revisited later, as long as the "localStorage" is not cleared in the meantime.
• The feature can automatically number the headings in the page.
• Headings in hidden sections ("comment" wikistyle, "display:none") will not be included in the TOC.
• Headings with the %notoc% class will not be included in the TOC.
• Headings in (:markup:) blocks are ignored.

The following directives in the wiki page can control the above features:

• (:toc:) the table of contents will be inserted at this position (rather than the default one), even if there are less than 3 headings in the page.
• (:notoc:) no table of contents will appear on the page, even if there are 3 or more headings, or a (:toc:) directive. If you have only one heading in a page, you may wish to use (:notoc:) to suppress numbering.
• Both directives can be placed anywhere in a page, even in included pages such as a sidebar or a header.
• On a page with both (:toc:) and (:notoc:) the latter wins and there will be no table of contents.

The TOC will use anchors or identifiers of the headings from the page, if they exist, otherwise it will create a new identifier (hash) based on the structure of the page. The following markups will all create a link with the anchor PageUrl?#here:

• !! Heading with id %block id=here%
• !! Heading with inline anchor [[#here]], or
• !! [[#here]] Heading with inline anchor
• [[#here]]
!! Anchor preceding the heading

If there is no identifier or anchor with a heading, then the anchor will be in the form #toc-1.2.1 where 1.2.1 is the structural path to the section, in this example "Section 1, subsection 2, sub-subsection 1".

Configuration

The following local configuration (in local/config.php) can control the default settings:

• $PmTOC['Enable'] = 1; # enable TOC and/or NH, default is disabled.
• $PmTOC['MaxLevel'] = 6; # heading levels included in the TOC
  by default <h1> to <h6> are included. Set to 3 to only include <h1> to <h3>.
• $PmTOC['MinNumber'] = 3; # minimum number of headings in the page for the TOC to be generated.
  Pages with few headings are usually short and do not need a TOC.
  • $PmTOC['MinNumber'] = 2; # pages with 2+ headings will have a TOC
  • $PmTOC['MinNumber'] = 9999999; # the TOC will not be automatic, only the (:toc:) directive will create a table of contents in the page.
• $PmTOC['NumberedHeadings'] = '1.1.1.1.1.1'; # the headings will be numbered (default disabled).
  • You can set here the numerals for the different levels of headings, can be 1 (numeric), I or i (Roman numerals), A or a (letters A-Z or a-z). For example, a specification like
    $PmTOC['NumberedHeadings'] = 'I.1.a';
    will number the biggest level headings on a page with uppercase Roman numerals (I, II, ...), the second biggest with numbers, the third with lowercase letters (a, b, ...), and the remaining levels (if any) with numbers.
  • $PmTOC['MinNumber'] = 9999999; # only enable Numbered headings without creating a TOC. You still need to set $PmTOC['Enable'] = 1;
• $PmTOC['EnableBacklinks'] = 1; # insert after the headings "↑" arrows linking back to the table of contents (default disabled).
• $PmTOC['ParentElement'] = "#wikitext"; # the query selector of the parent HTML element where the TOC block to be inserted
  by default the TOC is inserted before the first heading; here you can select a different element. If selected, the TOC will be inserted in the element at the top. The (:toc:) directive in the page can override this element.

Internationalization

The following strings can be translated in XLPage?, for example in French:

  "Contents" => "Sommaire",
  "show"     => "afficher",
  "hide"     => "masquer",

Styles

If you prefer to see the TOC on the right side, you may want to insert the following in your $PubDirUrl/css/local.css file:

.PmTOCdiv {
    float: right;
    margin-left: 5px;
  }

You can modify the table elements font size and maximum table height by defining in your $PubDirUrl/css/local.css file:

.PmTOCdiv { 
    font-size: 15px; 
    max-height: 600px;
  }

The default font size is 13px and the default maximum height is 500px, you can define own values. When the table height exceeds the max-height value, there is a scrollbar (overflow:auto).

See also: Cookbook:AutoTOC. If you previously used AutoTOC? you need to disable it when enabling $PmTOC.