--- title: "Markdown rendered diff vs line diff: what each one hides" slug: rendered-vs-line-diffs-markdown excerpt: "One Markdown edit compared as a line diff, a word diff and a plain-text stand-in for a rendered view, plus an order to read them in." quickAnswer: "This post sets a markdown rendered diff beside two raw views of the same edit: a line diff and a word diff. The body explains which question each view answers, compares the test results using a plain-text stand-in for the rendered view, and gives an order for reading them." keyTakeaways: - "The body compares a line diff, a word diff and a rendered diff on one test file." - "The line diff section walks through the test's rewrapped paragraph and its one-word change." - "The word diff section includes a second test built around a spacing edit." - "The rendered diff section goes through each edit from the test and how it looked as page text." - "The closing sections give a reading order and the signs that one view is not enough." publishedDate: 2026-10-20 dateModified: 2026-10-20 author: Bobby Huang cluster: D role: post status: published faq: - q: Why does my line diff mark a whole paragraph when I changed one word? a: "The line diff section walks through this case with a test file, and the word diff section looks at the same edit another way." - q: Can a rendered diff miss a change? a: "The rendered diff section takes up this question with the test file and names the spec rule behind each case." - q: Which view should I check last? a: "The section on picking a view gives an order and explains why one of the three goes at the end." related: - see-what-changed-in-a-markdown-file - how-to-diff-markdown-files-with-git - rendered-vs-raw-agent-markdown --- An agent edits a Markdown file and you need the exact edit. You can look at that change as raw lines, as single words, or as a formatted page with the edits marked. Those three views don't agree with each other. On one small test file, each of them missed or overstated something the others got right. This post runs that file through all three and says when each one earns its place. It skips setup. The [git walkthrough](how-to-diff-markdown-files-with-git.md) and the [what-changed guide](see-what-changed-in-a-markdown-file.md) cover the commands step by step. ## The test edit The old file was a short plan: a heading, a three-line paragraph, a link and a numbered list. The new version changed four things: - **One word.** "Monday" became "Tuesday". - **The wrap points.** The paragraph is still three lines, but each line now breaks at a different word. - **A link target.** `notes/q3.md` became `notes/q4.md`. The link text, "status report", stayed the same. - **Two list numbers.** Items written as `2.` and `3.` became `1.` and `1.`. In the plain-text test below, only the first change showed up as different words on the page. The other three are real edits to the file, and each view handles them differently. ## The line diff A line diff compares raw text one line at a time. Running `git diff` gave this hunk, and `diff -u old.md new.md` gave the same one: ```diff # Launch plan -Jane Doe will send the draft to the review team on Monday, and the -team will reply with notes by the end of the week so the final copy -can go out on time. +Jane Doe will send the draft to the review team on Tuesday, and the team will +reply with notes by the end of the week so the final copy can go out on +time. -See the [status report](notes/q3.md) for details. +See the [status report](notes/q4.md) for details. 1. Write the draft -2. Review the draft -3. Send the draft +1. Review the draft +1. Send the draft ``` All four changes are in there. Every changed line is listed, which is why this view is the one to trust before you commit or accept an edit. The trouble is weight. Six lines are marked as removed and six as added, yet a reader would only spot a single new word. The new day sits inside a block of removed and added lines that looks like a rewrite. The renumbered list looks like two edits too, but on the page it reads the same. In CommonMark, an ordered list takes its start number from its first item, and the numbers on later items are ignored. **Reach for it when:** you need the final word on what the file now holds, or the change is about spacing, indents or list markers. ## The word diff Running `git diff --word-diff` on the same edit gave this: ```text Jane Doe will send the draft to the review team on [-Monday,-]{+Tuesday,+} and the team will reply with notes by the end of the week so the final copy can go out on time. See the [status [-report](notes/q3.md)-]{+report](notes/q4.md)+} for details. 1. Write the draft [-2.-]{+1.+} Review the draft [-3.-]{+1.+} Send the draft ``` Removed words sit in `[-...-]` and added words in `{+...+}`. The rewrap is gone from view. By default, git splits words on whitespace, so moving a line break between two words is not a word change. The real edit now stands out. `git diff --color-words` marks the same words with color instead of brackets. Notice the link line, though. The whole run `report](notes/q3.md)` has no spaces in it, so git treats it as one word. You still see that the target changed, but you have to read the brackets closely. That same rule about whitespace is also this view's blind spot. In a second test, the sole edit was two spaces added to the end of one line. The word view showed a hunk where no word was marked. A plain `git diff` showed the line as removed and added. Those two spaces aren't noise in Markdown. Outside a code span or HTML tag, a line ending that follows two or more spaces, when it is not the last line of a block, is parsed as a hard line break. Pandoc turned the old file into one paragraph and the new file into a paragraph with a `
` in it. **Reach for it when:** prose was rewritten or rewrapped and you want the words that changed, not the lines. ## The rendered diff With this third view, edits may be flagged right in the styled output, though what gets flagged varies by tool. Some review tools and viewers offer one, and how they mark changes may differ from one to the next. To see what a page-level view has to work with, turn both versions into plain text with pandoc and compare the results: ```sh pandoc -f commonmark -t plain old.md > o.txt pandoc -f commonmark -t plain new.md > n.txt diff -u o.txt n.txt ``` The diff had one change in it: "Monday" to "Tuesday". Pandoc's plain text is a stand-in for the page, not a rendered diff tool, but it shows why the other three edits faded out: - **The rewrap.** A plain line ending inside a paragraph is a soft line break, which may be rendered as a space or a line ending. Pandoc reflowed the paragraph on its own, so the old wrap points were gone before the compare ran. - **The list numbers.** Only the first item sets the start number, so both lists rendered as the same 1, 2, 3. - **The link target.** A link has visible text and a separate destination. The text didn't change, so the words on the page didn't either. Pandoc's HTML output (`-t html`) did show `href="notes/q4.md"` in place of `notes/q3.md`, but many page views show a target only when you hover over or open the link. Link reference definitions fall in the same gap. The spec says a definition is not a structural element of the document. It only defines a label for links elsewhere. Change the URL in a link reference definition, and the page text can look the same while every link that uses that label now points somewhere new. **Reach for it when:** a long section, a table or a list was rewritten and you want to read the result the way your readers will. ## Picking a view No single view covered this test file on its own. A working order: 1. **Read the rendered diff first** to see what the change means for a reader. 2. **Read the word diff** when prose was touched, to find the exact words without wrap noise. 3. **Check the line diff last.** It marked all four edits in the test file. Neither of the other two did. If your raw diffs are noisy for every edit, the cause may sit upstream of the view. The post on [cutting diff noise from agents](keep-agent-markdown-diffs-small.md) handles that side. ## Signs one view isn't enough - **Every line of a paragraph shows as removed and added.** Switch to the word diff. A rewrap is the likely cause. - **The word diff shows a hunk with nothing marked.** Look at the line diff for spaces that changed. - **The page reads the same, while the line diff isn't empty.** Check link targets, reference definitions, list numbers and trailing spaces. - **A link looks right but goes to the wrong file.** The rendered view showed you the text. The raw diff shows you the target. For the wider question of when to read a file raw or rendered, outside of diffs, see [raw or rendered reading](rendered-vs-raw-agent-markdown.md). ## Where Sashmark fits The team behind Sashmark is building a desktop Markdown app for files that agents rewrite often. One feature on its v1 plan, Changes View, is meant to highlight edits made after your last look, with no git needed. Pair a page view like that with the raw diff. It is in development and has not been released. The app itself has no AI features. Scope is listed under [planned features](/features), behavior is in the [help pages](/help), and status is on the [roadmap](/roadmap). News on the project lives at [sashmark.com](https://www.sashmark.com/).