mddiff — high-fidelity rendered Markdown diff
Boost Markdown review productivity in the AI age.
Demo
👉 View the live rendered diff
Why mddiff
Coding agents now generate and modify more Markdown: plans, specs, skills, rules, READMEs, changelogs, and implementation notes.
That makes human review more important, not less. Reviewers need a clear view of what changed, without spending their time and attention decoding Markdown syntax noise or chasing unstable rendered previews.
mddiff boosts Markdown review productivity through clearer diffs, broader Markdown coverage, workflow-native access, and Git-aware comparison support.
Highlights
- Clear, human-friendly review — review the rendered document change instead of decoding Markdown syntax or noisy word diffs.
- High-fidelity Markdown coverage — keeps complex changes clear across inline edits, links, paragraphs, lists, tables, code blocks, rewritten sections, and larger structural changes. 👉 See here
- File comparison and Git awareness — compare selected Markdown files directly and Git-backed changes across working tree edits, staged changes, unstaged changes, revisions, and commit pairs.
- Two review modes — inline diff for document-flow review, and row-aligned side-by-side diff for structured comparison.
- Natural VS Code entry points — open rendered diffs from Source Control, the editor title bar, or Explorer context menus without leaving your review flow.
- Auto-refresh on save — rendered diffs update during edit-review loops when working-tree content changes.
- CLI + VS Code — use the same rendered diff from the editor, terminal, scripts, or coding-agent workflows.
Use it
mddiff does not require users to remember one special command.
Three ways in, each rendering the comparison you chose — never a silent substitute:
- Source Control — the mddiff glyph on a changed file row (or its right-click menu): under Changes it diffs staged ↔ working tree, under Staged Changes it diffs HEAD ↔ staged.
- Editor title bar — in a diff editor the mddiff button mirrors that comparison and replaces it (a back button returns); on a plain markdown editor it opens working tree ↔ HEAD.
- Explorer context menu — right-click a markdown file and choose Rendered Diff…: select two files to compare them against each other, or one file to pick the Git comparison you want.
In the shot: ① the Source Control glyph, ② the editor title-bar button — both open a rendered diff.
In the shot: ③ the Explorer right-click menu — choose Rendered Diff… on a markdown file.
Install
Open Extensions in VS Code, search mddiff, and click Install — or run:
code --install-extension awesomele.mddiff
The same diff engine also ships as a Homebrew CLI (macOS) that opens the diff in your browser:
brew install awesomele/tap/mddiff
Troubleshooting
Not seeing the entry points after installing? Reload the window — open the Command Palette (Cmd/Ctrl+Shift+P) and run Developer: Reload Window. A window that was already open keeps the previous extension state until it is reloaded.
