Table of contents

Home

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

  $PmTOC['Enable'] = 1;

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 visitor can close and open the table of contents, and his preferences will be remembered in "localStorage".
• 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 %block 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.

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".

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

• $PmTOC['Enable'] = 1; # enable TOC, default is disabled.
• $PmTOC['MaxLevel'] = 6; # levels of headings that are included in the TOC, by default <h1> to <h6> headings are included. Set to 3 to only include <h1> to <h3> headings.
• $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'] = -1; # 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['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.

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

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

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

• Edit
• History
• Source
• Attach File