• 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.

• Download pagetoc-2025-01-22.phpΔ
• Put pagetoc.php in your cookbook/ directory.
• Add the following line to local/config.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

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)

You can make the anchors a toc creates visible by writing

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

You can combine visible anchors and a replacement heading by writing

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

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

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

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

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

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

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:

If you don't have the MarkupExtensions recipe installed and want to omit headings, add the following to your config.php file

To generate a table of contents for a remote page write

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

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:

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

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

 pagetoc2.phpΔ, "&ensp" are changed in "&nbsp", so it's displayed better in most browsers)''

Contributor

jr

See also

Comments

See discussion at PageTableOfContents-Talk