xref: /plugin/annotations/README.md (revision 86c3281af18ac3f82557b4466adb5aef413e1639)

# Annotations Plugin for DokuWiki

Word- 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).

![Annotated text with gutter markers and counter bar](images/annotations-screen1.png)
![Open annotation thread with threaded reply](images/annotations-screen2.png)
![Resolved annotation thread](images/annotations-screen3.png)
![Orphaned annotations drawer](images/annotations-screen4.png)
![Admin annotated-pages overview with counts per page](images/annotations-screen5.png)

## Features

- **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.
- **Threaded replies** — any logged-in reader can reply to an annotation, or reply to another reply for a nested discussion.
- **Open / Resolved status** — mark a discussion closed; resolved annotations turn green.
- **Gutter markers** — small icons in the left margin show at a glance where annotations live.
- **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.
- **Per-user toggle** — turn the annotation overlay on or off from your user preferences.
- **No page revisions** — annotations live in a separate file per page; the wiki changelog is never touched.
- **Localised interface** — English, German, Russian and Japanese, falling back to English for any untranslated string.

## Requirements

- DokuWiki Librarian 2025-05-14b (or a compatible release)
- PHP 8.0 or later with the `mbstring` extension
- [usersettings plugin](https://github.com/tracker-user/dokuwiki-usersettings) *(optional — adds the per-user on/off toggle)*

Works in current browsers and as far back as Firefox 78 ESR.

## Installation

1. Copy the `annotations/` directory into `{DokuWiki}/lib/plugins/`.
2. If you want the per-user toggle, install the usersettings plugin too.
3. The defaults work out of the box; tune them in the Configuration Manager if you like (see below).

## Configuration

All settings live under **Admin → Configuration Settings → annotations**:

| Setting | Default | What it does |
|---------|---------|--------------|
| `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. |
| `color_resolved` | `#4ade80` | Highlight colour for resolved annotations. |
| `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. |
| `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. |
| `body_cap` | `10000` | Maximum length (characters) of an annotation or reply body; longer input is truncated. |
| `entries_per_page` | `25` | Rows per page in the **Admin → Annotations** overview of annotated pages. `0` shows every page on a single page. |

## Usage

### Reading annotations

Annotated text is highlighted in **amber** (open) or **green** (resolved). Click any highlight to open the thread panel inline below that paragraph.

The 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.

### Creating an annotation

1. Select any text on the page.
2. Click the **Annotate** button that appears.
3. Type your comment and click **Annotate** to save.

> 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.

The **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.

### Replying

Open 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.

### Resolving / reopening

Click **Resolve** on an annotation to mark its discussion closed, or **Reopen** to undo that. Any logged-in reader can resolve or reopen.

### Editing and deleting

- You can edit or delete your own annotations and replies.
- Admins can edit or delete anyone's.

### Admin: bulk operations

Admins see two extra buttons in the counter bar:

| Button | Effect |
|--------|--------|
| **Clear resolved** | Permanently deletes all resolved annotations on the page |
| **Clear orphaned** | Re-checks the page, then permanently deletes the orphaned annotations |

### Admin: annotated-pages overview

**Admin → Annotations** lists every page that has annotations, with three counts:

- **Normal** — annotations whose quoted text is still on the page.
- **Resolved** — annotations marked done (whatever their anchoring state).
- **Orphaned** — annotations whose text was deleted from the page.

The counts overlap on purpose: each one matches exactly what its clear button removes, so a
resolved annotation is also counted under **Normal** or **Orphaned** depending on whether its
text is still present.

- **Search** by page title or ID, and **sort** by page title or any of the three counts.
- **Clear resolved** on a row removes just that page's resolved annotations; **Clear orphaned**
  removes just that page's orphaned ones.
- **Clear all resolved (N)** and **Clear all orphaned (N)** at the top apply the matching sweep
  across every page at once.

Each clear re-checks the page server-side before deleting, so the counts are authoritative even
if the page changed since it was last viewed. Long lists are paginated (`entries_per_page`).

### Turning the overlay off

In **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.

## License

GPL 2, matching DokuWiki.

---

**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.