DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:purplenumbers

PurpleNumbers Plugin

Compatible with DokuWiki

  • 2013-12-08 "Binky" yes
  • 2013-05-10 "Weatherwax" yes
  • 2012-10-13 "Adora Belle" yes
  • 2012-01-25 "Angua" yes

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

Last updated on
2012-10-26
Provides
Render
Repository
Source

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

Download and install the plugin using the Plugin Manager using the URL given above. 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.

Configuration

  • 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”

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)

Version history

Feedback

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 Paralis.org (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 HenkeAnika Henke
ach

London, UK
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 a.pn {
    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 KnightJulian Knight
TotallyInformation

Sheffield, UK
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 HenkeAnika Henke
ach

London, UK
2013/03/24 16:03
plugin/purplenumbers.txt · Last modified: 2014/03/23 12:51 by ach