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

NumberedHeaders

Goal

1/ Setting numbered headers, like

2/ Indenting the text following the header level

3/ Set a table of contents of said headers

Answer

Load the file numtoc.zipΔ

Copy the file numtoc.php in the cookbook directory

Set in the local/config.php file the line :

  include_once('cookbook/numtoc.php');

Documentation page PmWiki.NumberedHeaders will go in /wikilib.d directory.

You should make a reference to this page in the PmWiki.Documentation Index and probably also in a page describing the particularities of your own wiki.

Notes and comments

• This recipe was last tested on PmWiki version: 2.2.0.beta57
• This recipe requires at least PmWiki version: 2.?
• php code size : 3.5 ko.

Usage

Use it with the usual headers !, !!, !!! -> !!!!!!
This is limited to four levels but can start from any level.
This is on purpose, please take care of your readers by making small pages, an easy task on a Wiki.

- Numbering

To have numbered headers, set the directive (:num:) and the headers will be numbered after the directive setting. (:nonum:) stops the numbering. The numbering starts from the first numbered header level seen:

!!general header (not numbered)
(:num:)
!!Header numbered
!!!Subheader numbered
!!!Subheader...
!!Another Header
!!!Subheader
(:nonum:)
!!Header not numbered (Annex..)
!!Header not numbered (Annex..)

- Table of Contents

To have a page table of contents, set the directive (:toc:):

!general header - not in toc
''' Table of Contents'''
(:toc:)
!Header
!!Subheader
!!Subheader
!Another Header
!!Subheader
(:notoc:)
!A new Header - not in toc
!!Subheader - not in toc

directive (:notoc:) stops the table of contents recording, but only one table of contents can exist in a page.

The table and indentation will work on 4 levels maximum.

- Indentation

To have text indented following the header level, set the directive (:indent:) before the first header. The indentation margin is based upon the first header seen after the directive. Anything below that level will show strange results

(:indent:)
!!general header
!!Header
!!!Subheader
!!!Subheader...
!!Another Header
!!!Subheader
(:noindent:)
Text not indented

The browsers default headers being way too large, if they are not redefined in your skin, you may want to set in your config.php the below text, which give more reasonnable sizes.

 
$HTMLStylesFmt['numheader'] = " 
  h1 {font-size:132%; margin:20px 0px;}
  h2 {font-size:124%; margin:16px 0px;}    
  h3 {font-size:116%; margin:12px 0px;}
  h4 {font-size:108%; margin:12px 0px;}  
";

Note that if css files are defined in the /pub/css directory, they will override the hereabove settings.

Site example :

• http://www.rouzeau.net/w3/pmwiki.php?n=Main.TableOfContent

Options

You can define the numbering type with a parameter in the directive (:num:) , like (:num A-1.a.1) :), which gives you the following numbering

Styling

You can override the default styling which are as follows.

The table of contents is in a container with the class .tocstyle . Default content of the class : empty.

The indentation of the table of contents is defined by the following classes :

 
$HTMLStylesFmt['nmhtoc']= "
  .toc1 {margin-left:1em;}
  .toc2 {margin-left:2em;}
  .toc3 {margin-left:3em;}
  .toc4 {margin-left:4em;}  
";

The indentation of the text blocks is defined by the following classes :

 
$HTMLStylesFmt['nmhindent']= "
  .indent1 {margin-left:1.25em;}
  .indent2 {margin-left:2.5em;}
  .indent3 {margin-left:3.75em;}
  .indent4 {margin-left:5em;}  
";

And the header have a negative indentation compared to the hereabove. This is defined in a variable :

 $HdrIndStyle = 'text-indent:-1em;';

Restrictions

You should deactivate the recipe PageTableOfContents of John Rankin.

Instead of the recipe of John Rankin, there is no parameter for (:toc:) directive. Only a naked directive will work.

The Q: markups are listed in the table of contents. If you don't want that, deactivate the markup '^Q:toc'.

History

• V0.1 First issue feb. 2005
• V0.3 Issue with table of contents 20 feb. 2005
• V0.4 Allow start at a level > 1 - 20 feb. 2005
• V0.5 Corrected bug with [[link|text]] - 22 feb. 2005
• V0.6 Corrected bug w/ smileys - added (:notoc:) in footer - 14 mar. 2005
• V0.7 Added the Tom patch to remove styling - 6 dec. 2006

Discussion

Is there any way to make it so if my second header is longer than one line it will indent that line as well? Right now my second header is indented on the first line, but it spills over to a second line in the TOC that is not indented. Looks very sloppy, any ideas? Thanks, Bryan.

I am trying to include a TOC on every page, I have put the TOC code in Main.GlobalHeader and inserted thise file in my theme. However unless I use the TOC code in the page itself it does not show up, and then of course I have two :) How might I get a TOC on top of every page?

I would like to see a option for horizontal line before each header (level 1). I doesn't work with indent, because the line starts at the last subheader indent. I have tried noindent, ---- and then indent but after some headers there are strange effects.

I've increased the maximum level of headings from 4 to 6 (the maximum recognized by PmWiki). You can download it here: numtoc_max.zipΔ if you are interested. //Aidin

Bugs

2.feb.2008 Manne
When invoking the validator on this current page:
This page is not Valid XHTML 1.0 Transitional!
Result: Failed validation, 329 Errors
Perhaps this recipe should get some rework concerning validation. Like this recipe very much.

6.jan.2008, Petr
still the bug where headers containing an anchor (eg [[#anchor]] ) don't display in the toc at all.

31. May 2007, Markus
Every header in my whole Wiki align is left when using this cookbook. %'center'% doesn't work anymore!?

24.May 2007, Lars:
Would it somehow be possible to limit the levels of subheadings displayed? I (on only one page) want the TOC to only contain ! and !!-headings, but not !!!.

A second issue is that special characters (e.g. á) appear in their markup in the TOC (as á), not as the special character. In the heading/subheading they are displayed correctly.

Thanks for your help.

7.Apr.2006 Is it possible to add number restarting? so it's possible to start from number other than 1. Very useful for pages included in other pages, to keep virtual numbering.

You can define a numbering style like (: num 2.1.1.1 :) and it will start numbering at 2, instead of 1.

9.feb.2006, a.l.e:

• The patch by tom should fix a bug when using this module with SectionEdit
• I've also added
  $title = preg_replace("/(.*?)/","<kbd>\\1</kbd>", $title);
  in order to allow preformatted text in the toc!
  i guess that a similar patch could be usefull for italic text.

27.jan.2006, Tom: I dunno how my configuration is set, but I was getting "%block margin-top=0px%" prepended to all of my titles in the TOC. So I added a small fix in my version of numtoc.php below the line that eats the anchors and extracts the text of links.

 
$title = preg_replace ("/(%.*?%)([^%]*)/", "\\2", $title);

This may not be the most elegant solution, but it works for me, and I think it behaves correctly (did some minor testing). If you have any suggestions for improvement, I'd be happy to acquiesce.

As soon styles are used for the heading e.g. this is displayed in the toc-list. Klonk August 31, 2005, at 06:39 AM

Ok, tom patch added on V0.7 - I was willing to use section edit, so discovering the problem... PRZ

See also

• PageTableOfContents

Contributors

• PRZ