Compare documents

Compare two documents in real time and show the diff in the editor.

For a step-by-step guide on comparing documents, see the Compare documents guide.

API Reference

startComparingDocuments

Starts real-time comparison with another document. Differences are displayed as suggestions in an inline diff view where the old and the new content are displayed in the editor.

Parameters (StartComparingDocumentsOptions)

• otherDoc? (Node): The document to compare against. It is a ProseMirror Node object. Defaults to a snapshot of the current document if omitted
• displayOptions? (DisplayOptions<{ suggestion: Suggestion }>): Controls how differences are rendered as suggestions
  • showAsDiff? (boolean): Show alternative content as a diff widget. Default: true in comparison flows
  • diffPosition? ('before' | 'after'): Where to display the diff relative to the suggestion. Default: 'before'
  • attributes? (Record<string, any>): Attributes added to rendered elements
  • renderDecorations? (RenderDecorations<{ suggestion: Suggestion }>): Custom rendering function
• debounceTimeout? (number): Milliseconds to wait before recomputing diffs. A low value will make the app seem more responsive, but it might cause performance issues in large documents. Default: 500
• diffUtilityConfig? (DiffUtilityConfig): Options for comparing the documents with the diff utility
  • simplifyChanges? (boolean): Whether to simplify the changes. If true, the changes will be simplified so that, for example, two changes in the same word are merged into a single change. Only applies when mode is 'detailed'. Default: true
  • ignoreAttributes? (string[]): The attributes to ignore. Default: ['id', 'data-thread-id']
  • ignoreMarks? (string[]): The marks to ignore. Default: ['inlineThread']
  • changeMergeDistance? (number | null): Maximum distance (in document positions) between changes to merge them. If two adjacent changes have a distance less than or equal to this value in either rangeA or rangeB, they will be merged into a single change. Set to null or undefined to disable merging. Only applies when mode is 'detailed'. Default: null
  • mode? ('detailed' | 'block'): The diff mode to use for comparison. 'detailed' performs character-level diff that identifies precise changes within text (default). 'block' performs block-level diff that treats each top-level node as a single unit. Block mode is useful when you only need to know which paragraphs, headings, or other block-level elements have changed, without character-level detail. In block mode, simplifyChanges and changeMergeDistance options are ignored. Default: 'detailed'

Returns

void

Example

// Start comparing changes with another document
toolkit.startComparingDocuments({
  otherDoc,
})

stopComparingDocuments

Stops the real-time comparison and clears all suggestions, so the diff view is no longer visible.

Returns

void

Example

// Stop comparison and clear decorations
toolkit.stopComparingDocuments()

Accepting and rejecting changes

When comparing documents, changes are displayed as suggestions. To accept or reject individual changes or all changes at once, use the suggestion methods:

• acceptSuggestion: Accept a specific change
• rejectSuggestion: Reject a specific change
• acceptAllSuggestions: Accept all changes
• rejectAllSuggestions: Reject all changes

These methods work with both regular suggestions and changes from the Compare Documents feature.

Example

// Start comparing documents
toolkit.startComparingDocuments({
  otherDoc: otherDoc,
})

// Get all changes (as suggestions)
const suggestions = toolkit.getSuggestions()

// Accept the first change and get feedback
if (suggestions.length > 0) {
  const result = toolkit.acceptSuggestion(suggestions[0].id)
  console.log(result.aiFeedback.events)
}

// Or reject all changes at once
const result = toolkit.rejectAllSuggestions()
console.log(result.aiFeedback.events)
toolkit.stopComparingDocuments()