Version diff
1 minute read
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. The
viewer renders nothing when there are no changes or the two versions are equal.
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
Change 1 of 4
Retries
Added
Legacy flags
Removed
Install
Changed
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.
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
Change 1 of 4
Version diff
Added
After## Version diff A section-by-section comparison.
Install
Changed
Beforenpm install slipway
Afternpm install @velella/mizzen
Legacy blocks
Removed
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. Without JavaScript the whole diff still reads in order.