Writing Clean Markdown: Rules Worth Following

Markdown is forgiving, which is both its strength and its weakness — the same document can be written many messy ways. A few consistent rules make Markdown easier to review, diff, and render predictably.

Rules that prevent real bugs

• Increment headings by one. Jumping from # to ### breaks the document outline that screen readers and tables of contents rely on.
• Put a space after the #. #Heading isn't a heading in most parsers — it renders as literal text.
• No trailing whitespace. Two trailing spaces silently become a <br> line break, which surprises people editing the file later.
• Use spaces, not hard tabs. Tabs render inconsistently and break nested list indentation.

Rules that keep things tidy

• No trailing punctuation in headings (## Overview. → ## Overview).
• No stacks of blank lines.
• Keep lines to a reasonable length (e.g. 120 characters) so diffs stay readable.

Why bother

Consistent Markdown produces smaller, clearer diffs in code review — a one-word change shouldn't reflow an entire paragraph — and it renders the same across GitHub, your docs site, and your editor's preview.

Catch issues automatically

The Markdown Linter checks your Markdown against these rules and reports each issue with its line number and a plain-English explanation, skipping code blocks so their contents aren't falsely flagged. And when you need the words without the syntax, Markdown to Plain Text strips it all cleanly.