authors (basic)

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'] = ''; # 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.

This page may have a more recent version on PmWiki:TableOfContents, and a talk page: PmWiki:TableOfContents-Talk.