Diffing extension

Compare two ProseMirror documents and replay differences as tracked changes

Compare two documents and replay the differences as tracked changes. The Diffing extension is included in the starter extensions by default.

For usage guides, see Document comparison.

Commands

compareDocuments

Compares the current document against an updated document and returns the differences. Does not modify the document.

Usage

const diff = editor.commands.compareDocuments(
  updatedDocument,       // ProseMirror Node
  updatedComments,       // CommentInput[] (optional)
  updatedStyles,         // StylesDocumentProperties (optional)
  updatedNumbering,      // NumberingProperties (optional)
);

Parameters:

updatedDocument · Node · required

The ProseMirror document to compare against. Typically from a headless Editor instance.

updatedComments · CommentInput[]

Comments from the updated document. Defaults to the current document’s comments if omitted.

updatedStyles · StylesDocumentProperties | null

OOXML styles from the updated document. Defaults to current styles if omitted.

updatedNumbering · NumberingProperties | null

OOXML numbering from the updated document. Defaults to current numbering if omitted.

Returns: A DiffResult object containing the computed differences.

replayDifferences

Applies a DiffResult onto the current document. By default, changes are wrapped in tracked-change marks.

Usage

editor.commands.replayDifferences(diff, { applyTrackedChanges: true });

Parameters:

diff · DiffResult · required

The diff result from compareDocuments.

options.applyTrackedChanges · boolean · default: "true"

When true, changes are tagged as tracked changes with author attribution. When false, changes are applied silently. Requires a user on the editor instance.

DiffResult

The object returned by compareDocuments:

Field	Type	Description
docDiffs	NodeDiff[]	Block and inline structural differences
commentDiffs	CommentDiff[]	Added, deleted, and modified comments
stylesDiff	StylesDiff | null	OOXML style changes
numberingDiff	NumberingDiff | null	OOXML numbering changes

Each NodeDiff has an action of 'added', 'deleted', or 'modified', with serialized node data and position anchors.

Source code