Hard-Wrap or Soft-Wrap Your Notes? The Diff Decides

Wrap width is diff granularity. If your note is one long line, a one-word edit rewrites that whole line in git diff. If your note is hard-wrapped at 80 columns, a one-word edit rewrites one line. Neither is universally right. The diff you want to read tomorrow decides the wrap you author today ^{1 2}.

Prettier ships this argument in three lines of documentation. Its proseWrap option defaults to "preserve", not "always" or "never", because "some services use a linebreak-sensitive renderer, e.g. GitHub comments and BitBucket" ³. The tool refuses to overwrite an intent it can't infer. This post walks you through the diff-test — the four-step decision procedure that infers the intent for you, then names the tool you set to respect it.

What CommonMark actually says about a line break

CommonMark treats a soft line break as whitespace, and a hard line break as an explicit switch — either two trailing spaces or a backslash at the end of the line — that renders as a <br /> tag ¹. That single fact is the quiet reason your line break didn't show up. A lone Enter is a soft break; the renderer collapses it into a space. Two spaces or a backslash is the toggle you were missing ⁴.

The spec is short about this on purpose. Example 634 gives the backslash the same status as the two-space form, verbatim: "For a more visible alternative, a backslash before the line ending may be used instead of two or more spaces" ¹. GitHub restates the identical rule in its writing docs for .md files ⁴. Issues, Discussions, and PR comments, however, do something different — and that difference is where the wrap debate begins.

The two camps, stated fairly

There are three defensible positions on how to wrap a Markdown note, and they disagree about what a good diff looks like. Position A leaves each paragraph as one long line and lets the editor wrap visually. Position B hard-wraps every paragraph at a fixed column (usually 72–80). Position C — semantic line breaks — breaks after each substantial unit of thought instead of at a column count ⁵.

Position A gives short files and paragraph-scoped diffs. Line-length arithmetic never leaks into content decisions.

Position B gives rectangular files that fit any editor at any width. Linux kernel style calls it: "The preferred limit on the length of a single line is 80 columns. Statements longer than 80 columns should be broken into sensible chunks, unless exceeding 80 columns significantly increases readability and does not hide information" ⁶. Even the strictest authority lets you off.

Position C is old. Brandon Rhodes named the modern practice in 2012: "Instead of fussing with the lines of each paragraph so that they all end near the right margin, they can add linefeeds anywhere that there is a break between ideas… your version-control system will love semantic linefeeds" ⁷. Mattt's Semantic Line Breaks specification made it precise around 2017: "When writing text with a compatible markup language, add a line break after each substantial unit of thought," and "A semantic line break MUST NOT alter the final rendered output of the document" ⁵. Robert Lin (bobheadxi) extended the argument into modern developer-review terms in 2021 ⁸.

The deeper thread is 1974. Brian W. Kernighan's Bell Labs Technical Memorandum 74-1273-18, "UNIX for Beginners," told writers preparing documents in nroff: "Start each sentence on a new line. Make lines short, and break lines at natural places, such as after commas and semicolons, rather than randomly" ⁹. Everything since is a rediscovery.

Semantic line breaks are honest about their cost

Semantic line breaks are beautiful in a .md file and brittle in two real places. Position C wins on clause-level diffs and loses on renderers that treat a single newline as content, so the case for it fails if you skip the caveats. The Hacker News thread on the sembr spec surfaced both objections in one weekend of comments ¹⁰.

The em-dash collision. The sembr spec says "A semantic line break SHOULD occur after an […] em dash (—)" ⁵. On Hacker News in September 2025, one commenter (chrismorgan) put the objection plainly: "I agree with this, however it means that no existing markup language supports semantic line breaks, because every last one of them just turns the break into a space — and em dashes are, in most locales, not to be surrounded by a space. Consequently, you'll end up with a stray space if you do this" ¹⁰. That is a real, load-bearing objection: a soft break between the words on either side of an em dash renders as a space, and typographic convention says no space.

