Summary: Talk page for PageTableOfContents.
Maintainer: jr
Users: +7 -1 (View / Edit)

This space is for User-contributed commentary and notes. Please include your name and a date along with your comment.

  • I need a markup such as (:toc-end:) that will stop the table of contents from continuing down the page at any level. That is necessary when using GroupFooter, or similar markups that write on the bottom of the page. Thanks!

Yes, Carlos (next post) and I are hitting at the same problem; the GroupFooter, SiteFooter and other footer pages are included, as well as code that follows the actual toc material. You cannot make a toc that is limited just to the material you want toc'ed. Here is an example: Notice that the bottom of page coding is also included in the toc.

Jagtig 4/8/2018

I don't see anywhere in the code a reference to including the GroupFooter page.

CarlosAB April 08, 2018, at 11:38 PM

Hi Jagtig, here is a new version that accepts (:toc-end:). pagetoc-end.phpΔ

CarlosAB April 17, 2018, at 09:40 AM

Hi CarlosAB, a slight change to the pattern in Markup('toc') makes the (:toc-end:) optional so that pagetoc-end.php can be used on other sites' existing pages:


Jagtig, the PageTableOfContents recipe is working as advertised. The footer on all of your site's pages is not being created by the normal GroupFooter method. Instead, one of the recipe or config files is appending the site footer (or an (:include:) of it) directly to the end of your not yet markup2html processed page text, where pagetoc sees it.

ChuckG April 18, 2018, at 09:47 PM

I was about to do that, thank you ChuckG.


CarlosAB April 19, 2018, at 01:17 AM

  • is there a method of restricting the toc to only a single level?
  • it would be useful to have a parameter that specified max-width for the toc
simon December 09, 2015, at 03:19 PM

There is a potential conflict with the Toggle recipe.

I've installed both in the same wiki before and noticed no issues.

Today, however, I installed PageTableOfContents first, and then Toggle.

Toggle was non-functioning until I moved the Toggle include to before the PageTableOfContents include. / Then both Toggle and PageTableOfContents were functional (on the same page even).

I have not investigated the code for what might be conflicts, nor have I tried in isolation with no other recipes installed.

MichaelPaulukonis June 26, 2014, at 01:21 PM


I've checked the code, and I believe the conflict lies in the definition of the 'toggle' markup (lines 190..200), which is the same name as that used by the Toggle recipe.

It would be great if this recipe could either 1) check to see if toggle is installed and use it if present or 2) use a recipe-specific name like toc-toggle.

MichaelPaulukonis June 27, 2014, at 08:25 AM

HansB November 02, 2017, at 05:53 AM: I agree with #2, it would be best if PageTOC uses a different markup, like (:toc-toggle :) and a different markup name, than the Toggle recipe. But I am not sure why the script uses (:toggle...:) internally at all, as there is no mention for users to use this markup in PageTOCs context.

Is PageTableOfContents supposed to work with Pagelists? I have a custom format that outputs the group-page as an H2, and the sub-pages as indents underneath. my (:*toc-float:) directive picks up headers on manually-coded elements elsewhere in the page, but ignores those coming from the pagelist.

Also, PageTableOfContents seems to be ignoring my custom anchors when they precede the header -- like in the following:

!! This is an example section
With some data in it that I want to include in another page

I put the anchors before the H2 so that when I include the section, it will grab the heading-tag.

Is there a way to get PageTableOfContents to respect these custom anchors? It's not the biggest deal in the world, but mousing over the TOC and seeing "#toc3" is an annoyance.

UPDATE: I had been using v2.0.31, but after updating to 2.0.38 the above behaviors are still present.

MichaelPaulukonis July 05, 2013, at 11:00 AM

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 for error example

Update: If i add a line to the page start, the header (:toc:) works. This unfortunately isn't a good solution. One has to add a line every time the page gets updated.


It looks as if this is caused by the order in which directives are evaluated. The toc script only picks up heading markup with a preceding "\n". I have changed the sequence of toc processing so it gets evaluated after the (:nl:) markup in the group header has been translated into "\n". I was able to replicate the problem and it went away after I changed the markup sequence. Download the latest version (2.0.13) and see if it fixes the problem. jr

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>

<Header End>


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

If you have the MarkupExtensions installed, put =>(:toc-back:) on a line by itself. This right aligns the paragraph and omits it from the printable view. jr

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

