Name Date Size #Lines LOC

..--

navigatorlabels/H29-Mar-2026-456248

CHANGELOG.mdH A D29-Mar-20261.7 KiB3429

LICENSE.txtH A D29-Mar-20261.1 KiB2418

README.mdH A D29-Mar-20264.1 KiB14695

README.md

1<!-- Folder structure finalized on 2026‑03‑18 -->
2
3# NavigatorLabels Plugin
4*A helper plugin providing multilingual sorting, AUTOINDEX support, and customizable UI vocabulary for the Navigator theme.*
5
6## Overview
7NavigatorLabels extends the **Navigator** theme with helper functions and configuration options that keep navigation calm, predictable, and multilingual‑friendly.
8
9The plugin provides:
10
11- **Multilingual article‑stripping** for natural alphabetical sorting
12- **AUTOINDEX integration** for Navigator’s autolist behavior
13- **Customizable UI labels** for the theme’s top bar and navigation vocabulary
14- **Unicode‑aware normalization** for consistent sorting across languages
15
16NavigatorLabels is designed specifically for the **DokuWiki** engine and integrates seamlessly with the Navigator theme.
17
18---
19
20## Features
21
22### Multilingual Sorting Engine
23NavigatorLabels removes leading articles and elisions before sorting page titles.
24This produces natural alphabetical order across multiple languages.
25
26Supported out of the box:
27
28- **English:** the, an
29- **French elisions:** l’, d’, qu’
30- **Portuguese:** a, as, o, os, um, uma, uns, umas
31- **Spanish:** el, la, los, las, un, una, unos, unas
32
33
34The list is fully configurable in the Admin panel.
35
36### AUTOINDEX Handling
37NavigatorLabels provides internal helper functions used by the Navigator theme to:
38
39- detect the `~~AUTOINDEX~~` marker
40- normalize titles
41- generate calm, predictable autolists
42
43When combined with the **Navigator** theme, the marker remains invisible to readers while still being detected by Navigator.
44
45### Customizable UI Vocabulary
46Administrators can define the labels used in the Navigator top bar via the Admin Configuration Settings, allowing:
47
48- multilingual wikis
49- custom terminology
50- simplified or domain‑specific navigation
51
52### Unicode‑Aware Normalization
53The plugin handles:
54
55- punctuation
56- hyphens
57- apostrophes
58- NBSP and thin spaces
59- French elisions
60- accented characters
61
62This ensures consistent behavior even when titles come from Word, PDFs, macOS, or multilingual sources.
63
64---
65
66## Installation
67
681. Place the navigatorlabels plugin folder in:
69   `<your_wiki>/lib/plugins/`
70
712. Visit:
72   **Admin → Configuration Settings → NavigatorLabels**
73   to customize:
74
75   - articles to ignore when sorting
76   - top‑bar labels
77   - other Navigator‑specific vocabulary
78
79No additional configuration is required for basic operation.
80
81---
82
83## Configuration
84
85### Articles to Ignore When Sorting
86A multiline field allows administrators to define a comma‑separated list of articles and elisions.
87
88**Default example:**
89
90a, as, o, os, um, uma, uns, umas,
91the, an,
92el, la, los, las, un, una, unos, unas,
93l’, d’, qu’
94
95
96The plugin is Unicode‑aware and accepts both `'` and `’`.
97
98### Top Bar Labels
99NavigatorLabels exposes several UI vocabulary fields used by the Navigator theme.
100These can be customized to match your wiki’s language or tone.
101
102---
103
104## Sorting Behavior
105
106NavigatorLabels normalizes titles before sorting by removing leading articles and elisions defined in the configuration.
107
108Examples:
109
110| Original Title                     | Normalized | Sorted Under |
111|-----------------------------------|------------|--------------|
112| A Casa                            | Casa       | C            |
113| The Journey                       | Journey    | J            |
114| El Camino                         | Camino     | C            |
115| L’Été                             | Été        | É            |
116| D’Amour                           | Amour      | A            |
117| Navigator is cool (if configured) | is cool    | I            |
118
119Normalization is:
120
121- Unicode‑aware
122- punctuation‑aware
123- NBSP‑safe
124- multilingual
125
126---
127
128## Compatibility
129
130- **DokuWiki:** Greebo → current
131- **PHP:** 7.4+ and 8.x
132- **Themes:** Designed for the Navigator theme; safe alongside others
133- **Languages:** Fully multilingual
134
135---
136
137## Changelog
138
139The complete development history is kept in
140**[CHANGELOG.md](CHANGELOG.md)**
141to ensure a single, consistent source of truth.
142
143This README focuses on usage and configuration.
144
145---
146