Table of Contents
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
Similar to titlesanchorlink
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.
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”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) |
Events
This plugin triggers events when paragraphs are opened and closed, i.e. PLUGIN_PURPLENUMBERS_P_OPENED
and PLUGIN_PURPLENUMBERS_P_CLOSED
.
Version history
- Merge pull request #25 from selfthinker/fix-php-errors (2024-01-21 01:33)
- version 2024-01-21 (2024-01-21 01:31)
- fix declaration of functions to be compatible with Doku_Renderer_xhtm… (2024-01-21 01:30)
- fix unsupported array with curly braces (2024-01-21 01:28)
- Merge pull request #22 from dokuwiki-translate/lang_update_897_153079… (2018-11-15 00:27)
- translation update (2018-07-05 13:55)
- Merge pull request #21 from dokuwiki-translate/lang_update_665_151362… (2018-04-16 22:42)
- translation update (2017-12-18 20:40)
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 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 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 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