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

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:

• 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

I'm having trouble using (:toc:) in a Group.Header page. It doesn't show the first Header in the Group.Page.

If i use the (:toc:) markup in the Group.Page it works fine. See http://rtr.inesc-id.pt/~rjc/Sala/OutrosDetalhes for error example

~Jota

Yep. It works! :) Thanks!

Although this isn't a problem if the Header only contains the following code Toc didn't work. Again, this isn't a problem. Inserting a line between instructions solves the problem.

<Header Start> (:toc:)

<Header End>

~Jota

Would it be possible to have the (:toc-back:) also to the right of the page (float)? MaBen

Thank you for your help. It works.

Wonderfully useful recipe--thanks for sharing it! Is it possible to turn off the $TocFloat for a page? I have $TocFloat=TRUE in my config file, so I tried using a page customization file, setting $TocFloat=FALSE, for a page, but it's not being recognized for some reason. Is there a directive setting to do this? Best, Brent

12.9.2005

Why is TOC is not in printable view ? Would be possible to number the headings in the page according to the numbers in the generated TOC ? Jiri

06.Nov 2005

There is a problem with the konqueror webbrowser:

Space after numbers wont show correctly. I had to replace " " with a normal (not html formated) space

 "$toc1 "

should be

 "$toc1 "

2005-09-21
2 wishes:

1. ability to specify TOC style (float) in toc directive
   Currently toc style can be specified in Pmwiki configuration by $TocFloat variable, so it is global setting for all pages with TOC directive. We would like to have the ability to specify toc style in toc directive, so different pages could have different appearance of toc.

<?php
$TocFloat = false;
?>

I think I know why. Try adding the following line to the local/config.php file above the instruction to include pagetoc.php (the Group.Page.php file needs to set $TocFloat before pagetoc tests its value; by default, group and page customisations load after local/config.php) jr

include_once("$FarmD/scripts/pgcust.php");

I propose that a more robust solution would be to introduce a (:toc-float:) directive that floats the toc, rather than rely on a configuration variable. Comments? jr

I think (:toc float:) where float is a parameter would be better. (:toc-float:) could have problems with compatibility with existing (:toc:) directives in pages. Or did you mean (:toc-float:) as an additional directive so (:toc:) appearance will be driven by config.php? In that case also (:toc-nofloat:) will be necessary. Roman

(:toc-float:) as of the 07 Nov 2005 version generates a toc after first reversing the setting of $TocFloat. So if $TocFloat is false, (:toc-float:) generates a toc floated right; if $TocFloat is true, it generates an unfloated toc. jr

1. remote TOC - ability to specify own title (or use remote page title)
   Currently (:toc-page Some Page:) directive shows page name as a toc title. We would like to specify our own toc title or use title of remote page.

Roman

10-Oct-2005

I want to combine PageTableOfContents with PmWiki2PDF but the toc is only a numbert list. Which parameter must be configured to get the toc in the right way. I have seen your solution PublishPDF but I could not use your external server in my company.

You could consider setting up your own internal PublishPDF server. We will release the PublishPDF server as open source when it's a bit more stable and can provide services to set it up. The challenge you face is that with PublishPDF the page toc "just works" in print -- there is no configuration required, the internal references are automatically translated into page numbers and the toc is automatically formatted. The ability to do this automatically was one of the reasons we chose a typesetting engine and not HTML to PDF conversion software. It sounds as if PmWiki2PDF is unable to translate the toc output into the correct print form. jr

fraz

In order to translate via *.XLPage, all the texts in pagetoc.php should be enclosed by $[ ].

21-Feb-2006 Christoph Claus

How do I disable the $ToggleText, if I set it to "" the brackets () still remain visible

April 1, 2006

I've got an odd problem with two-line TOC entries:

!!Article 1\\
Name

This shows up as expected in the table of contents during a preview, but only shows Article1\\ when browsed.

July 3, 2006

When I first inserted (:toc:) the table of contents was left aligned. Then for no apparent reason it switched to center alignment. I would like it left aligned again. Any ideas?

KM

If I use toc-float, can I show the table of contents with the text on the left?

August 9, 2006

How do i hide TOC if several pages that have each TOC of them are included in the other page?

-she Ensure the ToC in on the first line of the page. In your include include from the second line onwards.

2006-08-12

How do I get a page table of contents in a side bar that lists the contents of the page body?

• put (:toc-hide:) in every page body that you want a ptoc, hopefully users won't notice or delete it
• in the sidebar put (:toc-page {$FullName} self=1:) (note I unsuccessfully tried (:*toc-page {$FullName} self=1:))

