Markdown Guidelines: A Style Guide for Clean, Consistent Files

Good markdown guidelines are a short list of conventions that keep every file in a project looking and rendering the same. This style guide gives you 20 rules, the reason behind each one, the markdownlint rule that enforces it, and a config file you can drop into a repo today.

What Are the Style Guidelines for Markdown?

There's no official Markdown style guide. The CommonMark spec defines what parses, not what's tidy. So teams borrow conventions from Google's Markdown style guide, from markdownlint's defaults, and from what GitHub renders reliably. Those three sources agree on more than they disagree, and the rules below are the overlap.

The principle behind all of them: write Markdown that is readable as plain text and renders identically in CommonMark, GitHub, Obsidian, and MkDocs. Anything that only works in one renderer is a portability bug waiting to happen. If you need a syntax refresher before the rules, the Markdown cheat sheet covers every element in one page; this post won't re-teach the syntax.

Document Structure Rules

1. One H1 per file, at the top. It's the document title. Everything else is H2 or deeper. Google's guide says exactly this, and markdownlint enforces it with MD025 (multiple top-level headings) and MD041 (first line should be a top-level heading).

2. Never skip heading levels. H2 to H4 with no H3 in between breaks screen readers and auto-generated tables of contents. MD001 flags it. Our headings guide covers hierarchy in more depth.

