Review Markdown changes in a pull request

Agents often open pull requests that touch Markdown: a plan, a changelog, a handoff note, a README. The diff looks like code, but the reader of the file sees a rendered page. A review that only reads one of those two views can miss problems the other view would catch.

This covers both views, review notes and a checklist for agent-written files. If you'd rather check the commits on your own machine first, start with checking an agent's commits locally.

Two views of the same change

The line diff shows the raw text: each removed line, each added line, and some unchanged lines around them. Nothing is hidden. Front matter, link targets, trailing spaces and blank lines all show up as characters.

A rendered view shows the change as a reader would see it. Some git hosts offer source and rendered views for prose files like Markdown in commits and pull requests. In that rendered diff, added and removed text is highlighted on the formatted page, so **bold** in the source shows as bold.

Each view catches different mistakes:

• The line diff catches edits a reader can't see: a changed link URL, a front matter value, a trailing space removed, a list marker swapped from * to -.
• The rendered view catches edits that only look wrong once formatted: a heading that turned into a plain paragraph, a table that fell apart, a list that merged into the text above it.

Some hosts add a tooltip in the rendered diff when a link's URL changes, because that kind of change is invisible on the page. Don't count on it. Read link targets in the line diff.

Review an agent's Markdown pull request, step by step

Labels and menus differ from host to host, so check your host's docs for the exact names.

1. Read the description first. Find out what the agent was asked to do. If a pull request meant to fix one section touches 40 files, that is already a finding.
2. Open the changed files list. Some hosts let you filter the list or jump through a file tree. Start with the .md files.
3. Turn on hide whitespace, then turn it off. Many hosts have an option to hide whitespace changes. If a file's diff shrinks to a few lines with it on, the rest was reformat churn. Turn it back off before you approve, for the reason in the checklist below.
4. Read each file in the line diff. Go top to bottom. Check front matter, headings, links and code fences as raw text.
5. Switch to the rendered view, where your host offers one. Scan the page as a reader. Look for anything that renders differently from what the agent meant. Some hosts can't build a rendered view for very large or complex changes; when that happens, the line diff still works.
6. Leave notes on lines. Some hosts only accept line comments in the source view, so switch back to the line diff to write them. On many hosts you can click and drag to comment on several lines at once.
7. Mark each file as viewed. Many hosts let you mark a file as viewed so it collapses. If the agent pushes a new change to that file, it comes back for another look.
8. Submit one review. Many hosts let you hold comments as pending, visible only to you, until you submit them together. You then leave a general comment, approve, or ask for changes.

For the same checks on the command line, with word diffs and stats, read diffing Markdown with git.

Write notes that point at one fix

When the author is an agent, or a person who will paste your notes into an agent, write notes that point at one thing and say what done looks like.

• Quote the line. "Line 12 changes the deadline from June to July. Was that asked for?" beats "check dates".
• Name the rule. "Keep front matter keys in the existing order" gives the agent something to follow on the next run.
• Suggest the exact fix. Many hosts let you insert a suggestion block from the comment box. You edit the text inside it, and the author can apply it as a commit. On some hosts, the author can batch many suggestions into one commit.
• Batch your comments. Some hosts send a notification for each single comment. A pending review that goes out once keeps the noise down, and it gives an agent the full list in one pass.

When the agent pushes a fix, resolve the threads it addressed so the open ones stand out. Many hosts support resolving a thread.

A checklist for agent-written Markdown

Run these against every .md file in the pull request.

Front matter

• Values changed on purpose? Read every key and value in the line diff. A changed status or date is easy to miss.
• Delimiters intact? Front matter has no rule in the CommonMark spec. Under plain CommonMark, a --- line that opens a file is a thematic break, and a text line with --- right under it is read as a second-level heading. So in a viewer without front matter support, a simple run of key: value lines may show as a rule and a heading. Other YAML, such as a list, parses differently. Some hosts instead show front matter as-is, in a box above the rendered content. If the rendered view looks odd here, check that both --- lines survived. Our post on broken YAML headers covers the usual causes.

Headings

• Space after the hash? CommonMark needs a space or a tab between the opening # characters and the heading text. #Setup is a paragraph, not a heading. The spec notes that many implementations don't require the space, so it may look fine in one viewer and break in another.
• Heading text changed? Many viewers build anchor links from heading text, so a rename may break links from other files. See the post on heading anchors.
• Stray --- under a line? A --- right under a paragraph line, with no blank line between, makes that paragraph a heading.

Links

• Targets still right? Read each changed URL and file path in the line diff. On the page you only see the link text, not where it goes.
• Reference definitions kept? A reference link like [plan][1] needs a matching [1]: ... definition somewhere in the document. If the agent deleted the definition, the brackets no longer form a link.

Whitespace-only churn

• Trailing spaces stripped? In CommonMark, a paragraph line ending in two or more spaces produces a hard line break, unless that line ends the paragraph. Inside code spans, code blocks and HTML tags, trailing spaces make no break. Trimming them can join lines that were meant to stay apart. A line that ends in a backslash also breaks there, and trimming spaces leaves that backslash alone.
• Whole file rewritten? If the diff shrinks to a few lines with whitespace hidden, have the agent revert the reformat and resend only the real edits. Our post on smaller agent diffs has rules you can paste into its instructions.
• Blank lines moved? Check that no blank line was dropped between a paragraph and a --- line. Without it, the paragraph turns into a heading.

To track edits to one file outside a pull request, with or without git, read tracking changes to one Markdown file.

Where Sashmark fits

The desktop app Sashmark is meant to read and edit Markdown for people who check the files their agents keep rewriting. It is in development and has not been released. The app itself has no AI features. Planned for v1 is a Changes View that highlights edits made since your last visit, with no git needed. The same plan lists live rendering of headings, lists, tables and links. It also lists a Frontmatter Table, laying out each YAML key beside its value. It is planned as a reader for your own files; review still happens on your host. The help pages and roadmap, along with the list of planned features, show which parts are planned and how far along each one is.

Track the project at sashmark.com.