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. 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- **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. No additional configuration is required. 29 30## Usage 31 32### Reading annotations 33 34Annotated text is highlighted in **amber** (open) or **green** (resolved). Click any highlight to open the thread panel inline below that paragraph. 35 36The 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. 37 38### Creating an annotation 39 401. Select any text on the page. 412. Click the **Annotate** button that appears. 423. Type your comment and click **Annotate** to save. 43 44> 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. 45 46### Replying 47 48Open 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. 49 50### Resolving / reopening 51 52Click **Resolve** on an annotation to mark its discussion closed, or **Reopen** to undo that. Any logged-in reader can resolve or reopen. 53 54### Editing and deleting 55 56- You can edit or delete your own annotations and replies. 57- Admins can edit or delete anyone's. 58 59### Admin: bulk operations 60 61Admins see two extra buttons in the counter bar: 62 63| Button | Effect | 64|--------|--------| 65| **Clear resolved** | Permanently deletes all resolved annotations on the page | 66| **Clear orphaned** | Re-checks the page, then permanently deletes the orphaned annotations | 67 68### Turning the overlay off 69 70In **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. 71 72## License 73 74GPL 2, matching DokuWiki. 75 76--- 77 78**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. 79