authors (basic)
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
%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. If you have only one heading in a page, you may wish to use (:notoc:) to suppress numbering.
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; $PmTOC['MaxLevel'] = 6;$PmTOC['MinNumber'] = 3;$PmTOC['MinNumber'] = 2; $PmTOC['MinNumber'] = 9999999; (:toc:) directive will create a table of contents in the page.
$PmTOC['NumberedHeadings'] = '1.1.1.1.1.1'; - 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; $PmTOC['Enable'] = 1;
$PmTOC['EnableBacklinks'] = 1; $PmTOC['ParentElement'] = "#wikitext"; (: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.
