Plugin Numbered Headings

To use this plugin just add a '-' between the '=' and the actual heading:

====== - Level 1 Headline ======
===== - Level 2 Headline =====
==== - Level 3 Headline ====
==== - Level 3 Headline ====
===== - Level 2 Headline =====
==== - Level 3 Headline ====
...

The output should then look like this:

1 Level 1 Headline
    1.1 Level 2 Headline
        1.1.1 Level 3 Headline
        1.1.2 Level 3 Headline
    1.2 Level 2 Headline
        1.2.1 Level 3 Headline
...

To install the plugin:

1. Add a folder named header to your plugin-directory (lib/plugins/).
2. Create a file called syntax.php in the new folder.
3. Paste the code below into the new file and save it.
4. The plugin is now installed.

Alternatively you may use one of the following links (at your own risk), these links are provided for convenience to use with the DokuWiki plugin manager: header.tar.gz (1.5kB) or header.zip (1.6kB)

You can configure the heading-level (in syntax.php) to start with numbering (default = 2):

var $startlevel = 2;

The example above generates the following output:

Level 1 Headline
    1 Level 2 Headline
        1.1 Level 3 Headline
        1.2 Level 3 Headline
    2 Level 2 Headline
        2.1 Level 3 Headline
...

As I use a sidebar-index showing the first heading instead of the filename, I configured the plugin to start with the numbered headings from H2 on. Otherwise the numbers would be shown in the index… but feel free to change the level to 1.

You can also override this value in a per-page basis. Just insert this code to your page:

{{header>n}}

Where n is a number between 1 and 5, so your numbering will start in the heading level specified there.

This is the actual plugin-code.

<?php
/**
 * Plugin Numbered Headings: Plugin to add numbered headings to DokuWiki-Syntax
 * 
 * Usage:   ====== - Heading Level 1======
 *          ===== - Heading Level 2 =====
 *          ===== - Heading Level 2 =====
 * 	          ...
 * 
 * =>       1 Heading Level 1
 *              1.1 Heading Level 2
 *              1.2 Heading Level 2
 *          ...
 * 
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Lars J. Metz <dokuwiki@meistermetz.de>  
 */
 
if(!defined('DOKU_INC')) define('DOKU_INC',realpath(dirname(__FILE__).'/../../').'/');
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');
 
class syntax_plugin_header extends DokuWiki_Syntax_Plugin {
 
    // level to start with numbered headings (default = 2)
    var $startlevel = 2;
 
    var $levels = array( '======'=>1,
                         '====='=>2,
                         '===='=>3,
                         '==='=>4,
                         '=='=>5);
 
    var $headingCount = 
                 array(  1=>0,
                         2=>0,
                         3=>0,
                         4=>0,
                         5=>0);
 
    function getInfo(){
        return array( 'author' => 'Lars J. Metz',
                      'email'  => 'dokuwiki@meistermetz.de',
                      'date'   => '2008-09-04',
                      'name'   => 'Plugin: Numbered Headings',
                      'desc'   => 'Adds numbered headings to DokuWiki',
                      'url'    => 'http://www.dokuwiki.org/plugin:NumberedHeadings');
    }
 
    function getType(){
        return 'substition';
    }
 
    function connectTo($mode) {
        $this->Lexer->addSpecialPattern('{{header>[1-5]}}',$mode,'plugin_header');
        $this->Lexer->addSpecialPattern( '^[ \t]*={2,6}\s?\-[^\n]+={2,6}[ \t]*(?=\n)',
                                         $mode,
                                         'plugin_header');
    }
 
    function getSort() {
        return 45; 
    }
 
    function handle($match, $state, $pos, &$handler){
        // Obtain the startlevel from the page if defined
        if ( !strncmp('{{header>', $match, 6) ) {
            list($nothing, $levels) = explode(">", $match);
            $levels = trim( str_replace("}", '', $levels) );
            $this->startlevel = $levels;
            return array();
        }
 
        // define the level of the heading
        $heading = '';
        preg_match('/(={2,})/', $match, $heading);
        $level = $this->levels[$heading[1]];
 
        if(preg_match('/#([0-9]+)\s/', $match, $startNum) && is_numeric($startNum[1])) {
 
            //if the user set the level
            $this->headingCount[$level] = $startNum[1];
            //delete the level-setting markup from string
            $match = preg_replace('/#[0-9]+\s/', ' ', $match);
        }
        else {
 
            // increment the number of the heading
            $this->headingCount[$level]++;
        }
 
        $headingNumber = '';
        for ($i=$this->startlevel;$i<=5;$i++) {
 
            // reset the number of the subheadings
            if ($i>$level) {
                $this->headingCount[$i] = 0;
            }
 
            // build the number of the heading
            $headingNumber .= ($this->headingCount[$i]!=0) ? $this->headingCount[$i].'.' : '';
        }
 
        // insert the number (without the last '.')...        
        $match = preg_replace('/(={2,}\s?)\-/', '${1}'.substr($headingNumber,0,-1), $match);
 
        // ... and return to original behavior
        $handler->header($match, $state, $pos);
 
        return true;
    }
 
    function render($format, &$renderer, $data) {
        //do nothing (already done by original render-method)
    }
}
//Setup VIM: ex: et ts=4 enc=utf-8 :

• 2006-08-25 — Published Plugin
• 2008-09-04 — Added startlevel per-page setting (mat)

Feel free to make any comments regarding my plugin… or write me an email (Lars J. Metz).

This is so basic, it should be in the basic installation of DokuWiki IMHO… diftong@gmx.net

Would be good to bring the start level out to configuration.

Great thing, just what I was looking for, there is just one issue in combination with page-includes (include), they are not renumbered correctly, for each include page they start with 1. The same for headlines in the original page. 2006-09-19 23:31 Dirk 'el loco' Haage

I'm currently working on a fix, so that included pages are numbered correctly. I'll release it soon… 2006-09-27 09:45 Lars J. Metz

Hi, I'm having a hard time making DokuWiki to view the saved files after the plugin is installed. When I click save, everything dissapears. I have to load from the startpage again, because the reload doesn't work (postdata). Do you have any idea why this plugin does this? If I remove the plugin DokuWiki works well 2006-11-17 13:20 Robert Popa

I saw this same behavior when I added Debian backports, and got DokuWiki-0.0.20061106-1~bpo.1 It looks like the fix is to remove the trailing ?> (last line) from the script above. That fixed it for me, and matches the syntax.php for all the other plugins I have installed. 2006-11-21 11:51 Rob Walsh

For your information: I just wrote a different approach for numbered headings (per CSS). — Anika Henke 2008-01-06 16:02

I've just merged the code for adding the ability to set the startlevel in a per-page basis. Just added the first line of connectTo and the first if in handle.

Also, added the instructions for using.

— mat, 04-09-08

I have added the ability for the user to set the outline level with the following markup:

=== - #<number> Heading text ===

For example:

=== - #3 Heading level 1 ===

== - Heading level 2 ===

will be rendered

Martin Klima