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 existing annotation. 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. Admins can bulk-delete orphans. 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 15## Requirements 16 17- DokuWiki Librarian 2025-05-14b (or a compatible release) 18- PHP 8.0 or later with the `mbstring` extension 19- [usersettings plugin](https://github.com/tracker-user/dokuwiki-usersettings) *(optional — adds the per-user on/off toggle)* 20 21Works in current browsers and as far back as Firefox 78 ESR. 22 23## Installation 24 251. Copy the `annotations/` directory into `{DokuWiki}/lib/plugins/`. 262. If you want the per-user toggle, install the usersettings plugin too. 273. No additional configuration is required. 28 29## Usage 30 31### Reading annotations 32 33Annotated text is highlighted in **amber** (open) or **green** (resolved). Click any highlight to open the thread panel inline below that paragraph. 34 35The 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. 36 37### Creating an annotation 38 391. Select any text on the page. 402. Click the **Annotate** button that appears. 413. Type your comment and click **Annotate** to save. 42 43> 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. 44 45### Replying 46 47Open the thread panel for any annotation and use the **Reply** field at the bottom. Any logged-in reader can reply. 48 49### Resolving / reopening 50 51Click **Resolve** on an annotation to mark its discussion closed, or **Reopen** to undo that. Any logged-in reader can resolve or reopen. 52 53### Editing and deleting 54 55- You can edit or delete your own annotations and replies. 56- Admins can edit or delete anyone's. 57 58### Admin: bulk operations 59 60Admins see two extra buttons in the counter bar: 61 62| Button | Effect | 63|--------|--------| 64| **Clear resolved** | Permanently deletes all resolved annotations on the page | 65| **Clear orphaned** | Re-checks the page, then permanently deletes the orphaned annotations | 66 67### Turning the overlay off 68 69In **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. 70 71## License 72 73GPL 2, matching DokuWiki. 74 75--- 76 77**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. 78