Markdown · <code># Heading</code> to <code>###### Heading</code>
Headings
ATX headings use one to six # characters; setext headings underline text with = or -.
Key facts
| ATX | <code># Heading</code> to <code>###### Heading</code> |
|---|---|
| Setext | Text underlined with <code>=</code> (h1) or <code>-</code> (h2) |
| Levels | Six in ATX; two in setext |
| Space | Required after the # characters in CommonMark |
| Closing | Optional trailing # characters |
| Standard | CommonMark §4.2, §4.3 |
Two syntaxes, one outline
ATX headings are the familiar form: ## Installation. CommonMark requires a space between the hashes and the text, so #hashtag is a paragraph, not a heading. Up to three leading spaces are allowed; four make it an indented code block.
Setext headings underline a paragraph with = for level one or - for level two. They are valid but rare, and a line of dashes under text can also be read as a thematic break if the spacing is wrong.
Levels and anchors
Use one level-one heading per document and keep the hierarchy sequential. Skipping from h2 to h4 breaks screen-reader navigation and document outlines even though the renderer accepts it.
Heading anchors are not part of Markdown. Static site generators and GitHub derive an id from the text, usually lowercased with spaces replaced by hyphens. Duplicate headings get numeric suffixes, and changing the heading text breaks existing links.
Frequently asked questions
Is a space required after #?
In CommonMark, yes. Many legacy parsers accept #Heading, but the portable form includes the space.
Can I use more than six # characters?
No. Seven or more is not a heading; it renders as paragraph text.