Brent, you need to include the $TocFloat=False statement before the include statement because of the way the css properties are set. David A Spitzley
Thanks, David. That explains it. Brent

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
TOC is in printable view as of the 20 Sep 2005 version. If the toc is numbered, the headings are also numbered. If you have the PublishPDF library installed, the toc gets page numbers in the pdf version.It's not currently in the printable view, because the current toc design is primarily an online navigation aid. The PublishPDF library also generates a proper document toc and section numbering for multipage print collections. jr

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


should be

 "$toc1 "

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.
This will require a bit of code juggling to accomplish. In the mean time, an administrator could create local/Group.Page.php files to set the desired float characteristics on a per-page basis. The toc syntax will probably need to change so it can have a number of parameters in any order, for example like the pagelist directive.
I've tried local/<Group>.<Page>.php method, but it does not have any effect. Could you, please, verify it? Roman
$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
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.
You should be able to set $RemoteTocFmt = '<b>On page [[$Toc#toc |+ ]]...</b>'; to show the remote page's title. jr
For me it doesn't work but $RemoteTocFmt = '<b>[[$Toc |+ ]]...</b>'; is fine. nico


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


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

Good idea. At the moment, all text is in variables or controlled through the directive itself. I will investigate adding XLPage support.

21-Feb-2006 Christoph Claus

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

At the moment, Show/Hide is, by popular request, a given. You want to be able to turn this off, so the toc is always displayed?
Yes please
Change line 235 to $toggle = "";

April 1, 2006
I've got an odd problem with two-line TOC entries:
!!Article 1\\

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?


Do the headings include %center% wiki styles? If so, the code will pick these up in the toc entry text. Any center and right styles are removed in version 2.0.31. jr

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

The fastest way to achieve this is to change "float: right;" to "float: left;" in the definition of div.tocfloat. But we can probably make this a parameter...

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.

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:))
Sidebar page table of contents example
  • 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
         <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".

