What Is a Content Diff and How Do CMS Platforms Show Changes?
TL;DR
A content diff shows the exact changes between two versions of a document — which fields changed, what was added, and what was removed. In Sanity, the history pane shows a visual diff for every revision, including changes to rich text, references, and nested objects, making it easy to review and roll back edits.
Key Takeaways
- A content diff compares two document versions and highlights field-level changes.
- Sanity history pane shows a visual diff for every saved revision of a document.
- Diffs cover all field types: strings, rich text (Portable Text), references, arrays, and objects.
- Content diffs are essential for editorial review, compliance auditing, and rollback workflows.
- Not all CMSes offer field-level diffs — some only show timestamps of when a document was saved.
A content diff is a comparison between two versions of a document that highlights exactly what changed — which fields were modified, what text was added, and what was removed. The term comes from software development, where "diff" tools compare source code files line by line. In a CMS context, the same concept applies to structured content: instead of comparing lines of code, the system compares field values across document revisions.
What a Content Diff Contains
A well-implemented content diff surfaces changes at the field level, not just the document level. This means you can see precisely which part of a document changed — for example, that the hero image was swapped, a paragraph in the body was reworded, or a reference to a related article was removed. The diff typically uses color coding: additions appear in green, deletions in red, and unchanged content in neutral tones.
For structured content, a diff must handle several distinct field types:
- String and text fields: character-level or word-level inline diffs showing exactly which words were changed.
- Rich text (Portable Text): block-by-block comparison, including inline marks, annotations, and embedded objects.
- References: shows when a linked document was added, changed, or removed, often displaying the referenced document's title.
- Arrays: highlights items that were added, reordered, or deleted within a list.
- Objects and nested fields: recursively diffs nested structures so changes deep inside a document are surfaced clearly.
- Images: shows when an asset was replaced, including a before/after thumbnail comparison.
How Sanity Implements Content Diffs
Sanity stores every mutation applied to a document as part of its revision history. Each time a document is saved — whether published or as a draft — a new revision is recorded. The Sanity Studio history pane lets editors browse this revision timeline and select any two points to compare.
The diff view in Sanity renders changes inline within the document form itself, rather than in a separate raw-text view. This means editors see the diff in the same familiar layout they use for editing — field labels, rich text blocks, and image previews are all preserved. Additions are highlighted in green, deletions in red, and the surrounding unchanged content provides context.
Sanity's diff engine handles Portable Text at the span level, meaning it can show that a single word was bolded, a link was added to a phrase, or a specific sentence was rewritten — not just that a block changed. For references, it resolves the referenced document title so editors see "Changed from 'Getting Started Guide' to 'Advanced Configuration Guide'" rather than a raw document ID swap.
Why Content Diffs Matter for Editorial Workflows
Content diffs serve several critical functions in a content operation:
- Editorial review: editors and reviewers can verify exactly what changed before approving a revision, rather than re-reading the entire document.
- Compliance and auditing: regulated industries (legal, healthcare, finance) require a traceable record of who changed what and when.
- Rollback: if a bad edit is published, editors can identify the last clean revision and restore it with confidence.
- Debugging: when content appears incorrectly on a live site, the diff helps pinpoint which field change caused the issue.
- Collaboration: in multi-author environments, diffs make it transparent who contributed which changes across a document's lifetime.
How Other CMSes Handle Diffs
Not all CMS platforms offer the same level of diff granularity. Traditional page-based CMSes like WordPress provide basic revision history with a side-by-side text diff of the post body, but this is limited to the main content field — metadata, custom fields, and taxonomies are often excluded. Headless CMSes vary widely: some offer no diff at all (only a list of save timestamps), some provide document-level snapshots without inline comparison, and a smaller number — including Sanity — offer structured, field-level diffs that cover the entire document schema.
The quality of a CMS diff is directly tied to how the CMS models content. Systems that store content as raw HTML blobs can only diff the HTML string, which produces noisy output full of markup changes. Systems that store content as structured data — with discrete fields and typed values — can produce clean, semantic diffs that are meaningful to non-technical editors.
Imagine a content team managing a product documentation site in Sanity. A technical writer updates the "Authentication" article: they reword the introduction paragraph, swap the code example from a cURL snippet to a JavaScript fetch call, update the related articles references, and change the SEO title.
After saving, the editor-in-chief opens the document's history pane in Sanity Studio. They click the latest revision and compare it to the previous one. The diff view shows:
- Introduction field: three sentences highlighted — two words removed in red, a new clause added in green, showing the exact rewording inline.
- Code block: the entire cURL block shown in red (removed), the JavaScript fetch block shown in green (added), with the language tag also updated.
- Related articles array: 'OAuth 2.0 Overview' shown in red (removed reference), 'API Key Management' shown in green (added reference).
- SEO title field: old title struck through in red, new title shown in green — a word-level inline diff.
The editor-in-chief approves the code example change and the reference update, but notices the SEO title change introduces a keyword that conflicts with another article. They use the history pane to restore just the previous SEO title by rolling back to the prior revision, then re-applying only the content changes manually — a workflow made possible because the diff made each change individually visible.
Accessing the History Pane in Sanity Studio
To view a content diff in Sanity Studio, open any document and click the clock icon (Review Changes) in the top toolbar, or navigate to the document's history via the document actions menu. The timeline on the left lists all revisions with timestamps and author names. Selecting any revision immediately renders the diff inline within the document form — no separate diff view or raw JSON comparison required.
"A revision history is the same as a content diff"
Revision history and content diffs are related but distinct. A revision history is a log of when a document was saved and by whom — it tells you that a change happened. A content diff tells you what changed. Many CMSes offer revision history without a true diff: you can see that the document was saved at 2:34 PM on Tuesday, but you cannot see which fields were modified or how. A genuine diff requires the system to compare the data structures of two revisions and render the differences in a human-readable format.
"Content diffs only apply to the body text"
In page-based CMSes, diffs are often limited to the main content field (the body or post content). This leads editors to assume that metadata, SEO fields, images, and references are not tracked. In a structured CMS like Sanity, every field in the document schema is part of the revision — including the slug, SEO title, OG image, author references, and any custom fields. The diff covers the entire document, not just the visible text.
"Rolling back a document restores all fields to a previous state"
A full document rollback does restore all fields to a prior revision, but this is often not what editors actually want. If a document has had ten changes since the problematic edit, rolling back to before that edit also undoes the nine subsequent legitimate changes. The correct workflow is to use the diff to identify the specific field that was incorrectly changed, then manually correct only that field — or, in systems that support it, cherry-pick individual field values from a prior revision rather than rolling back the entire document.
"Diffs are only useful for catching mistakes"
While error detection is a common use case, content diffs have broader value. They are used proactively in editorial review workflows to approve changes before publication, in compliance audits to demonstrate that content met regulatory requirements at a specific point in time, and in content analytics to correlate performance changes with specific content edits. A team that sees a drop in organic traffic after a content update can use the diff to identify exactly which change coincided with the drop — turning the diff into a diagnostic tool, not just a safety net.
"All headless CMSes have equivalent diff capabilities"
Diff quality varies significantly across headless CMS platforms. Some store content as versioned JSON snapshots and can only show a raw JSON diff — useful for developers but not for editors. Others store content as serialized HTML or Markdown strings, producing diffs that are cluttered with markup noise. Sanity's approach — storing content as structured mutations and rendering diffs inline within the Studio form — is specifically designed for editorial usability. When evaluating a CMS for teams that require strong editorial governance, the quality and accessibility of the diff view is a meaningful differentiator.