It's better when it's simple

User Tools

Site Tools


PurpleNumbers Plugin

Compatible with DokuWiki

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

plugin Adds “Purple Numbers” (granular IDs) and optionally comment links to every block level element

Last updated on

Similar to titlesanchorlink

Tagged with links, section

Needed for editions

This plugin adds Purple Numbers (granular IDs) to every block level element (<h1-5>, <p>, <li>, <pre> and <table>) for better addressability. Optionally links to comment pages are added per block element as well.

Download and Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

:!: After the installation you need to set the renderer_xhtml config option to purplenumbers to switch from the core renderer to the purplenumbers renderer.


  • numbering type:
    • hierarchical (default, should normally be preferred, is more stable)
    • consecutive (if you have a flat page structure, with hardly any or no headlines, this could make sense)
  • uniqueness:
    • page-wide (default)
    • site-wide (adds the page ID, should be used if the purple numbers will be used together with other plugins which include other pages or parts of other pages, e.g. blogs)
  • internalID: create IDs that can be used as internal anchors (Attention: this means those IDs can potentially be created within the wiki and might not be unique, e.g. if your Purple Number is “ID75” and you have a heading “ID75” on the same page, this ID is ambiguous and will be the same for both)
  • linkText:
    • paragraph/section sign (default, § for headlines, ¶ for the rest) – for this option the link to the annotationPage (if enabled) will be just an icon
    • ID (better for accessibility, but takes more space) – for this option the link to the annotationPage (if enabled) will be an icon plus the text “comment”
  • restrictionNS: restrict usage of plugin to these first level namespaces (comma separated)
  • restrictionType:
    • include (default; i.e. the plugin will only be used on pages included in those namespaces which are specified in restrictionNS)
    • exclude (i.e. the plugin will only be used on pages excluded in those namespaces which are specified in restrictionNS)
  • annotationPage: pattern for links to annotation pages (leave empty to disable), this can include certain placeholders (@PN@ for just the numeral part of the Purple Number, @PNID@ for the whole ID, @ID@ for the whole page ID including namespaces and @PAGE@ for just the pagename excluding namespaces), e.g. annotation:@PAGE@-@PNID@ on a page like “articlename” with a PNID of “ID5” would result in the page “annotation:articlename-id5” and @ID@:note-@PN@ on a page like “foo:bar:article” with a PN of “1.5:16” would result in “foo:bar:article:note-1_5-16”
  • includeStartpage: display Purple Numbers on start pages? (makes it possible to exclude PNs on start pages)

Examples for types of IDs

Examples in brackets are produced when internalID is switched on.

numbering = hierarchical numbering = consecutive
uniqueness = page-wide ID1.5:16 (id1_5-16) ID75 (id75)
uniqueness = site-wide wiki:syntax.1.5:16 (wiki-syntax_1_5-16) wiki:syntax.75 (wiki-syntax_75)


This plugin triggers events when paragraphs are opened and closed, i.e. PLUGIN_PURPLENUMBERS_P_OPENED and PLUGIN_PURPLENUMBERS_P_CLOSED.

Version history


This looks like a very useful tool, may well solve an information architecture puzzle I've been struggling with for some time with my larger projects requiring detailed internal cross-referencing.

It would be very useful if there were links to at least one demonstration wiki, ideally both examples where PN is used in “production”, as well as a sandbox/playground to check it out when deciding whether or not to implement.

Thanks for all of your FOSS contributions, they appear to valuable extensions to DW's functionality and created/maintained to a very high standard.

Question - when new content is added to the page/file, does everything get re-numbered and inbound links (to the source location and/or annotations-comments page) will now be broken??

It depends. The way it is done, you cannot guarantee links to each Purple Number will stay intact, but you can maximize the chance of it. When you're using a hierarchical numbering and your pages are of a very hierarchical nature, chances are most links will still work after you added something. But with a consecutive numbering or very flat pages, more links will get broken.
There are other solutions of Purple Numbers out there which have solved that specific problem, but they all need a database. In the end, this means that you should not use this plugin for typical wiki pages (when a lot of pages are bound to change all the time), but for text which is less likely to change.
One example installation which uses this plugin is (used within the “edition” namespace). That site doesn't use the latest version and the version it uses was also changed a bit, but the general functionality is the same. — Anika Henke 2011/11/24 00:21

It would be really useful if we could have a configuration option to restrict the links to headings only (not to other paragraphs). I find having it on every paragraph to be very distracting.

The other improvement would be to tone down the icon - it probably should be purple ;) or maybe grey.

UPDATE 2012-03-26: To change the color and size of the mark, I've edited lib/plugins/purplenumbers/style.css:

.dokuwiki {
    color: #aaa !important; font-size:60% !important;

It would be easy enough to leave the marks hidden on certain block types as well using just the css.

Julian Knight 20012-03-23

I agree that changing the CSS is the best way to do it. But I would advise against changing the CSS in the plugin, as those changes would be overwritten with an update. Better use user styles for that. — Anika Henke 2013/03/24 16:03

Hello. I think this plugin has a lot of potential. There's still a great need for fine-grained referncing, as is evidenced by programs like Obsidian, Logseq, and the Streams plugin for TiddlyWiki. Ted Nelson is also still promoting his ideas.

This plugin, however, falls short on a few fronts. Firstly, it's a real bummer that links break when paragraphs are inserted or rearranged. The comment pages get associated with the wrong paragraphs as well, that's really bad. My request is for a third numbering system to be implemented where every paragraph gets a unique, randomly generated ID which persists. Perhaps anchor links can be inserted into the page code itself, so that they are seen when editing the text, and can be copy/pasted along with the paragraphs when one moves them around. My second request is that the paragraph gets highlighted when clicked, so that it becomes clear what paragraph is being referenced even when the article is too short for scroll operations. — Antithesis 2022/09/22

plugin/purplenumbers.txt · Last modified: 2024-01-21 01:35 by ach

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