The GitHub-Issues collision. GitHub's .md renderer follows CommonMark; a single Enter is whitespace and semantic breaks read cleanly. GitHub Issues, Discussions, and pull-request comments do not — a single \n in that context is rendered as <br>. On the same HN thread, account42 made the pro-hard-single-linebreak case: "The problem is that this makes having line breaks that are not paragraph breaks in the output much more awkward, and I think those are much more important than line breaks that are only there in the source" ¹⁰. Semantic breaks work in the file; they insert extra <br> in the comment box.

Both objections are correct. Both are why sembr.org's own FAQ tells you: "git diff can normalize line changes in a way that may obscure certain revisions to text with semantic line breaks. You can pass the --word-diff option to the git diff command for better results" ⁵. If you pick semantic line breaks, you accept the cost, and you learn git diff --word-diff.

Why the numbers cluster at 65–80

Every widely used prose reformatter picks a width in the 70-something range. That is not a punch-card accident but a converged answer to a typographic question about how many characters the eye can track without losing its place. Robert Bringhurst's Elements of Typographic Style — via Richard Rutter's web mirror — collects the consensus: "Anything from 45 to 75 characters is widely regarded as a satisfactory length of line" with "the 66-character line… widely regarded as ideal" ¹¹.

Every tool sits inside that band. GNU fmt defaults to -w 75 maximum with a goal of 93% of width — roughly 70 ¹². GNU Emacs's M-q (fill-paragraph) fills to fill-column, "the default value (see Local Variables) is 70" ¹³. Vim's gq uses 'textwidth'; when it's 0, the length is the screen width capped at 79 ¹⁴. Pandoc's --wrap=auto wraps to --columns (default 72) ¹⁵. Kernel style says 80. Bringhurst says 66. If four independent codebases converge on 65–80, the number measures how long a human sentence can be before the eye loses its place ¹¹.

The diff-test — one procedure that decides for you

Do this for the specific note you are wrestling with. It takes four minutes and gives you a per-note answer that a general opinion never will. The test replaces argument with a diff you can read.

1. Write two versions of the same paragraph. Save the paragraph as one long line in note-soft.md. Save the same paragraph, hard-wrapped at 80 columns, in note-hard.md. Same content. Different shape.
2. Change one word in the middle. Not the first word, not the last. Somewhere in the third sentence of the third line.
3. Run git diff --no-index note-soft.md note-soft.edited.md and the same on the hard-wrapped pair. Look at the two red/green blocks side by side.
4. Ask: which diff can you read? If the soft-wrap diff is a wall of red and green rewrapping the whole paragraph and the hard-wrap diff is a one-line swap, the note wants hard-wrap. If the soft-wrap diff is a clean single-line swap because the paragraph is short, the note wants soft-wrap. If the note is prose you edit at the clause level — code-review comments, spec text, legal — try the same test with semantic line breaks and git diff --word-diff, then read that.

The test is the decision procedure. There is no verdict beyond the diff you can read tomorrow.

Common mistakes

Five failure modes show up most often when a repo picks a wrap policy without a diff-test to anchor it. Each is easier to spot than to unwind after two months of commits, so read this list before the wrap discussion happens, not after.

• Reflowing a hard-wrapped file with a tool that resets the width. Running fmt -w 100 over a repo hard-wrapped at 72 rewrites every line in every paragraph. The diff is unreadable. Pick one width per repo and keep it there ¹².
• Using single-space line breaks and expecting a <br>. In .md files on GitHub, the break requires two spaces at the end of the first line, or a backslash at the end of the first line ⁴. One space is invisible whitespace; the render collapses it.
• Semantic line breaks in a linebreak-sensitive box. Pasting sembr-shaped prose into a GitHub Issue or Discussion inserts a <br> at every clause ¹⁰. The prose looks like a poem no one asked for. Save sembr for .md files.
• Assuming Prettier will hard-wrap for you. The default is preserve — Prettier will not change your wrapping ³. Set "proseWrap": "always" and a printWidth explicitly if you want it to.
• Forgetting --word-diff. If you soft-wrap prose or use semantic line breaks, the default git diff shows whole-paragraph or whole-clause changes. git diff --word-diff shows the actual word changes and makes reviews readable ⁵.

