PageTableOfContents

Summary: Adds a clickable table of contents to a page
Version: 2017-11-08
Status: Stable
Prerequisites: pmwiki 2.2.56 and above (requires php 5.3 or above, compatible with php 7)
Maintainer: jr
Users: +7 -1 (View / Edit)
Categories: Markup, TOC, PHP55, PHP72

Goal

Generate a table of contents for a wiki page, using any headings found on the page.

Solution

Please note. The PublishPDF library includes the PageTableOfContents recipe. When typesetting a page as PDF, the toc entries gain page number references.

The latest version 2.1.3 (released 2017-11-08 for compatibility with php 5.5 and php 7) avoids use of the deprecated /e modifier in calls to Markup and avoids Markup_e:

Older version:

pagetoc2_0.phpΔ -- this is a stable release. It uses the new directive markup and works with version 2.0 dev 17 and later. (if you notice strange font, try this pagetoc.phpΔ, "&ensp" are changed in "&nbsp", so it's displayed better in most browsers)

Put pagetoc.php in your cookbook/ directory.

Add the following line to local/config.php

    include_once("$FarmD/cookbook/pagetoc.php");

Some usage notes in relation to other scripts:

  • if using the toggle script, add $ToggleMarkup = false; to local/config.php before including pagetoc-php (added in version 2.1.3)
  • it recognises some of the extra markups in MarkupExtensions (run-in heads and Q: markup), but should have everything it needs to work correctly as a stand-alone script
  • if you are using MarkupExtensions, you must use version 2.0.5 or above (to preserve script independence, several items moved out of version 2.0.4 into pagetoc)
  • PageTableOfContents suppresses the toc in printable view, but PublishWikiTrail turns action='print' into action='browse', so put include pagetoc.php above include publish.php removed by popular request
  • It stops looking for headings when it reaches a (:breakpage:) directive
  • It removes center and right alignment styles from toc entries

Discussion

The simplest usage is to add the following line on any wiki page

    (:toc:)

That's it. Any headings and questions after the toc directive will be listed, to 2 levels. Once Some Page contains a (:toc:) directive, you can put the following on any other page (remote tocs)

    (:toc-page Some Page:)

You can make the anchors a toc creates visible by writing

    (:toc anchors=visible:)

If you have entered your own anchors, it uses these. If you want to make your own anchors visible, write [[##anchor]] instead of [[#anchor]]

You can change the default heading text by writing

    (:toc Replacement Heading:)

You can combine visible anchors and a replacement heading by writing

    (:toc anchors=visible Replacement Heading:)

You can change the numbered list (in case $NumberToc is true) to an itemised list by writing

    (:*toc:)

You can change the itemized list (in case $NumberToc is false) to a numbered list by writing

    (:#toc:)

You can make the anchors visible and replace the heading here too.

You can control inclusion or exclusion of Q: markups by writing

  (:toc Q:)

This will cause toc to omit Q: markups. An administrator can also set $OmitQMarkup to true in config.php to omit Q: markups by default. In this case, (:toc Q:) will cause toc to include Q: markups.

You can use wiki markup in your headings and toc will work out suitable link text. Well, it's supposed to...

Standard PmWiki 2 markup supports [[#anchor | text]]. PageTableOfContents extends this in 2 ways:

    [[#anchor | #]] uses the text of the paragraph after [[#anchor]]
     as the link text

    [[#anchor | *]] uses "anchor" as the link text

To create a link back to the table of contents (which automatically has a [[#toc]] anchor), write

    (:toc-back:)

To specify the text to be used for the link back, write (for example):

    (:toc-back Back to Table of Contents:)

Subsequent (:toc-back:) references will also use this value.

If you use PmWiki/WikiStyles in headings that will appear in the toc, be sure to close them explicitly with %% markup. Otherwise, the style will apply to all following toc item entries.

If you have the MarkupExtensions installed, you can omit a heading from the toc by using "invisible stop" markup:

`.!!An omitted heading

See http://intranet.affinity.co.nz/pmwiki2/index.php?n=PmWiki.TextFormattingRules -- the sample headings do not appear in the toc. If you don't have the MarkupExtensions recipe installed and want to omit headings, add the following to your config.php file

    Markup("`.",'>links',"/`\./",'');

To generate a table of contents for a remote page write

    (:toc-page Some Page:)

Some Page must include a (:toc:) directive, as toc-page uses this to find where on the page to start, and ensures the correct anchor links get inserted on the target page. Alternatively, an author can use the

   (:toc-hide:)

directive on Some Page. This will cause toc-page to pick up headings after the toc-hide directive, insert the necessary anchors, but does not display a table of contents. The toc-hide directive supports all toc variants; for example (:#toc-hide anchors=visible:) will number the entries and show the anchors. Note: toc-hide does not insert an anchor at the toc-hide position, so toc-back won't work on pages with a toc-hide directive -- there is no toc to go back to.

By default, (:toc-page:) doesn't display a toc if the page name is the current page. You can override this by writing:

    (:toc-page Some Page self=1:)

You can configure the floating of the table of contents by using the

  (:toc-float:)

The $TocFloat configuration variable (see below) specifies the default position of the table of contents. By default, (:toc-float:) floats the TOC on the right.

Configuration variables

variabledefault settingcomment
$DefaultTocTitle"On this page..." 
$TocHeaderFmt"[[#toc]]<b>$TocTitle</b>"
$VisibleAnchor§ 
$VisibleAnchorLinksfalsevisible anchor has title; true makes it href
$TocSize'smaller'set $TocSize = 'medium'; or other before you include the pagetoc script. jr
The code to set the style runs as soon as the script loads, so you have to set the size first
$NumberToctruetoc entries are numbered
$OmitQMarkupfalse 
$TocBackFmt"↑ Contents" 
$RemoteTocFmt'<b>On page [[$Toc(#toc)]]...</b>' 
$TocFloatfalsetrue floats toc to the right of the page and reverses the semantics of (:toc-float:).
$ToggleTextarray('hide', 'show')for the clickable toc (set this variable before including the recipe)

Limitations

The code that builds the table of contents is messy. To extend this to support more than 2 levels would require a complete re-write of the TableOfContents function.

History

03 Aug 2012 include $GroupHeaderFmt in text for toc-page option
04 Aug 2006 remove alignment styles and improve toc styling
11 April 2006 fix show/hide problem with toc-page in sidebars
30 March 2006 add self=1 option to (:toc-page:) and use different toggle-id
15 Mar 2006 add (:toc-hide:) directive
09 Feb 2006 make the toc clickable (show / hide link)
07 Nov 2005 add $DefaultTocAnchor and (:toc-float:)
02 Oct 2005 adjust number styles and indents
20 Sep 2005 add numbering to headings if the toc is numbered
21 Sep 2005 add border and light grey background colour by default
04 Jul 2005 add option to float toc to the right of the page
27 Mar 2005 add (:toc-page Some Page:) to create a toc for a remote page
22 Feb 2005 add a capability to omit headings defined with (:markup:), eg so PmWiki/TextFormattingRules can have a nice toc
13 Feb 2005 fix bug that omitted a start of page heading when the toc directive is in a GroupHeader page -- thanks to Jota
27 Jan 2005 add support for (:toc Q:) markup to control inclusion or omission of Q: markups -- thanks to Christian
25 Jan 2005 fix incompatibility with pmwiki beta 19, which led to invalid html being generated
4 & 10 Jan 2005 add (:toc-back:) directive for a link back to the table of contents -- thanks to Christian
17 Nov 2004 fix offset notice when processing definition list markup for autonumbered anchors -- thanks to Christian
8 Nov 2004 remove style that controls indenting of itemised lists -- thanks to PRZ
7 Nov 2004 add support for a (:#toc:) variant to create a numbered toc when $NumberToc is false
4 Nov 2004 really fixed the invalid HTML bug; added itemised list markup option and font-size control
3 Nov 2004 fixed invalid HTML bug (I think) -- thanks to Val

Contributor

jr

See also

PmWiki /
TableOfContents  Basic automatic table of contents and numbered headings
Cookbook /
Accordion  lightweight Accordion javascript requiring no framework (stable)
AutoTOC  Unobtrusive Automatic Table of Contents links (stable)
HandyTableOfContents  Handy Client-side Table of Contents (stable)
NumberedHeaders  Display numbered headers, indented paragraphs and table of contents (Stable)
NumberedSections  Add section numbers on a page (stable)
QuickPageTableOfContents  Adds a dropdown clickable table of contents to a page - client side processing (Stable)
SlimTableOfContents  Simple or Numbered Table of Contents, Compatible with SectionEdit Recipe (not working with php5.5)
PmWiki /
TableOfContents-Talk  

Comments

See discussion at PageTableOfContents-Talk

User notes +7 -1: If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.