To change the default width follow the above instructions for customising your template. Then add the following to the skin's css file
  div.tocfloat {
    width: auto;
    min-width: 12em;
    maxwidth: 24em;

Just a bump for the earlier query about having a numbered TOC that doesn't also have, or suppresses, the numbers on the headers.
Des August 13, 2006, at 11:51 AM

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

1. 1. A “Má Fama” da Monografia
2. 2. A Cultura do Processador de Textos
3. 3. Lógica da Edição de Textos

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?

José Geraldo

Is it possible to enhance the toc markup to be able to specify the default to rolled up for a particular page?
Is it possible to have all headings displayed at the same level of indentation (ie none)?
Is it possible to specify the range of headings to be shown in the page toc, eg say I only want to display h2, h3, and h4?
Is it possible to have the toc also pick up included pages (pmwiki-2.2.0-beta15) (they are being included by a pagelist fmt variant). Alternatively can I use a wildcard, eg (:toc-page SomeGroup/*:)?
thanks Simon

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?


Are there any plans to add the level=n feature ? Francis


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.

  • By trial and fail, I make it working by modifying pagetoc.php as follows
    • Line 27: change 'display: none;' to the stylesheet of ol.toc.
    • Line 51: switch the if/else block: test 'block' set 'none, else set 'block'. (This should not be needed, but I have to click twice to expanded a hidden toc. I do not know why.)
    • Line 236: Change default string to ToggleText[1].

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.

Garth McMillan


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



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


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


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

see "Limitations" on this Page


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


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


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?



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>";


2008-11-25 Wanted to add this to the GroupHeader file, but people were getting annoyed at having the full TOC on some pages. Heres a patch to call the toggle function if the toc markup is used with the hide=true directive added, e.g (:toc hide=true:) will generate a table with the toc body already closed.

--- pagetoc.php	2008-11-25 15:50:52.000000000 +0000
+++ pagetoc.php	2008-11-25 15:49:07.000000000 +0000
@@ -152,9 +153,9 @@
-    '/\(:([#\*])?toc(?:-(float|hide))?(?:\s+anchors=(v)isible)?(?:\s+(.*?))?(?:\s+(Q))?:\)(.*)$/se', 
-    "TableOfContents(\$pagename,'$1','$2',PSS('$4'),'$5',PSS('$6')).
-    TocEntryAnchors('$3',PSS('$6'))");
+    '/\(:([#\*])?toc(?:-(float|hide))?(?:\s+anchors=(v)isible)?(?:\s+hide=(true|false))?(?:\s+(.*?))?(?:\s+(Q))?:\)?(.*)$/se', 
+    "TableOfContents(\$pagename,'$1','$2','$4',PSS('$5'),'$6',PSS('$7')).
+    TocEntryAnchors('$3',PSS('$7'))");
 SDV($TocBackFmt,'&uarr; Contents');
     "'[[#toc | '.TocLinkText(PSS('$1')).']]'");
@@ -169,9 +170,9 @@
     if ($tocname==$pagename && $self==0) return '';
-    if (preg_match('/\(:([#\*])?toc(?:-(float|hide))?(?:\s+anchors=(v)isible)?(?:\s+(.*?))?(?:\s+(Q))?:\)(.*)$/se',$toctext,$m))
+    if (preg_match('/\(:([#\*])?toc(?:-(float|hide))?(?:\s+anchors=(v)isible)?(?:\s+hide=(true|false))?(?:\s+(.*?))?(?:\s+(Q))?:\)(.*)$/se',$toctext,$m))
         $toc = str_replace('[[#',"[[$ref#",
-            TableOfContents($tocname,$m[1],'page','',$m[5],PSS($m[6])));
+            TableOfContents($tocname,$m[1],'page',$m[4],'',$m[6],PSS($m[7])));
     $TocHeaderFmt = $oTocHeader;
     return $toc;
@@ -210,7 +211,7 @@
   return $r;

-function TableOfContents($pagename,$number,$float,$title,$includeq,$text) {
+function TableOfContents($pagename,$number,$float,$hide,$title,$includeq,$text) {
     global $DefaultTocTitle,$TocHeaderFmt,$IdPattern,$NumberToc,$OmitQMarkup,
@@ -238,6 +239,8 @@
         $f = ($TocFloat) ? 'float' : '';
         $toc = "<div class='toc$f'><p>$toc$toggle</p>" . 
                "<$sc id='$tocid'><$l>\$List</$l></$s></div>";
+	if($hide == 'true')
+		$toc.= "<script type=\"text/javascript\">toggle('$tocid')</script>";
     preg_match_all("/\n(!+|Q?:)\s*(\[\[#+$IdPattern\]\]|#*)([^\n]*)/",$text, $match);
     for ($i=0;$i<count($match[0]);$i++) {


I'd really love to see the above code worked in as an option in the "official" release... I hate to have to keep trying to patch every time a change is made...


Somebody earlier asked about defaulting the TOC to 'collapsed' mode, so that you need to click on the 'show' toggle link to expand it... Here's how...

Alter line 289 in pagetoc.php from

return $r;


return $r . " <script type=\"text/javascript\">toggle('tocid');</script>";

This will automatically toggle the TOC to hidden whenever the page is loaded.



To have a more balanced display of the TOC, I had to add the following lines in pagetoc.php:

ul.toc {margin-top: 7px}
ul.toc ul.toc {margin-top: 5px}

just before the ol.toc line.

Hope it helps. Ciao!


The numbered TOC has a problem: seems it output an unneeded digit that is overwritten by the first character of the title. Something like:

 1. 1Mytitle
     1.1 1Second
     1.2 2Third

Where the last digit is bold and actually over the first character of the title.



PROBLEM with Category links in headers: if a header has a category link in it as in the following line

  !!!! [[!Catlink]] header item 

the table of contents displays only [[ for this item.
All the text of the header is gone. I am using the latest pagetoc.php and pmwiki-2.2.4


This question was asked before but not answered yet: How can one have a numbered TOC that does not put numbers in front of any header (like in Wikipedia)? Thanks in advice, elb


I've made some changes so that the TOC is now capable to deal with deeper levels, too. Basically my modification calculates an outline for the TO first and renders it afterwards. The maximum number of levels that shall be displayed can be configured with the parameter MaxTocDepth. The default is obviously 2 in order to keep compatibility with the current codebase. Sine I'm definitely no PHP developer the code should be reviewed (at least it works for me). Especially the function InsertAnchors which is now always generating anchors should be reviewed. Also the Q-Markup support should be verified (I personally have no clue what Q-Markup is).


Bye Daniel Kasmeroglu


The CSS code and the Javascript code has been extracted into external resources (so they're better customisable). The InsertAnchor now uses the tree information, too so level 3+ headings will have the correct chapter number. The Show/Hide feature can be disabled using the new parameter TocToggle now.

NOTE: I didn't took care of Q-Markup and such stuff, so there's still probably some work to be done. However it's working for the usual markups.


Bye Daniel Kasmeroglu


Added some fixes as I'm obviously not a php expert. Mainly to generate xml compliant outcome.


Bye Daniel Kasmeroglu


Ran into PITS 01319 - preg_replace /e depreciation with php 5.5.7 and pmwiki 2.2.61. An example is at line 211, function TocEntryAnchors().


Bob Sanders

Talk page for the PageTableOfContents recipe (users).