1# Annotations Plugin for DokuWiki 2 3Word- and sentence-level annotations on wiki pages, stored separately from the page text with threaded replies. Inspired by [Hypothes.is](https://hypothes.is/) and [ep_comments_page](https://github.com/ether/ep_comments_page). 4 5## Features 6 7- **Text-quote anchoring** — select any word or sentence; the annotation is tied to the quoted text plus its surrounding context, so it survives minor edits to the page. 8- **Threaded replies** — any logged-in reader can reply to an annotation, or reply to another reply for a nested discussion. 9- **Open / Resolved status** — mark a discussion closed; resolved annotations turn green. 10- **Gutter markers** — small icons in the left margin show at a glance where annotations live. 11- **Orphan detection** — when the annotated text is removed from the page, the annotation is flagged as orphaned and stays reachable via the counter. Orphaned annotations become read-only (they can only be deleted), and admins can bulk-delete them. 12- **Per-user toggle** — turn the annotation overlay on or off from your user preferences. 13- **No page revisions** — annotations live in a separate file per page; the wiki changelog is never touched. 14- **Localised interface** — English, German, Russian and Japanese, falling back to English for any untranslated string. 15 16## Requirements 17 18- DokuWiki Librarian 2025-05-14b (or a compatible release) 19- PHP 8.0 or later with the `mbstring` extension 20- [usersettings plugin](https://github.com/tracker-user/dokuwiki-usersettings) *(optional — adds the per-user on/off toggle)* 21 22Works in current browsers and as far back as Firefox 78 ESR. 23 24## Installation 25 261. Copy the `annotations/` directory into `{DokuWiki}/lib/plugins/`. 272. If you want the per-user toggle, install the usersettings plugin too. 283. The defaults work out of the box; tune them in the Configuration Manager if you like (see below). 29 30## Configuration 31 32All settings live under **Admin → Configuration Settings → annotations**: 33 34| Setting | Default | What it does | 35|---------|---------|--------------| 36| `color_open` | `#f59e0b` | Highlight colour for open (unresolved) annotations. One hex value; lighter fills, gutter markers and status-pill tints are derived from it automatically. | 37| `color_resolved` | `#4ade80` | Highlight colour for resolved annotations. | 38| `embed_max_bytes` | `131072` | Largest annotation list (bytes) shipped inline with the page. Bigger lists load via a separate AJAX request instead, keeping every page view lean. | 39| `context_length` | `64` | Characters of surrounding text stored on each side of a quote, used to re-locate it after edits and to disambiguate repeated quotes. `0` disables context. | 40| `body_cap` | `10000` | Maximum length (characters) of an annotation or reply body; longer input is truncated. | 41| `entries_per_page` | `25` | Rows per page in the **Admin → Annotations** overview of annotated pages. `0` shows every page on a single page. | 42 43## Usage 44 45### Reading annotations 46 47Annotated text is highlighted in **amber** (open) or **green** (resolved). Click any highlight to open the thread panel inline below that paragraph. 48 49The counter bar above the page content shows how many annotations the page has. If some are orphaned (their text was deleted), a clickable "N orphaned" link opens a drawer at the bottom of the page with those threads. Orphaned annotations are read-only — the quoted text is gone, so they can no longer be resolved, reopened or edited; the thread still shows in full and its author (or an admin) can delete it. 50 51### Creating an annotation 52 531. Select any text on the page. 542. Click the **Annotate** button that appears. 553. Type your comment and click **Annotate** to save. 56 57> You only need to be logged in and able to *read* the page — edit access is **not** required. If you can read a page, you can annotate it. 58 59The **Annotate** button only appears over real page prose. Selecting inside the table of contents, the page-info line, section-edit buttons, or the annotation panels does nothing. If your selection touches an existing annotation — even by a single character — that annotation opens instead of starting a new, overlapping one. 60 61### Replying 62 63Open the thread panel for any annotation and use the **Reply** field at the bottom. Each individual reply also has its own **Reply** button, so conversations can nest. Any logged-in reader can reply. 64 65### Resolving / reopening 66 67Click **Resolve** on an annotation to mark its discussion closed, or **Reopen** to undo that. Any logged-in reader can resolve or reopen. 68 69### Editing and deleting 70 71- You can edit or delete your own annotations and replies. 72- Admins can edit or delete anyone's. 73 74### Admin: bulk operations 75 76Admins see two extra buttons in the counter bar: 77 78| Button | Effect | 79|--------|--------| 80| **Clear resolved** | Permanently deletes all resolved annotations on the page | 81| **Clear orphaned** | Re-checks the page, then permanently deletes the orphaned annotations | 82 83### Admin: annotated-pages overview 84 85**Admin → Annotations** lists every page that has annotations, with three counts: 86 87- **Normal** — annotations whose quoted text is still on the page. 88- **Resolved** — annotations marked done (whatever their anchoring state). 89- **Orphaned** — annotations whose text was deleted from the page. 90 91The counts overlap on purpose: each one matches exactly what its clear button removes, so a 92resolved annotation is also counted under **Normal** or **Orphaned** depending on whether its 93text is still present. 94 95- **Search** by page title or ID, and **sort** by page title or any of the three counts. 96- **Clear resolved** on a row removes just that page's resolved annotations; **Clear orphaned** 97 removes just that page's orphaned ones. 98- **Clear all resolved (N)** and **Clear all orphaned (N)** at the top apply the matching sweep 99 across every page at once. 100 101Each clear re-checks the page server-side before deleting, so the counts are authoritative even 102if the page changed since it was last viewed. Long lists are paginated (`entries_per_page`). 103 104### Turning the overlay off 105 106In **User Preferences** (provided by the usersettings plugin), uncheck **Enable annotations**. The overlay is then hidden for you; your annotations are still stored and remain visible to everyone else. 107 108## License 109 110GPL 2, matching DokuWiki. 111 112--- 113 114**Developers & AI agents:** see **[DESIGN.md](DESIGN.md)** for the full technical reference — architecture, the text-quote anchoring algorithm, the JSON storage format, the JSINFO-injection mechanism, the permission model, the AJAX API, browser/PHP constraints, and known gaps. 115