Headings and Paragraphs

ATX Headings

The hash form. One to six hashes, a space, then the text. This is the form every flavor supports and the one to use.

# Heading level 1

Heading level 2

Heading level 3

#### Heading level 4 ##### Heading level 5 ###### Heading level 6

Rules that trip people up:

- The space after the hashes is required in CommonMark. `#Heading` is a plain paragraph.
- Seven or more hashes is not a heading, it is a paragraph starting with hashes.
- Up to three leading spaces are allowed. Four or more makes it an indented code block.
- A blank line before a heading is not required by the spec, but several older parsers (including some wikis) need one, so leave it in.
- Trailing hashes are stripped, so `## Title ##` renders as `Title`.

markdown ### Three leading spaces is still a heading #### Four spaces is a code block, not a heading #No space, so this is a paragraph

Closing hashes are optional ##

Setext Headings

The underline form. Only two levels exist, and it is legal but rarely worth using.

Heading level 1
===============

Heading level 2
---------------

Any number of = or - works, so a single - on the line below text makes an h2. That is the trap: a stray hyphen under a paragraph silently turns it into a heading instead of a horizontal rule.

This becomes an h2
-

But with a blank line between, the hyphen is a thematic break

---

Setext headings cannot be empty, cannot contain a line break, and only work under a paragraph. Prefer ATX everywhere, since it is unambiguous and greppable.

Paragraphs

A paragraph is one or more lines of text separated from its neighbors by a blank line. That is the whole rule.

This is one paragraph. These two lines
both belong to it, because there is no
blank line between them.

This is a second paragraph.

Leading whitespace on the first line is stripped, so do not indent paragraphs to align them. Four spaces of indentation makes a code block instead.

    This indented text renders as code, not as a paragraph.

Blank lines between paragraphs collapse: two blank lines and ten blank lines produce the same output. To force visible vertical space you need raw HTML, which many renderers strip.

Line Breaks

A single newline inside a paragraph is not a line break. The renderer joins the lines with a space, because Markdown treats source wrapping as insignificant.

There are two ways to force a break inside a paragraph.

Line one has two trailing spaces  
so line two starts on its own line.

Line one ends with a backslash\
so line two starts on its own line.

Line one has nothing special
so this joins line one with a space.

Trailing spaces are invisible, get stripped by editors that trim whitespace on save, and are flagged by linters. The backslash form survives all of that, so prefer it. When neither is available, an explicit <br> works wherever raw HTML is permitted.

Heading Anchors

Most renderers derive an id from the heading text so it can be linked. GitHub's algorithm, which many tools copy:

1. Lowercase the text.
2. Strip anything that is not a letter, digit, space, hyphen, or underscore. Punctuation and emoji disappear.
3. Replace each space with a hyphen.
4. On a duplicate, append -1, -2, and so on in document order.

[jump to setup](#setup)
[jump to the second setup section](#setup-1)
[another file's section](./guide.md#getting-started)

The slugging is not standardized, so the anchor GitHub generates and the one a static-site generator generates can differ for the same heading. Anchors built from headings containing code spans, links, or emoji are the usual mismatch.

Document Structure

Conventions rather than syntax, but they are what makes a Markdown file readable in raw form.

• One h1 per document, at the top, matching the title. Many site generators inject the h1 from front matter, in which case start the body at h2.
• Do not skip levels. An h4 directly under an h2 breaks screen-reader outlines and table-of-contents generators.
• Keep headings short. They become anchors, sidebar entries, and search results.
• Blank line before and after every block element (heading, list, fence, table, quote). Some parsers do not need it, and every parser accepts it.
• Pick one line-wrap policy per repository and enforce it with a formatter. Either one sentence per line, which makes diffs readable, or a hard wrap at 80 characters. Mixing both produces noisy diffs.

# Project name

Short description paragraph.

Install

Usage

Options

License