• View
• Edit
• History
• Attach
• Print
• Backlinks

PageTableOfContents

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.5 (2024-04-11 with more compatibility fixes for php 8, changes suggested by John Rankin)

The 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:

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

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

Contributor

jr

See also

Comments

See discussion at PageTableOfContents-Talk