--- title: "Why editors reformat Markdown on save (and how that bloats your diffs)" slug: why-editors-reformat-markdown-on-save excerpt: "Why a one-word Markdown fix can produce a large diff, and how list markers, wrapping and whitespace settings cause formatting churn." quickAnswer: "Editors reformat Markdown because many of them rebuild the file from a document model instead of keeping your text. That swaps list markers, changes emphasis characters, rewraps lines and strips whitespace." keyTakeaways: - "Several Markdown source styles can produce the same rendered page." - "A document model may keep the meaning but lose the original list markers, indentation or wrapping." - "Trailing-space changes can remove a Markdown hard line break." - "Choose a style, apply formatting in its own commit, and check the diff before committing." publishedDate: 2026-10-07 dateModified: 2026-10-07 author: Bobby Huang cluster: D role: post status: published related: - see-what-changed-in-a-markdown-file --- You open a Markdown file. You fix one typo. You save. Then the diff shows 140 changed lines. Nothing is broken. The file renders the same as before. But your one-word fix is now buried, and anyone reviewing the commit has to scroll through noise to find it. If agents also write to that file, the next agent edit lands on top of a reformatted file, and the history gets harder to read. This guide explains why that happens, shows what the changes look like, and covers a few ways to keep Markdown diffs small. ## Markdown has many ways to write the same thing Markdown is loose on purpose. The same rendered output can come from several different source texts. A bullet can start with `-`, `*` or `+`. Bold can be `**bold**` or `__bold__`. A heading can use `#` marks or an underline of `===`. Many editors don't keep your source text as you wrote it. They read the file into an internal model of the document (a tree of headings, lists, paragraphs) and then write a fresh file from that model on save. The model remembers that something is a bullet. It often forgets which character you used to make it. So when the editor writes the file back out, it uses its own house style. Every place your file differs from that style becomes a changed line. ## The four usual suspects ### 1. List markers Your file, as an agent wrote it: ```markdown * Draft the summary * Send it to Jane Doe * Ask about the Doe Holdings deadline ``` After save, normalized: ```markdown - Draft the summary - Send it to Jane Doe - Ask about the Doe Holdings deadline ``` Every line changed. The marker swapped from `*` to `-`, and the nested item's indent dropped from four spaces to two. The rendered list looks identical. Ordered lists get the same treatment. Some writers number every item `1.` and let the renderer count. A normalizer may renumber them `1.`, `2.`, `3.`, or the reverse. ### 2. Emphasis Before: ```markdown This is __important__ and this is *subtle*. ``` After: ```markdown This is **important** and this is _subtle_. ``` One changed line, but in a long file with many bold words, this touches lines all over the document. ### 3. Line wrapping This one does the most damage. Some writers, and many agents, put one sentence per line. Others write one long line per paragraph. A normalizer may rewrap every paragraph to a fixed width, often 80 characters. Before: ```markdown The quarterly review is due Friday. Jane Doe owns the budget section. ``` After, rewrapped to a single paragraph line: ```markdown The quarterly review is due Friday. Jane Doe owns the budget section. ``` Both render as one paragraph. But now every later edit to that paragraph changes the whole line, and a one-word fix in a wrapped paragraph can shift the breaks for every line after it. The diff shows the full paragraph as removed and re-added. ### 4. Trailing spaces and whitespace Two spaces at the end of a line mean a hard line break in Markdown. Many editors strip trailing whitespace on save. That changes the line in the diff, and it can also change how the file renders, because the hard break is gone. Other quiet changes in this group: - adding or removing a final newline at the end of the file - collapsing two blank lines into one - converting tabs to spaces - changing line endings between LF and CRLF Some of these changes leave the rendered page unchanged. Changes to tabs or indentation can alter code blocks or list nesting. All of them show up in a line diff. ## Why this hurts more when agents write your Markdown When one person edits a file in one tool, the reformat happens once and then settles. When agents write the file, each agent writes in its own style. Then a person opens it and the editor rewrites it back to house style. Then the agent writes again in its style. The file flips back and forth. Each round is a large diff with a small real change hiding inside it. Review gets slower, `git blame` points at the wrong commit, and merge conflicts show up on lines nobody meant to touch. ## How to keep Markdown diffs small You have a few options. Pick the one that fits how your team works. **Agree on one style and write it down.** Choose a list marker, an emphasis style and a wrap rule (one sentence per line keeps diffs smallest). Put it in the instructions your agents read, so they write in that style from the start. **Run a formatter once, in its own commit.** If you want a house style, apply it to the whole repo in a single commit with no content changes. Later diffs stay small because the files already match. Some teams list that commit in a "blame ignore" file so line history skips it. **Turn off format-on-save for Markdown.** Most editors let you scope format-on-save by file type. If your files are written mostly by agents, leaving Markdown alone on save is often the simplest fix. **Check whitespace settings.** Look at "trim trailing whitespace" and "insert final newline" settings, and set line endings per repo with a `.gitattributes` file. **Read the diff before you commit.** A quick `git diff --stat` shows how many lines changed. If a one-word fix shows 100 lines, stop and find out why before you push. ## Where Skimmark fits Skimmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development, and nothing is released yet. A clean Round-Trip is planned for v1: lines you did not edit are meant to stay byte-for-byte the same on save. [What is a byte-for-byte round-trip save?](https://www.skimmark.com/blog/what-is-a-byte-for-byte-round-trip-save) explains the term. ## The short version Editors reformat Markdown because many of them rebuild the file from a document model instead of keeping your text. That swaps list markers, changes emphasis characters, rewraps lines and strips whitespace. Some of these changes leave the rendered page unchanged. Changes to tabs or indentation can alter code blocks or list nesting. The diff fills with noise. Pick one style, apply it once, scope format-on-save, and read your diff stat before you commit. ## Next read [Seeing what changed in a Markdown file: git, diff tools, and readers](https://www.skimmark.com/blog/see-what-changed-in-a-markdown-file) covers the wider diff workflow. Skimmark is in development. [Skimmark](https://www.skimmark.com/) is the home page.