Version diff

A version diff shows what changed between two versions of a page, section by section. Every change is added, removed, changed, or moved, and carries a visible text label beside its own icon shape, so colour is never the only signal. A moved change also shows its old and new position.

An explicit comparison is never silently hidden. Its state is exposed as data-diff-state: changes when every evidence entry was readable and at least one change came out, incomplete when usable changes came out but other entries were dropped as malformed, unchanged when two versions were compared and the change list was explicitly empty, and unavailable when a version is missing or equal or the change evidence could not be read at all. A changes or incomplete viewer carries machine-readable data-changes-usable and data-changes-dropped counts, and an incomplete one adds a visible "Partial" note saying some recorded evidence could not be read — the valid changes and their navigation stay usable, but a partially unreadable comparison is never called complete or unchanged. An unchanged comparison still names both versions and shows a zero-change count. Only a page with no comparison written at all renders nothing.

Syntax

Pass the diff as JSON in the directive's changes attribute, with the two versions in from and to:

Changes from v1 to v2

Base version v1 Target version v2

1. Retries

   Added

2. Legacy flags

   Removed

3. Install

   Changed

4. Upgrade

   Moved

   From position 3To position 5

The same data also works in a page's versionDiff front matter, or as the engine's diff/<version>/<page>.json shape, where the four kinds are four lists.

An explicit empty change list compares the two versions and reports that they are unchanged:

Changes from 0.3 to 0.4

Base version 0.3 Target version 0.4

Change 0 of 0

If the comparison was requested but none of its evidence can be read, the viewer says it is unavailable instead of looking like a verified empty diff. When some entries are readable and others are malformed, the readable changes still render and the viewer marks the comparison incomplete:

Changes from v1 to v2

Base version v1 Target version v2

Partial This version comparison is incomplete: 2 usable changes are shown; 2 unreadable entries were dropped from the recorded diff.

1. Retries

   Added

2. Install

   Changed

   Removed: − Before

   old

   Added: + After

   new

The note above the list says the evidence is only partial, data-diff-state is incomplete, and data-changes-usable="2" with data-changes-dropped="2" report exactly what was read and what was not. The same counts apply to the engine's grouped shape, where malformed entries inside the four kind lists are counted as dropped.

Options

Name	Type	Default	What it does
from	string	none	The version the page is compared from.
to	string	none	The version the page is compared to.
changes	JSON array	none	The sections that changed, each with kind, title, and optional from, to, before, and after.
data	JSON object	none	The whole diff, as an alternative to the three attributes above.

Example

Changes from 0.2 to 0.3

Base version 0.2 Target version 0.3

1. Version diff

   Added

   Added: + After

   ## Version diff A section-by-section comparison.

2. Install

   Changed

   Removed: − Before

   npm install mizzen

   Added: + After

   npm install @velella/mizzen

3. Legacy blocks

   Removed

4. Upgrade

   Moved

   From position 2To position 4

The Previous and Next buttons and the change count start hidden; the island reveals them and makes one change a single tab stop, with arrow keys moving between changes in reading order. In an incomplete viewer the count, the anchors, and the keyboard navigation cover only the readable changes — nothing is invented for the dropped evidence. Without JavaScript the whole diff still reads in order.