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

  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.

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

  1. Version diff

    Added

    After

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

  2. Install

    Changed

    Before

    npm install slipway

    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. Without JavaScript the whole diff still reads in order.

View Markdown

Use with an agent
View Markdown

Open in