Source diff vs. rich diff: why reviewing Markdown in a GitHub PR is harder than it should be

Open a pull request that changes a Markdown file and GitHub gives you a small toggle: view the source diff or the rich diff. Most people click it once, decide it does not help much, and go back to skimming. The toggle is not the problem. The problem is that each view answers a different question, and reviewing a document properly needs both answered at the same time.

This is the single most common friction in reviewing Markdown changes on GitHub, and it is worth being precise about why.

What the source diff is good at, and where it fails

The source diff is the familiar red-and-green line view. It is the same machinery GitHub uses for code, pointed at a .md file. Its strengths are real:

• Every changed line is accounted for. Nothing is hidden.
• You can comment on an exact line, which is where review actually happens.
• You can see structural edits: a heading level that changed, a list that was reordered, a link whose target moved.

Where it fails is reading. Markdown is a source format for prose, and prose does not survive being chopped into diff lines. A reworded paragraph shows up as one long deleted line and one long added line, and you are left mentally diffing two walls of text. You can review the change token by token, but you cannot see what the reader of the document will actually get.

What the rich diff is good at, and where it fails

GitHub's rich diff renders the Markdown and marks up what was added or removed inside the rendered output. Now the prose reads like prose. Headings look like headings. A reworded sentence reads as a sentence, not as two diff lines.

The catch is that rendering and reviewing pull against each other:

• You usually cannot comment on a specific line from the rich view. The precise anchor that makes review actionable is gone.
• Complex changes render poorly. Moved content, restructured tables, and edited diagrams are exactly the cases where the rendered markup is hardest to trust, and they are also the cases that most need careful review.
• It is a single rendered result. You see the destination, but the rich diff is weakest at showing you the path, which is the whole point of a diff.

So the rich diff makes the document readable and the source diff makes it reviewable, and GitHub asks you to pick one per glance. For a three-line typo fix, that is fine. For a 1,500-line specification, switching back and forth between two views, losing your place each time, is how whole sections get approved without being read.

The false choice

Here is the part worth saying plainly, because it is easy to miss: readable or reviewable is a false choice. It is an artifact of a UI that shows you one view at a time, not a law of nature.

What you actually want while reviewing a document is to look at the rendered result the reader will get, see inside that rendered result what changed, and still be able to drop a comment on the exact line that is wrong. Those are not competing goals. They only compete when the tool makes you toggle.

Once you name it that way, the fix is obvious. Stop toggling. Put the source and the rendered result side by side, keep the change markers inside the rendered view so you never lose track of what moved, and keep the line-level comment anchor live the whole time.

What "both at once" looks like in practice

A review built around this idea behaves differently from the GitHub toggle in a few concrete ways.

The diff and the rendered document sit together, not one-or-the-other. You read the change as prose and confirm the mechanics in the source without leaving the page or losing your scroll position.

Change markers live inside the rendered view. You are looking at the document the way a reader will, and the parts that changed are marked right there. Removed content is shown in place rather than silently vanishing, so a deletion at the edge of a section does not slip past you.

Long documents are broken into sections you can track. A big PR becomes a set of headings you can collapse, mark viewed, and come back to. That part is its own subject, taken up in Reviewing AI-generated specifications.

None of this replaces GitHub. The PR, the approvals, and the merge stay where they are. It replaces the one thing GitHub does badly, which is letting you read and review a document at the same time.

When the trade-off actually bites

If your PRs are mostly code with the occasional README tweak, the source-versus-rich toggle is a minor annoyance and you can stop reading here.

It becomes a real workflow problem when Markdown is a first-class artifact in your repository: specifications, design docs, ADRs, PRDs, runbooks, and AGENTS or CLAUDE instruction files. These are long, they are edited often, and increasingly they are generated by AI in minutes and then run to hundreds or thousands of lines. Reviewing them through a toggle that shows you readable-or-reviewable, one glance at a time, is how they get skimmed instead of read.

That is the gap Markdown Review is built to close: review a Markdown PR section by section, see the source and the rendered result together, comment on the exact line, and mark sections viewed so you can pick up where you left off. It is the human review layer for Markdown-heavy and AI-generated pull requests, sitting on top of the GitHub PR you already have.

You do not have to choose between readable and reviewable. That choice was never real.