Tools that respect your choice

MNMNOTE saves the file exactly as you type it — the wrap you author is the wrap on disk, and the wrap on disk is the wrap git diff reads. It has no built-in prose reformatter, so the choice of tool at the boundary is yours. The row-per-tool table below is the one-page reference for how each option handles a Markdown paragraph.

Steph Ango calls the deeper argument "file over app": "Apps are ephemeral, but your files have a chance to last" ¹⁶. Wrap is a property of the file. Whichever camp you land in, the tool you use tomorrow should read your file the same way today's tool does — every tool above respects the shape you author. If yours doesn't, replace the tool, not the shape ¹⁷.

Frequently Asked Questions

The seven questions below are the ones a reader arrives with. Answers stay short so a language model can lift them, and each maps to a section above so you can follow the argument back to the primary source.

Should I hard-wrap my Markdown at 80 columns? It depends on what you diff. If you review the file with git diff, hard-wrap at a fixed width (72–80) so a one-word change produces a one-line diff. If you never diff and always edit through a WYSIWYG, soft-wrap and forget the ruler. Prettier defaults to "preserve" for exactly this reason ³. Test both against your own diff to decide.

How wide should I wrap plain-text notes? Somewhere in the 65–80 range, and the same width across the repo. Bringhurst's typographic measure sits at 45–75 characters with 66 "widely regarded as ideal" ¹¹. fmt defaults to 75 with a 70 goal ¹²; Emacs fill-column defaults to 70 ¹³; Vim's gq caps at 79 when textwidth is 0 ¹⁴; Pandoc's default is 72 ¹⁵. Pick one — 72 or 80 are both fine — and stop tuning.

Why doesn't my Markdown line break show up? Because CommonMark treats a single newline as whitespace. To force a <br> you need two or more spaces at the end of the line, or a backslash ¹. GitHub restates the same rule in its writing docs for .md files ⁴. If you want the break to render, add the two spaces (or use a blank line for a paragraph break).

What is the difference between a hard and soft line break in Markdown? A soft break is a plain newline in the source; the renderer turns it into a space between words. A hard break — two trailing spaces or a backslash — becomes a <br /> tag in HTML ¹. Hard breaks are for line-scoped structure (addresses, verse); paragraph breaks are for prose.

Are semantic line breaks better than hard-wrapping at 80? They are better for prose you review at the clause level, worse for prose you paste into a linebreak-sensitive box. The spec says "A semantic line break MUST NOT alter the final rendered output" ⁵, but the em-dash-and-space collision and the GitHub-Issues \n = <br> collision are real ¹⁰. Run the diff-test on your own file and pick.

How do I make git diff show word changes in Markdown? git diff --word-diff — or git diff --word-diff=color for terminal highlighting. sembr.org's own FAQ recommends it because "git diff can normalize line changes in a way that may obscure certain revisions to text with semantic line breaks" ⁵. It also makes soft-wrapped paragraphs diff-readable.

Does Prettier hard-wrap my Markdown? Only if you tell it to. The default proseWrap: "preserve" leaves your wrapping alone ³. To hard-wrap, set "proseWrap": "always" and a printWidth in .prettierrc. To un-wrap, set "proseWrap": "never".

MNMNOTE saves the file exactly as you type it — the wrap on your screen is the wrap on disk, and the wrap on disk is the wrap the diff reads. Run the four-minute diff-test on your next note, pick a shape, and configure one tool to keep it. mnmnote.com lives in your browser; the file is yours.