README.md
1# DokuWiki Plugin: Priority List
2**Priority List** is a custom DokuWiki plugin that automatically generates a reverse-chronological list (newest first) of pages whose titles start with one, two, or three plus signs : `+`, `++`, `+++`
3
4It is particularly useful for highlighting priority blog posts, important announcements, or "featured" articles without having to maintain a manual list.
5
6## Features
7
8- **Automatic Detection**: Recursively scans a namespace (and all its subdirectories) to find pages whose H1 title (`======`) starts with `+`, `++`, or `+++`.
9- **Smart Sorting**: Displays results by last modification date, from newest to oldest.
10- **Tag Support**: Automatically detects and displays tags associated with each page (using `{{tag>...}}` syntax).
11- **Universal Compatibility**: Works regardless of your DokuWiki `savedir` configuration (custom data directory names are supported).
12- **Customizable**: Allows you to define the target namespace and limit the number of results.
13
14## Installation
15
161. Download this plugin or copy the `prioritylist` folder into the `lib/plugins/` directory of your DokuWiki installation.
17 ```bash
18 mkdir -p lib/plugins/prioritylist
19 # Copy the syntax.php file into this folder
20
21 Ensure the folder permissions allow read access by the web server.
22 No additional registration is required; the plugin is detected automatically.
23 Important: Clear the DokuWiki cache after installation via the URL doku.php?id=admin:rebuild_cache or by adding ?purge=true to any page URL.
24
25## Usage
26
27Insert the following syntax into any wiki page to display the list:
28Basic Usage
29
30Displays priority posts from the default namespace (billets):
31
32 <prioritylist />
33
34Specify a Namespace
35
36To target a different folder (e.g., my:custom:namespace):
37
38
39 <prioritylist ns=my:custom:namespace />
40
41### Limit Results
42
43To display only the 10 most recent priority posts:
44
45 <prioritylist ns=billets limit=10 />
46
47### Required Page Format
48
49For a page to appear in the list, it must meet two conditions:
50
51The Title: The first level-1 heading must start with at least one + sign.
52
53 dokuwiki
54 ====== + My Important Post ======
55
56 or
57
58 dokuwiki
59 ====== ++ Major Announcement ======
60
61Tags (Optional): If you use standard DokuWiki tag syntax, they will be automatically extracted and displayed next to the title.
62
63 {{tag>thriller reviews important}}
64
65Example Output:
66
67 + Alberto Vignati, Hedonia (thriller; reviews)
68
69## File Structure
70
71
72prioritylist/
73├── syntax.php # Plugin core (scanning logic, sorting, and rendering)
74└── README.md # This file
75
76## Technical Notes
77
78- Performance: The plugin reads only the beginning of files (approx. 8 KB) to extract the title and tags, making the scan fast even on large document bases.
79- Fallback Mechanism: If the native DokuWiki API fails to list pages (in rare complex configurations), the plugin uses a manual recursive scanner to ensure no pages are missed.
80 Compatibility: Tested on DokuWiki "Hogfather" and newer versions.
81
82## Author & Support
83
84This plugin was custom-developed for the Radeff.red blog.
85
86Author: Frédéric Radeff
87
88Email: fradeff@akademia.ch
89
90Website: https://radeff.red/blog/
91
92## License
93
94This plugin is provided "as is" for personal or internal use. You are free to modify and redistribute it according to your needs.
95
96