The Markdown File Changed Even Though I Only Edited One Word

I once opened a Markdown file, changed one word and saved it.

The preview looked exactly as expected. Then I checked the Git diff and found changes all over the document.

Paragraphs had been rewrapped. Blank lines had appeared between list items. A few characters had been escaped. My one-word edit was still there, but it was buried inside a much larger rewrite.

The editor had not simply changed the text I touched. It had parsed the whole document, converted it into an internal format, then generated new Markdown when I saved.

That process is called a round trip, and it can be surprisingly lossy.

The preview does not tell the whole story

These two Markdown paragraphs usually render the same way:

This paragraph is wrapped manually
at a comfortable source width.

This paragraph is written on one long line.

After parsing them, an editor may only know that each one is a paragraph. It may not remember how the original source was wrapped.

When the file is saved again, the editor has to decide what Markdown to produce. It might join the lines, rewrap them at a different width or preserve every newline as a visible break.

This gets more important when a line ends with two spaces or a backslash. Those can create an intentional hard break. Trimming what looks like unnecessary whitespace may change how the document renders. I ended up documenting the difference between soft and hard Markdown line breaks because it is an easy detail to miss.

Lists have the same problem

This is a tight list:

- Alpha
- Beta
- Gamma

This is a loose list:

- Alpha

- Beta

- Gamma

They may look almost identical under some themes, but their Markdown structure is different. If an editor always saves lists in its preferred style, a tiny edit can produce a very noisy diff.

The same thing happens with indentation in nested lists, aligned table columns and reference-style links. The document may still render correctly, but the source is no longer the source you opened.

App-specific Markdown makes it harder

Real Markdown files often contain syntax that is not part of standard Markdown:

[[Project Roadmap]]
#release
> [!NOTE]
> This ships on Friday.

One app may understand those as a wiki-link, a tag and a callout. Another editor may see ordinary punctuation and escape it when saving.

That is why “supports Markdown” can mean very different things. CommonMark, GitHub Flavored Markdown, Pandoc and apps such as Obsidian do not all understand the same syntax.

If an editor does not recognise something, leaving it untouched is often safer than trying to correct it.

A simple test

There is an easy way to check an editor before trusting it with important files:

1. Copy a representative .md file.
2. Open it and change one ordinary word.
3. Save and close it.
4. Compare the saved file with the original.

The diff should show the word you changed and nothing unrelated.

Try the same test without editing anything. Just open and save the file. Ideally, it should remain identical.

Use a real document containing the things you normally write, such as nested lists, tables, code blocks, maths, images, front matter or wiki-links. A perfect five-line README will not expose much.

Opinionated formatting is not always bad. A team may deliberately choose one Markdown style and format every file consistently. The important thing is that the behaviour is clear and expected.

But if the editor promises to work with existing Markdown files, the source matters as much as the preview.

Change one word, save the file, and check what else changed.