It's better when it's simple

User Tools

Site Tools


Numbered Headings Plugin

Compatible with DokuWiki

  • 2024-02-06 "Kaos" unknown
  • 2023-04-04 "Jack Jackrum" yes
  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" yes

plugin Adds numbered headings to DokuWiki without changing the actual behavior of the standard headings.

Last updated on
Conflicts with
ckgedit, htag, include

Tagged with headings, style


Search and install the plugin using the Extension Manager.

Alternatively, refer to Plugins on how to install plugins manually. Download the plugin package and unpack it to your plugin-directory (lib/plugins/). This will create a new folder called numberedheadings.


Adding a “-” before the heading text will make the headings tiered-numbered. You can choose the first-tier level (tier1) in the Configuration manager. The tier1 may be a fixed value (eg. level 2) or auto-detected in the page. You can use “-#<number>” to set number of the heading.

====== - Level 1 Headline ======
===== - Level 2 Headline =====
==== -#5 Level 3 Headline ====
==== - Level 3 Headline ====
===== -#7 Level 2 Headline =====
==== - Level 3 Headline ====

When the config tier1 is set to 2, the headings are interpreted as if you have written:

====== Level 1 Headline ======
===== 1. Level 2 Headline =====
==== 1.5 Level 3 Headline ====
==== 1.6 Level 3 Headline ====
===== 7. Level 2 Headline =====
==== 7.1 Level 3 Headline ====

Experimental: Alpha-numeric numbering

Character variables can be incremented in PHP, like A0, A1, A2 … You can use -"<string>" to set number string of the heading.

==== -"A1" Appendix ====
=== - headline ===


The plugin can be configured within the DokuWiki configuration manager available through the admin menu.

tier1 heading level corresponding to the 1st tier default = 21)
format numbering format (used in vsprintf) of each tier, JSON array string
fancy styled heading numbers default = off

Auto-Detect first-tier level

When the config tier1 is 0, the heading level where the numbered headings used first in the page will be set as tier1 value in the page. You can use appropriate 1st-tier level in different pages.

Numbering format

The config format defines tiered numbering style. Each tier format is the formatting string of sprintf, must be enclosed in double quotes ("). If n-th tier format is not defined, numbers are simply joined with period char. Some format examples:

["%d.", "%d.%d", "%d.%d.%d", "%d.%d.%d.%d", "%d.%d.%d.%d.%d"]
["Chapter %d.", "Section %d.%d", "Subsection %d.%d.%d", "(%4$d)"]
["Model %04d", "%04d-%02d"]

Control numbering feature

The numbered headings that are prefixed with “--” (instead of single “-”) are not rendered, but can be used to specify level numbers or tier format.

assume config tier1 is set to 0
=== --#1000 ["(%04d)"] ===   ... set number and tier format of the level, invisible 
=== - item 1 ===    → (1001) item 1
=== -- ===             ... initialize tier1, format, headings counter
==== - item 2 ====  → 1. item 2

You can also override the first-tier level in a per-page basis. Just insert this code to your page:


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


The Numbered Headings plugin was initially developed by Lars J. Metz, and provided provided for convenience to use with the DokuWiki plugin manager: numberedheadings.tar.gz (3kB) or (4kB)

Since 2019-01-02, the plugin code has moved to github repository to provide better accessibility for install and further development opportunity. Thanks Lars J. Metz for your early work and encouraging me to move the code to github. — s.sahara 2019-01-02 03:40

Change Log from github repository

Old Revision List

  • 2006-08-25 — Published Plugin
  • 2008-09-04 — Added startlevel per-page setting (mat)
  • 2010-05-11 — Added the availability to show a tailingdot
  • 2010-05-12 — Brought startlevel and tailingdot out to configuration (refactored the code)
  • 2019-01-02 — Added new macro to set startlevel in a page
  • 2019-01-03 — Allow css for tiered numbers in headings


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

Old Discussion

Could a similar system be used to format the numbered lists in nested decimal style instead of the crazy roman numerals and stuff? Better with just changing the css maybe? If so any ideas how best to do that? Armin.

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
Unfortunately I couldn't do anything here, but it works fine with page-includes (include) at the moment Lars J. Metz 2010/05/12 17:51

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

Seems like the changes in Rincewind metadata handling means that the numbering sometimes doesn't start from 0 anymore. Any plans to update for the official new release? - Senorandy 2011/05/03 11:01

Per page start level

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, 2008-09-04

Thanks — Lars J. Metz 2010/05/12 18:08

Set outline level for each heading

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

=== 3 Heading level 1 ===
== 3.1 Heading level 2 ===

Martin Klima

Added it in the Usage-Section. Thanks — Lars J. Metz 2010/05/12 18:08

Css for heading numbers

Fantastic plugin! I was wondering if anyone knows what I would need to modify to add tags like


around the heading numbers. This would allow them to be differently styled, positioned, and even do cool things like section numbering outside the margins of printed documents (what I'm trying to do.)

I have tried messing with the code myself, but any html I add shows as text, and not interpreted as real html code. Could anyone figure this out? - kououken 2012/02/07 14:32

Suggestion / Request

Great plugin - Can I make a request to:
- Include an option by wiki, to do this automatically (without the hyphens) for all pages
- Disable option by page, when enabled at wiki level
- Enable the option by page by a setting at the top of the page


I just developed this feature for my own needs. The code is available from Feedbacks are welcome. So this version adds:

  • an option to enable numbering by default on every page
  • the possibility to use {{enable_numbering}} or {{disable_numbering}}

Start pages with sub level

I would like to break up longer pages into subpages. These new pages then should to start numbering at a sub level.

For example:

====== - #3.1 Level 1 Headline ======
===== - Level 2 Headline =====

should be rendered as:

3.1 Level 1 Headline
    3.1.1 Level 2 Headline

What changes to syntax.php would be necessary in order to accomplish that?

More flexible numbering

Some modification. For example:

=== Chapter - Heading level 1 ===

will be rendered

=== Chapter 1 Heading level 1 ===


=== Chapter -#2 Heading level 1 ===

will be rendered

=== Chapter 2 Heading level 1 ===

Just replace some regular expressions:

//line 68:
        $this->Lexer->addSpecialPattern( '^[ \t]*={2,6}[^\n\-]*\-[^\n]+={2,6}[ \t]*(?=\n)',
//line 90 to line 94:
        if (preg_match('/#([0-9]+)/', $match, $startnumber) && ($startnumber[1]) > 0) {
            $this->headingCount[$level] = $startnumber[1];
            //delete the startnumber-setting markup from string
            $match = preg_replace('/#[0-9]+/', '', $match);
//line 119:
        $match = preg_replace('/(={2,}[^\-]*)\-/', '${1}'.$headingNumber, $match);

But this will make '-' unusable in headings. To avoid the problem, change like this

//line 68:
        $this->Lexer->addSpecialPattern( '^[ \t]*={2,6}[^\n\-]*\s{1}\-\s{1}[^\n]+={2,6}[ \t]*(?=\n)',
//line 90 to line 94 and line 119: same as above


=== SST-2003 ===

will be still

=== SST-2003 ===


=== SST - 2003 ===

will be

=== SST 1 2003 ===

lainme 2010/06/20 03:24

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.
plugin/numberedheadings.txt · Last modified: 2023-09-13 08:34 by s-sahara

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki