How to diff markdown outside of git
- Step 1Switch to Upload file mode — A two-file diff needs the Upload file tab. Paste text has only one box (File A); File B is supplied as an upload. Switch to Upload first.
- Step 2Load the repo version as File A — File A is the base — the file currently in your repo (
git show HEAD:docs/README.md > README-base.md, or just the copy on your branch). Lines only in this version show as-(removed). Accepts.md,.mdx,.markdown,.txt. - Step 3Load the proposed file as File B — File B is the incoming change — the version from Slack/email. New lines show as
+(added). Putting the base in A and the proposal in B makes the diff read like a normal PR (added = what they want to land). - Step 4Run the diff — Click run. The unified diff is computed locally. There are no options — md-diff is a fixed line-by-line diff with 4 lines of context; there is no whitespace-ignore or rename-detection mode like full Git has.
- Step 5Review the hunks — Read each
@@block:-lines would be removed from the repo file,+lines would be added. Treat it exactly as you'd treat a PR diff — check each hunk against the change description. - Step 6Paste into the PR or save the patch — Copy the diff into your review comment so the discussion has the exact delta, or download
diff.patch. If the contributor can't open a PR, apply the patch yourself withgit apply diff.patchafter verifying it.
md-diff vs. full git diff for PR review
md-diff gives you the unified-diff review surface, but it is a single text-level diff — not the full Git toolchain. Know the boundaries before relying on it.
| Capability | md-diff | Notes |
|---|---|---|
Unified diff output (+/-/@@) | Yes | Same format as git diff; pastes into PR comments |
| Lines of context | 4 (fixed) | No -U style control; engine default |
Apply with git apply / patch | Yes | If both sides are real files |
| Ignore-whitespace mode | No | Whitespace is significant; no -w equivalent |
| Rename / move detection | No | Compares two given files only; no -M |
Word-level (--word-diff) | No | Line granularity only |
| Multi-file / directory diff | No | Exactly two files (File A, File B) |
Unified-diff markers in the output
The patch md-diff emits follows the standard unified-diff layout.
| Marker | Meaning |
|---|---|
--- <name> File A | The base side (your repo version) |
+++ <name> File B | The proposed side (the incoming change) |
@@ -a,b +c,d @@ | Hunk header: lines a..a+b in A, c..c+d in B |
(space) | Context line, unchanged in both |
- | Line removed from the repo version |
+ | Line added by the proposed change |
Cookbook
Real Markdown PR-review scenarios and the unified diff md-diff produces. Output trimmed to the relevant hunk.
A README line edited in a Slack-shared draft
A teammate sent an updated README in Slack. The diff shows the one-line change you'd review in a PR.
File A (repo README.md): ## Installation Run `npm install` to get started. File B (Slack draft): ## Installation Run `pnpm install` to get started. Diff (hunk): @@ -1,2 +1,2 @@ ## Installation -Run `npm install` to get started. +Run `pnpm install` to get started.
A changelog entry added
A PM emailed a CHANGELOG with a new release note. The diff shows it as a clean addition.
File A (CHANGELOG.md): ## [1.4.0] - Added export to PDF File B (proposed): ## [1.5.0] - Added dark mode ## [1.4.0] - Added export to PDF Diff (hunk): @@ -1,2 +1,4 @@ +## [1.5.0] +- Added dark mode ## [1.4.0] - Added export to PDF
A fenced code block changed
The diff compares the raw fenced block line by line, so an edited command inside it shows precisely.
File A: ``` docker run app:1.0 ``` File B: ``` docker run app:2.0 ``` Diff (hunk): @@ -1,3 +1,3 @@ ``` -docker run app:1.0 +docker run app:2.0 ```
Reconstruct the base from Git, then diff the attachment
When the proposal is an email attachment, pull the repo version to a file first, then diff the two.
Steps: git show HEAD:docs/setup.md > setup-base.md # File A # save the email attachment as setup-new.md # File B Load setup-base.md (A) and setup-new.md (B), run. The resulting diff is the PR you never received. Apply it later with: git apply diff.patch
Whitespace-only change flagged
A contributor's editor re-indented a list. There's no ignore-whitespace mode, so the diff surfaces it — which is useful for catching unintended reformatting in a PR.
File A: - item one - item two File B (re-indented with two leading spaces): - item one - item two Diff (hunk): @@ -1,2 +1,2 @@ -- item one -- item two + - item one + - item two
Edge cases and what actually happens
No whitespace-ignore option
By designUnlike git diff -w, md-diff treats whitespace as significant and has no ignore mode. Re-indentation, trailing spaces, and tab-vs-space changes all show as diffs. For PR review this is often desirable — it surfaces accidental reformatting — but expect noise if a draft was run through a formatter.
Base and proposal swapped
Inverted resultPutting the proposed file in File A and the repo version in File B inverts the diff: the change's additions show as -. File A is always the base. Reload with repo version = A, proposal = B.
Only one file loaded
ExpectedIf File B is empty, md-diff diffs File A against an empty file — the entire file shows as removed. An all-- result means the proposed file wasn't loaded.
No rename / move detection
Not supportedmd-diff compares exactly the two files you provide. It has no -M rename detection and no directory diff. If a doc was renamed and edited, load the old path as A and the new path's content as B to review the content delta.
Identical files after a round-trip
ExpectedIf the 'change' turns out to match the repo byte-for-byte, the patch has a header but no hunks. An empty diff body means there is nothing to review — the proposal is already in the repo.
Line-ending differences between OSes
ReportedA file saved with different line endings can register changes because line content is captured as-is. If a Windows-saved attachment diffs noisily against a repo file, normalise line endings first (or note that the diff reflects an EOL change, not a content change).
File over the plan limit
RejectedEach side is checked against your plan's character limit (Free: 500,000). An oversized file throws an error naming the file and its character count; the other side is unaffected.
Expecting word-level diff like a code-review UI
Line granularity onlySome PR tools highlight changed words inline. md-diff is line-level: a one-word edit shows as a full old-line/new-line pair. There is no --word-diff equivalent.
Frequently asked questions
Is the output the same format as git diff?
Yes — it's a standard unified diff with --- File A / +++ File B headers, @@ ... @@ hunk markers, and +/-/context lines. You can paste it into a PR comment or apply it with git apply if both sides are real files.
Can I review a Markdown change that was never pushed to a branch?
That's the main use case. Save the repo version as File A and the Slack/email version as File B, run the diff, and you get the same review surface a PR would give you — without a branch.
How do I get the repo version out as a file for File A?
git show HEAD:path/to/file.md > base.md writes the committed version to a file you can upload as File A. Then save the proposed change as File B and run the diff.
Does it ignore whitespace like git diff -w?
No. Whitespace is significant and there is no ignore option. Re-indentation and trailing spaces show as changes — useful for catching unintended reformatting, but it means a formatter-run draft will produce extra hunks.
Does it detect renames or moved files?
No. md-diff compares exactly two files you provide; there's no rename detection or directory diff. For a renamed-and-edited doc, diff the old content (A) against the new content (B) to see the change.
Can I apply the diff to my repo?
Yes, if both sides are real files. Download diff.patch and run git apply diff.patch (or patch -p0 < diff.patch). Verify the hunks first, as with any patch from outside the repo.
How many lines of context are shown?
Four, the engine default. There's no equivalent of git diff -U10 to widen it — md-diff has no options panel.
Are the files uploaded to a server?
No. The diff runs in your browser, so internal READMEs, unreleased changelogs, and private runbooks stay on your machine.
Why are the additions showing as removals?
You probably loaded the proposed file as File A and the repo version as File B. File A is always the base, so swap them: repo = A, proposal = B.
Can I diff more than two files at once?
No. md-diff is strictly two inputs (File A, File B). To combine several Markdown files before reviewing, use md-merger; to break a large doc into reviewable pieces, use md-splitter.
What's the size limit per file?
Free 1 MB / 500,000 characters, Pro 10 MB / 5,000,000, Pro-media 50 MB / 20,000,000, Developer 500 MB / unlimited. Each file is checked independently.
How do I cut diff noise from formatting before review?
Run both files through md-prettifier so spacing and bullet style match, then diff — the result shows only substantive changes. md-lint can also flag style issues in the proposal before you review it.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.