Markdown Trailing Spaces, Hard Breaks and Setext Headings
Trailing spaces are sometimes content
In CommonMark, two or more spaces at the end of a line, followed by another line in the same paragraph, produce a hard line break (<br>). A tool that trims trailing whitespace deletes that break and joins the two lines into one wrapped paragraph. The home-page tidy does exactly that, on every line.
| Source | Rendered |
|---|---|
line one␣␣ newline line two | two lines |
line one newline line two | one wrapped line |
line one\ newline line two | two lines (backslash break) |
A backslash at the end of the line is a hard break that survives trimming, and it is visible in the source. Prefer it in files that an editor or CI will trim.
The linter reports two-or-more trailing spaces as information (they may be intentional) and a single trailing space as a warning (it renders as nothing).
#Title is not a heading
CommonMark requires a space after the # characters. #Title is a paragraph that happens to start with a hash. GitHub renders it literally. The linter flags it.
A dash line can turn text into a heading
A line of --- or === directly under a paragraph makes that paragraph a heading (setext style), instead of drawing a rule:
Some text
---renders "Some text" as an h2. Put a blank line above the --- if you meant a horizontal rule. The linter flags a dash or equals line that follows paragraph text.
Heading levels and fences
- A jump from
#to###leaves a gap that outline tools and screen readers expose; the linter warns. - An opening code fence with no closing fence turns the rest of the document into code; the linter reports it as an error on the last line, because that is where the problem becomes visible.