1# DokuWiki Plugin Numbered Headings
2
3Prepend tiered numbers for hierarchical headings to DokuWiki without changing
4the actual behavior of the standard headings.
5
6## Configuration
7
8| Parameter  | Description                                                          |
9| ---------- | -------------------------------------------------------------------- |
10| tier1      | heading level corresponding to the first tier (default = 2)            |
11| format     | numbering format (used in vsprintf) of each tier, JSON array string  |
12| fancy      | styled heading numbers (default = false)                             |
13
14default numbering format: `["%d.", "%d.%d", "%d.%d.%d", "%d.%d.%d.%d", "%d.%d.%d.%d.%d"]`
15
16## Usage
17
18Adding a `-` before the heading text will make the headings tiered-numbered.
19You can choose the first tier level (**tier1**) in the Configration manager.
20The **tier1** may be a fixed value (eg. level 2) or auto-detected in the page.
21You can use `-#<number>` to set number of the heading.
22
23    ====== - Level 1 Headline ======
24    ===== - Level 2 Headline =====
25    ==== -#5 Level 3 Headline ====
26    ==== - Level 3 Headline ====
27    ===== -#7 Level 2 Headline =====
28    ==== - Level 3 Headline ====
29
30When the config **tier1** is set to 2, the headings are interpreted as if you have written:
31
32    ====== Level 1 Headline ======
33    ===== 1. Level 2 Headline =====
34    ==== 1.5 Level 3 Headline ====
35    ==== 1.6 Level 3 Headline ====
36    ===== 7. Level 2 Headline =====
37    ==== 7.1 Level 3 Headline ====
38
39### Auto-Detect first tier level
40
41When the config **tier1** is 0, the first appeared numbered headings should define
42the value of **tier1** for the page.
43You can use different first tier level in each page.
44
45### Numbering format
46
47The config **format** defines tiered numbering style.
48Each tier format is the formatting string of
49 [sprintf](https://www.php.net/manual/en/function.sprintf.php "sprintf"),
50must be enclosed in double quotes.
51If n-th tier format is not defined, numbers are simply joined with a period.
52Some format examples:
53
54    ["%d.", "%d.%d", "%d.%d.%d", "%d.%d.%d.%d", "%d.%d.%d.%d.%d"]
55    ["Chapter %d.", "Section %d.%d", "Subsection %d.%d.%d", "(%4$d)"]
56    ["Model %04d", "%04d-%02d"]
57
58### Control numbering feature
59
60The numbered headings that are prefixed with `--` (instead of single `-`)
61are not rendered, but can be used to sepecify level numbers or tier format.
62
63    assume config tier1 is set to 0
64    === --#1000 ["(%04d)"] ===   ... set number and tier format of the level
65    === - item 1 ===    → (1001) item 1
66    === -- ===             ... initialise tier1, format, headings counter
67    ==== - item 2 ====  → 1. item 2
68
69### Experimental: Alpha-numeric numbering
70
71Character variables can be incremented in PHP, like A0, A1, A2 ...
72You can use `-"<string>"` to set number string of the heading.
73
74    === --"A0" ["%s."] ===
75    === - item a1 ===   → A1. item a1
76    === - item a2 ===   → A2. item a2
77    == - item a2.1 ==   → A2.1 item a2.1
78
79