NanoFile

Markdown line break

Pressing Enter once does nothing visible: markdown joins the two lines into one paragraph. This is the single most common markdown surprise, and there are three ways around it.

Two spaces at the end of the line
first line  
second line

first line
second line

The two trailing spaces are invisible in your editor, which is exactly why this trips people up.

A backslash at the end of the line
first line\
second line

first line
second line

Visible, so it survives editors that trim trailing whitespace. Supported by CommonMark and GitHub.

A blank line, for a new paragraph
first paragraph

second paragraph

first paragraph

second paragraph

Not a line break but a paragraph break, which is usually what was wanted anyway.

The HTML escape hatch
first line<br>
second line

first line
second line

What usually goes wrong

  • Many editors strip trailing whitespace on save, silently removing the two spaces that made your line break work. Use the backslash or <br> if yours does.
  • Inside a table cell, none of the three work: use <br>.
  • Three or more blank lines collapse to one paragraph break. Markdown has no way to add vertical space, which is a formatting job for CSS.

Where it behaves differently

PlatformBehaviour
GitHub comments and issuesA single newline does break the line here, unlike in .md files. GitHub turns on “breaks” for comment fields, which is why the same text behaves differently in a README.
Discord and SlackA single newline breaks the line, as in any chat app.
ObsidianFollows the file rule by default, with a setting to switch it.

Questions

Why did my line break work in a GitHub comment but not in my README?

GitHub renders comment fields with line breaks turned on and .md files without. The same source, two different settings. Use two trailing spaces or a backslash and it works in both.

How do I add a blank line between paragraphs?

Leave one empty line. More empty lines do not add more space, because markdown collapses them.

Related