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:

• !!#here Heading with id (from PmWiki 2.5.5)
• !! 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['MinNumberedHeadings'] = 2; # the headings will be numbered only if there are at least this many headings.
• $PmTOC['EnableBacklinks'] = 1; # insert after the headings "^" carets 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

To change the "^" caret character in the back-to-table-of-contents links, you can add to pub/css/local.css:

.back-arrow::after {
  /* Use one of the content: lines */
  content: "\2191"; /* ↑ Up arrow */
  content: "\21A9"; /* ↩ Return arrow */
  content: "\2934"; /* ⤴ Up-right arrow */
  content: "\2912"; /* ⤒ Upwards arrowhead */
  content: "\2303"; /* ⌃ Control symbol */
  content: "\21E7"; /* ⇧ Upwards white arrow */
  content: "\2302"; /* ⌂ House */
  content: "\21B0"; /* ↰ Upwards arrow with tip */
  content: "\21A5"; /* ↥ Upwards arrow from bar */
  content: "\25B2"; /* ▲ Black up-pointing triangle */
  content: "\261D"; /* ☝🏻 Up-pointing index emoji */
  /* Or some small text */
  content: "[Contents]"; font-size: 0.6rem; vertical-align: super;
}

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

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

The default font size is 13px and the default maximum height is 40vh (40% of the screen height). When the table height exceeds the max-height value, there is a scrollbar (overflow:auto).

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

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

The numbering for a heading includes all the "parent" levels, like "2.3.1." To only show the number for the current heading, e.g. "1.", add to local.css:

.pmnumwrap > span:not(:last-child) {
  display: none;
}

See also

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