How to review Markdown changes in a GitHub pull request

Someone opens a pull request that rewrites half of your architecture document. You click Files changed and get a wall of red and green lines that does not read like the document it is changing. So you skim it, decide the headings look about right, and approve.

There is a better way to do this, and most of it uses features GitHub already has and advertises badly. This is the practical version: what you actually get, the order to use it in, and where it runs out.

The order that works

GitHub gives you more for a Markdown PR than most reviewers ever use. But the features matter less than the sequence, because reviewing a document in diff order is what produces approvals of things nobody read.

1. Read the rendered result first

Before you judge any edit, read the document the way its readers will. Each changed .md file on the Files changed tab carries a rich diff toggle in its header, which renders the Markdown instead of listing raw lines and marks what was added and removed inside the rendered output. Start there, not in the source.

You are not hunting for changes yet. You are answering one question: does this document make sense as it now stands? Skip this step and you will evaluate every edit in isolation without ever asking whether the whole document still holds together.

2. Then walk the source diff for the mechanics

Now toggle back to the source diff, the red-and-green line view GitHub uses for code. First, hide whitespace-only changes, in the diff settings gear or by adding ?w=1 to the URL. Markdown reflows constantly, and a reformatted paragraph or a changed wrap width can otherwise bury three real edits in forty fake ones.

Then go line by line, because a rendered view hides exactly the things that break a document later:

• A heading that changed depth, which silently restructures every table of contents and anchor link built from it.
• A link whose text stayed and whose target moved.
• List nesting that shifted by two spaces and reparented half a list.
• An unclosed code fence, which swallows everything after it.
• Frontmatter edits, which usually render as nothing at all.

None of these look like anything in a rendered view. All of them are obvious in the source.

3. Comment on the line, and suggest the fix

Click a line number to anchor a comment on that exact line, or click one number and drag to the next to cover a range, which prose concerns usually need since sentences rarely respect line breaks. A comment sitting on the sentence that is off beats "the tone in section 4 is off" every time.

For prose, go one step further. A comment can carry a suggestion block that the author applies with a single button. Typos, clumsy wording, stale links: for most problems in a docs PR, the fix is shorter than a description of the fix, so write the fix.

4. Close files out with Viewed

Every file in the diff carries a Viewed checkbox. Ticking it collapses the file and remembers your choice, so the PR shrinks as you work through it. On a PR touching a dozen docs, that is the difference between knowing what is left and guessing.

5. Re-review by commit, not by re-reading

The author pushes fixes. Instead of re-reading the document, open the commits dropdown on the Files changed tab and scope the diff to just the new commits. And check your checkboxes: a push to a file clears its Viewed tick, which is GitHub telling you exactly which files need a second look.

That workflow gets you a long way with nothing but GitHub, and on a normal docs PR it is enough. Use it.

Where it stops working

It stops working on exactly the PRs where careful review matters most: the long ones. Four limits, and they compound.

You get one view at a time. Steps 1 and 2 above are really one activity that the toggle splits in two, and on a long document every switch costs you your scroll position. Losing your place repeatedly is how sections get skipped. Source diff vs. rich diff picks this limit up in full.

The rich diff has no comment anchor. The moment the document becomes readable, the ability to point at a line goes away, along with the line numbers themselves. So you read in one view and comment in the other, matching them up by eye.

Viewed is per file, and a document is not a file. This is the one that really bites. A 1,500-line specification is a single checkbox. GitHub's unit of progress is the file, but the unit of review for a document is the section. Reviewing AI-generated specifications is what that costs you at a thousand lines.

Structured content is where both views fail hardest. A changed table is a run of pipes and dashes in the source, and a changed diagram is a block of arrow syntax. Neither view shows you the thing itself.

None of this is a discipline problem. Asking a reviewer to hold document-wide progress in their head, across two views they have to alternate between, on a document generated in minutes and running to a thousand lines, is asking willpower to do a bookkeeping job.

The same five steps, with the bookkeeping done for you

That is a real review, running inline. Try the panes and the Viewed tick.

The workflow above does not change. What changes is how many of its steps you have to carry yourself:

• Steps 1 and 2 become one pass. The source and the rendered result sit side by side, so there is no toggle and no scroll position to lose. Source diff vs. rich diff is the longer argument for why that pairing is the fix.
• Step 4 moves down to the section level. Viewed stops being one checkbox for a whole document and becomes one per heading, with progress for the file as a whole. Reviewing AI-generated specifications is the longer argument for why the section is the unit that matters.
• Steps 3 and 5 work without leaving the page. You comment without switching back to the source view, and the review can be scoped to any range of the PR's commits.
• Structured content is handled as structure. Table changes diff row by row, and a changed diagram is rendered rather than left as syntax.

Nothing about the PR moves. Approvals, requested changes, and the merge all stay on GitHub, and comments post to the PR as normal. The only thing that changes is where you do the reading.

Go deeper

Specific cases from this walkthrough, in more detail:

• Source diff vs. rich diff is the case for reading and reviewing in one pass, and what changes when removals stay visible.
• Reviewing AI-generated specifications is the workflow when the document was written in minutes and runs to 1,500 lines.

The short version

Read the document first, then the diff, comment on the exact line, and close each file out deliberately. GitHub supports all of it, and for a short docs PR that is the whole answer.

For a long one, the honest answer is that GitHub gives you the pieces and expects you to be the glue. Markdown Review is the human review layer for Markdown-heavy and AI-generated pull requests: the same workflow, with the source and the rendered result together, comments on the exact line, and sections you can mark viewed so "reviewed" means somebody read it. And when you want the jump to be one click, Markdown Review for GitHub adds a link to every Markdown file header on the PR.