ATX headings (the # style)
- `# Title` — level 1, usually one per document
- `## Section` — level 2
- `### Subsection` — level 3
- Keep going to level 6; levels 4–6 are rarely used
- A space after the `#` is required in most parsers
Setext headings (the underline style)
Level 1 and 2 can also be written by underlining the text: a line of `===` makes an H1 and a line of `---` makes an H2. It reads well for a document with just a title and sections, but it only supports two levels and interacts badly with horizontal rules, so most style guides prefer hashes.
How headings become anchors
Renderers generate an id for each heading from its text — lowercased, spaces to hyphens, punctuation stripped. `## Getting Started` becomes `#getting-started`, which is what table-of-contents links point at. Two headings with the same text get `-1`, `-2` suffixes, so duplicate titles can silently break a hand-written anchor.
Heading style rules worth following
- Use one H1 per document, as the title
- Do not skip levels (H2 then H4) — it breaks outlines and screen readers
- Keep headings short and front-load the keyword
- Leave a blank line before and after a heading
Frequently Asked Questions
How many heading levels does Markdown have?
Six, matching HTML's h1–h6. Most documents use two or three.
Do I need a space after the # ?
Yes in virtually all parsers: `# Title` is a heading, `#Title` is usually plain text. Some renderers also strip optional closing hashes like `# Title #`.
How do I link to a heading?
Use the generated anchor: `[Getting Started](#getting-started)`. The id is the heading text lowercased with spaces replaced by hyphens and punctuation removed.
Why does my table of contents link 404?
The heading text changed, or the duplicate-heading suffix shifted (the second `## Setup` becomes `#setup-1`). Regenerate the table of contents after editing headings.