3. Use ATX headings (#), not underlines. Setext headings (Title with === beneath) only support two levels and are harder to maintain. MD003 with style: atx.

4. Put a space after the #. CommonMark requires it. #Heading renders as a paragraph containing the literal text #Heading, and so does #hashtag. This is the single most common mistake we see in pasted content. MD018.

5. Surround headings, lists, tables, and code fences with blank lines. Some renderers accept a list glued to a paragraph. CommonMark only lets a bullet list interrupt a paragraph, and an ordered list only if it starts with 1.. A blank line works everywhere. MD022, MD032, MD031, and MD058.

6. End the file with exactly one newline. Git shows "no newline at end of file" otherwise, and concatenating files goes wrong. MD047.

7. Keep lines under 80 characters, or don't wrap at all. Google's guide keeps the 80-character limit for diff readability. Many teams prefer one sentence per line instead, which gives cleaner diffs still. Pick one and set MD013 to match (it defaults to 80).

Lists, Emphasis, and Code Rules

8. Use - for bullets, consistently. Mixing -, *, and + in one list creates three separate lists in CommonMark. A change of marker starts a new list. MD004 with style: dash.

9. Indent nested bullets by the width of the parent marker. Two spaces under - and three under 1. . Four spaces under a bullet is safe too, but it's the point where some parsers start seeing an indented code block. MD007 defaults to 2. See the lists guide for the nesting rules in detail.

10. Number ordered lists as 1. every time, or in strict order. Both render correctly. Lazy 1. numbering means inserting an item never renumbers the list. MD029 accepts either style by default (one_or_ordered).

11. Use **double asterisks** for bold and *single asterisks* for italics. Underscores fail inside words: snake_case_word stays literal because CommonMark doesn't allow intraword emphasis with _. Asterisks work everywhere. MD050 and MD049.

12. Fenced code blocks only, with a language. Indented code blocks can't declare a language, so they never get highlighting, and they conflict with nested lists. MD046 and MD040.

```bash
npm install markdownlint-cli2
```

13. Use inline code for anything you'd type. File names, flags, commands, and keys go in backticks. It also escapes characters like * and _ that would otherwise be parsed.

Links, Images, HTML, and Whitespace Rules

14. Never leave a bare URL. https://example.com on its own line isn't a link in CommonMark (it is on GitHub, via the autolink extension). Wrap it in <https://example.com> or give it link text. MD034.

15. Write descriptive link text. "Here" and "click this" tell a screen reader nothing. MD059 checks for the worst offenders.

16. Use reference links for long URLs in prose. [the spec][cm] with [cm]: https://spec.commonmark.org/0.31.2/ at the bottom keeps paragraphs readable in source form.

17. Every image gets alt text. ![]() with an empty alt fails accessibility checks and MD045.

18. Prefer Markdown to HTML. HTML in Markdown doesn't render the same in every tool (Obsidian sanitises it and some static site generators escape it) and can't be linted. Use it only for things Markdown can't do, and keep it to simple tags. MD033 flags inline HTML if you want to ban it outright.

19. No trailing spaces. Two trailing spaces are a valid hard line break in CommonMark, but they're invisible, editors strip them, and reviewers can't see them in a diff. Use a backslash at the end of the line or a blank line instead. MD009. Our line break guide explains the trade-offs.

20. No consecutive blank lines, no hard tabs. Two blank lines don't render differently from one, and tabs are interpreted as four spaces in ways that confuse list nesting. MD012 and MD010.

We prefer one sentence per line over 80-character wrapping. It makes a Git diff show exactly which sentence changed, and no renderer cares either way. That preference is the one rule on this list where reasonable teams disagree, so document your choice and move on.

Try the Markdown Guidelines in the Editor

Here's a file that breaks several of the rules above. Watch how the preview differs from what the author meant, then fix each line and watch it snap into place. The #Heading line renders as plain text, the mixed markers split one list into three, the language-less fence gets no highlighting, and snake_case_bug stays literal. The glued list and the bare URL happen to render here because this editor, like GitHub, is forgiving; a stricter renderer would show them as text.

npm install

The formatter tool normalises list markers, heading spacing, and blank lines automatically. It's the fastest way to bring an old file up to these guidelines before you turn on a linter.

How Do You Enforce Markdown Guidelines Automatically?

Rules that aren't enforced get ignored within a month. markdownlint is the standard enforcement tool: it runs in VS Code as an extension, on the command line as markdownlint-cli2, and in CI. Every rule above maps to a markdownlint ID, and the rules reference documents each one with fixable examples.

This .markdownlint.jsonc encodes the 20 rules. Drop it in the repo root:

{
  "default": true,
  "MD003": { "style": "atx" },
  "MD004": { "style": "dash" },
  "MD007": { "indent": 2 },
  "MD013": false,
  "MD033": false,
  "MD046": { "style": "fenced" },
  "MD049": { "style": "asterisk" },
  "MD050": { "style": "asterisk" }
}

"default": true turns on every rule, so MD009, MD012, MD018, MD022, MD025, MD034, MD040, MD041, MD045, and MD047 are all active without being listed. MD013 is off because we use one sentence per line; set it to { "line_length": 80 } if you wrap instead. MD033 is off to allow the occasional <br /> or <details> block; turn it on for a pure-Markdown project.

Add one paragraph to CONTRIBUTING.md so new contributors know why the check exists.

Markdown files are linted with markdownlint. Run `npx markdownlint-cli2 "**/*.md"`
before opening a pull request, or install the markdownlint VS Code extension
to see problems inline. The config in `.markdownlint.jsonc` explains each rule.

The markdown lint guide covers installing the CLI, the VS Code extension, the auto-fix flag, and the GitHub Action. This post stops at the config.

Where the Guidelines Bend by Platform

GitHub. GFM adds tables, task lists, strikethrough, and bare-URL autolinks, so rule 14 is technically optional in a README. Keep it anyway: the same file may be rendered by a docs generator that doesn't autolink. The README guide applies these rules to a project README specifically.

Obsidian. Wiki-links ([[Note]]) and ==highlights== are Obsidian-only. If the vault will ever be published elsewhere, stick to standard links.

MkDocs and Docusaurus. Both read frontmatter and both are strict about blank lines around lists. Rule 5 saves the most debugging time here.

One limitation of any guideline set: it can't cover admonitions, callouts, and footnotes, because those differ per platform. Document the flavour your project targets and add its extensions to the guide rather than pretending they're portable.

Markdown Guidelines FAQ

Adopting markdown guidelines is mostly a matter of picking the portable form of each element and letting a linter remind you. The 20 rules here, plus the config above, are what we use on our own docs. To test a file against them right now, paste it into the editor and read the preview for anything that renders differently than you meant. Then run it through the formatter before you commit.