00027: Table of Contents

Summary: Table of Contents
Created: 2004-09-04 01:12
Status: Closed - added for 2.2.119 (2019-10-03)
Category: CoreCandidate
From: Jonas?
Priority: 55555 55555 55555 55555 55555 554433 15

Description: Adding of a Table of Contents tag to the standard distribution of PmWiki. Something like PageTableOfContents would be great.

Given the existence of the cookbook script, I'm not quite ready to make this a part of the standard distribution. It needs a few more priority votes and some fleshing out of the basic concepts.



  • the toc entries are Links to the headings
  • <Toc Auto Depth> variable to define the heading depth that gets displayed like: (:toc depth=2..5:) (:toc depth=3:)
  • possibility to display the toc in a other page (for example in a sidebar) without the constraint to have the directive also in the target page (:toc name=OtherPage:)
  • either replicate all the functionality of Cookbook.PageTableOfContents or write it in a way that a cookbook recipe can add just the missing features (in particular, it should work with creole markup).
  • the headings optionally has a link to the toc
  • toc can be sorted or in natural order (:toc order=heading:) (:toc order=natural:)
  • provide alignment (:toc align=right:)

more general suggestion

  • Compatible to Cookbook.NumberedHeaders
  • if there is a link form the toc to the heading, there will be a anchor on the heading. To have a anchor on every heading in pages per default (not with the anchor markup) could be very useful. Maybe, it could be a way to make a script for building automatically anchors on headings (setable for all pages or just for pages with a toc) and a toc script that makes a list of headings with a link to it. noskule

I don't think I'm ready to say that I'll replicate *all* of the functionality of Cookbook.PageTableOfContents -- it's a little too feature-rich and specific for the core. However, I am fully committed that whatever we design will allow Cookbook/PageTableOfContents to continue to work, most likely by allowing it to simply add any features that don't make it into the core. --Pm

It's also worthy of note that TOC is a core feature in many currently popular wiki engines (e.g. MediaWiki, Dokuwiki). MateuszCzaplinski

Pagelist of anchors

Actually I think PageTableOfContents is the wrong model for a ToC core candidate. I'd like to see it based on the pagelist concept, except it applies to anchors in a page. Since the pagelist area is being reviewed (eg looking at including attachments as well) possibly generating lists of anchors would not be too far fetched. Elsewhere (PITS.00955) it has been suggested that anchors be generated automagically for all heading, something I'd like to see. Together these two suggestions would provide the solution. simon October 16, 2009, at 11:28 PM

I agree with simon. I think that with adding to PageList a new attribute anchors we could fully extend more easily the pagelist direcive with PageListTemplates. This implementation could look like this: (:pagelist group=PmWiki name=pit* anchors=current|all :) . This is the last thing missing from my TOC implemented through a custom PageListTemplates that requires no php code writing RobertThomas?

I don't understand this suggested solution, or at least its connection with pagelists. Do you mean you would like a markup with a similar syntax and similar templating capabilities but centered around anchors (something like (:anchorlist name={$FullName} anchorname=TOC*:)?) Or do you really mean to extend (:pagelist...:) itself? If the latter can you help me understand the use of it? Or maybe how the template would look? Would you have a new (:template anchor:) section that would repeat or something? Then would you need a new (:template anchorfirst:) and etc as well? It does not seem trivial by any stretch of the imagination... Peter Bowers September 19, 2010, at 12:00 AM

(:pagelist name=thispage anchor=* fmt=#mytoc:)

(:template defaults order=anchor:)
(:template first {=$Anchor}:)
!!!!  {=$Namespaced} table of contents
(:template anchor:)
* [[{=$FullName}#{=$Anchor}|{=$Anchorspaced}]]

Note that recursive pagelists could be used to provide ToCs for multiple pages.

simon September 20, 2010, at 04:52 AM
now added specifically as PITS.01224 for discussion

Being less implicit would make life easier

Request moved from PmWiki:InitialSetupTasks-Talk.

I add the following to this talk page because every time I setup a new PM-Wiki same things popup into my brain and hurts it. Don't get me wrong: I love PM-Wiki otherwise I would use another wiki. In most cases its pretty easy to use ...but It there are some issus make me go crazy:

Why this hand made TOCs

A lot of pages offer "hand made" Table Of Contents - Well.. it might be a good idea to define by wiki-syntax what should appear in a TOC..BUT if I would like to have a TOC anywhere (especially those floating boxes) and how the look and was formatted should be configurable.

Why don't you use some more .tmpl Files for those things with has to have a placeholder where the generated list is inserted. Anyway.. the way its done now is not a real help to get a nice clean looking wiki.

It would be help enough to give all TOCs an unique CSS class so anyone who don't like em can easily hide em by display:none;.

Jan Bernitt?

If not part of the core, I would certainly like some sort of TOC-recipe enabled on this wiki. Hand-made TOCs are fine and dandy, but they aren't automatic; that's why we're using a computer and not a notebook in the first place, right?

I'm not going to argue for placing a toc-tag in a site- or group- header; manually insertion into desired pages would be fine (especially since there are quite a few small pages where it would be inappropriate). Michael Paulukonis February 25, 2014, at 10:05 AM