• to customise what you see, you can use CSS in the skin css file, this requires you to change both the skin's template and css files
  • In the .tmpl file ensure that the HeaderText line is before the CSS file include, this ensures that the changes you make to the skin CSS override the embedded CSS generated by the ToC recipe, viz

       <!--HeaderText-->
       <link rel='stylesheet' href='$SkinDirUrl/pmwiki.css' type='text/css' />

  • in the skin css file add the following to suppress the In this page line. div.toc p {display: none;}
  • if you wish to change the colour, background colour, and hide the margins, padding, and border (you will), use the following in your CSS file

      div.tocfloat {
        background-color: black;
        color: white;
        margin : 0px;
        margin-right: 1em;
        padding: 0px;
        border: 0px;
        font-size: small;
        }

It would be very helpful if the pagetoc recipe supported suppression of the "In this page line".

  div.tocfloat {
    width: auto;
    min-width: 12em;
    maxwidth: 24em;
  }

2006-08-13

Just a bump for the earlier query about having a numbered TOC that doesn't also have, or suppresses, the numbers on the headers.

Hi, I am trying to implement the new pagetoc2.php (which seems to be a real improvement) but I am getting numbering two times:

The problem happens both in Mozilla and IE. Unfortunately I cannot test with different skins because the site I am building is very customized and uses my homegrown, three-colum skin. I have succeded in removing the unwanted extra numbers using ol#tocid, ol#tocid li { list-style-type: none} in my stylesheet, but I consider this a "hack". Is there a better way?

2006-10-27

Is it possible to enhance the toc markup to be able to specify the default to rolled up for a particular page?

2007-02-19

I'm using (:toc-page DiscussionBoard/HomePage :). Of course it says On page HomePage, how can I supply a replacement heading (viz (:toc-page DiscussionBoard/HomePage Replacement heading:)), or get the page title ($Title) to be used?

2007-03-20

Are there any plans to add the level=n feature ? http://thread.gmane.org/gmane.comp.web.wiki.pmwiki.user/29915/focus=29999 Francis

2007-04-05

Two questions:

1. Is it possible to have the default view hidden, with only the "On this page...(show)" visible?

• I was able to have default as hidden by setting the CSS for the TOC div to "display:none", then making $ToggleText = array('hide','show'); BenWilson April 23, 2007, at 08:10 AM

-can anyone explain this more? I would really like to add this customization.

2. Can someone please expand on the (:toc-page:) information? I am not clear on how to remove the table of contents for one page. In my case I do not want it visible on my homepage. Currently I have (:*toc:) in Site.Allgroupheader.

2007-05-05

Is it possible to generate table of contents entries to invisible headers, or alternatively, to list items? My page has this:

! section

1. note 1
2. note 2
3. note 3

I want the notes to be referred to in the toc so that readers can see their existence. However, I don't want to promote the list items to subsection headers since then they're typeset too large.

• Why not just use the standard markup and reformat the header text to suit, using such as [-small-], [--smaller--] etc. to undo the unwanted formatting, but retain the header status Des May 07, 2007, at 08:28 AM

Thanks.

2007-07-11

Is it possible to include the TOC in the skin's template file so that it will be visible on all pages? Thanks

2007-11-13

This recipe isn't compatible with Creole headings. Would it be terribly difficult to fix that? -- JonHaupt November 13, 2007, at 05:04 PM

2007-12-06

Right now this only displays two levels of headers (!! and !!!), no more. While I can understand wanting a cutoff, there are times that I'd really like to see at least one further level of hierarchy displayed; I write highly-structured documents, and sometimes that third level of depth is significant. (Also, better instructions in the "Discussion" section of this page on modifying the ToC display via CSS would be nice.) --CrazyDreamer

2008-02-23

I use this recipe in a german wiki and I have include some translations ($[On this page], $[hide], $[show] ...). No problems, except for the (:toc-page ...:)-directive. The output is $[show]. Does anybody know why?
Insert the translation in the orginal file. -- st

2008-03-11

I use this recipe along. I like the floating TOC. But it stops floating reaching a new section. I have to mention that we use section-edit, too. Can't the script float over sections using this recipe?

kt007 March 11, 2008, at 12:06 PM

I'm having the same problem. TOC, Section-edit, and the TriadSkin. Float works just fine in preview - TOC on the right, text on the left then below. But in regular view, TOC is on the right, and text is only below... OtherMichael June, 2008

2008-03-24

I like this script very well. I search a possibility that the script shows a table of content like a line (A B C D E ...). Could anybody help me?

Casio

---

2008-04-16

There's a bug in the code that breaks the "view Source" function of the browser for large TOCs.

The problem is that the HTML code for TOC is one long line, instead of having one line per TOC item.

The solution:

• edit the /pmwiki/cookbook/pagetoc.php file
• replace the line: if ($closel==1) $r .= "</$l><$l>";
• with: if ($closel==1) $r .= "</$l>\n<$l>";

D'de