Markdown headings: the six levels, hierarchy and anchor IDs

Setext headings and the dashed-line trap

Markdown has an older second syntax: underline the text with equals signs for level 1, hyphens for level 2.

Release notes
=============

Version 2.4
-----------

These are Setext headings. One character is enough, since = and =========== mean the same thing, and the underline need not match the title's width. The text may even wrap across several lines, which ATX cannot do.

Only two levels exist

There is no Setext equivalent of H3 to H6. A document written this way has to switch to hashes the moment it needs a third level. Most formatters, Prettier included, rewrite Setext to ATX anyway. Use hashes for new writing.

The trap that catches everybody

Because hyphens under text create an H2, this does not do what it looks like:

Deploy the build, then run the smoke tests.
---
The next section starts here.

The author wanted a horizontal rule. They got an H2 containing that whole sentence. A blank line fixes it, detaching the hyphens so they read as a thematic break:

Deploy the build, then run the smoke tests.

---

The next section starts here.

Two habits stop it coming back:

• Write rules as *** or ___. Neither can ever be mistaken for a heading underline.
• Remember that YAML front matter in Jekyll, Hugo and Astro also uses ---, and only counts as front matter at the very top of a file.

Hierarchy: one H1, and no skipped levels

Heading levels are not font sizes. They are a nesting structure, and assistive technology and search crawlers both read them as one.

One H1 per document

The H1 is the title: what the whole document is about. Two of them tell a screen reader the page contains two documents. Many static site generators already emit an H1 from the title in your front matter. Where that happens, the Markdown body should start at H2, so check the rendered HTML first.

Do not skip levels

Jumping from ## to #### because the smaller size looked nicer breaks the outline. It costs you in three separate places:

• Screen reader navigation. Users pull up a list of headings and move by "next heading at this level", and a missing level leaves an H4 with no parent.
• Accessibility audits. Automated checks flag it, and it counts against WCAG 1.3.1 Info and Relationships.
• Search. Crawlers use the heading tree to work out which passage answers which question, and featured snippets lean on that structure.

Style headings with CSS if the sizes bother you, and keep the levels honest. Running a draft through the table of contents generator shows the outline you actually wrote, gaps included.

Headings inside quotes, lists and paragraphs

A heading is a block element, so it fits inside any block that accepts blocks.

Inside a blockquote

> ## Deprecation notice
>
> The v1 endpoint stops responding in March.

Prefix every line, the heading included. It still gets an ID, and it still shows up in an auto-generated table of contents. The blockquotes reference covers nesting and the callout syntaxes built on quotes.

Inside a list item

Indent the heading to the item's content column and leave a blank line above it:

1. Prepare the machine

   ### Requirements

   Node 20 or newer, and 2 GB of free disk.

2. Run the installer

It works, but think twice. A heading inside a list claims a place in the outline while visually reading as a sub-item, and it makes the list loose, which respaces every item. Bold is usually better there; see the bold and italic reference. Indentation rules for nested content are in the lists reference.

With no blank line above it

CommonMark and GFM let an ATX heading interrupt a paragraph, so this renders as a paragraph plus an H2:

The build finished in 40 seconds.
## Next steps

Older engines are less forgiving, and some swallow the heading into the paragraph, printing the hashes as text. Setext behaves differently again, since a hyphen row directly under a paragraph line reads as an underline.

Watch out: Leave a blank line above every heading, whatever your renderer allows. One below is optional, though it makes the raw file far easier to scan when you come back to it.

Emoji, CJK and how long a heading should be

Emoji

Emoji render fine in a heading, pasted directly or, on GitHub, as a shortcode such as :rocket:. The complication is the ID. Emoji are stripped during slug generation, and the space they leave becomes a hyphen, so a leading emoji produces an anchor that starts with one.

## 🚀 Getting started    -> #-getting-started

That anchor works. It just looks wrong written by hand. Put the emoji after the text, or copy the anchor from the rendered page.

Chinese, Japanese and Korean

CJK characters survive slug generation on GitHub, so ## 安裝步驟 becomes #安裝步驟. Browsers show it percent-encoded when you copy it, which is normal and still works. Static site generators are less consistent:

• Some keep the characters exactly as GitHub does.
• Some transliterate to pinyin or romaji.
• A few give up and fall back to #section-1.

Test one anchor before writing fifty. Full-width punctuation is dropped like ASCII punctuation, so ## 安裝步驟（進階） becomes #安裝步驟進階.

Length

Keep headings under roughly sixty characters. Long ones wrap awkwardly in tables of contents, produce unwieldy anchors, and get truncated when a search engine lifts them into a result. Front-load the words that matter: "Configuring SSO" beats "A few notes on how you might go about configuring SSO for your team".

Common mistakes and their fixes

1. No space after the hash. The line stays a paragraph and the hashes print. Broken, then fixed:

#Introduction

# Introduction

2. A horizontal rule that turns into a heading. Three hyphens directly under text underline it instead. Broken:

That covers the setup.
---

Fixed with a blank line, or by writing the rule as ***:

That covers the setup.

---

3. Skipping a level for visual reasons. Broken outline, then the fix, which you can style down with CSS if it looks too big:

## Configuration
#### Environment variables

## Configuration

### Environment variables

4. Bold text standing in for a heading. It is invisible to the outline, to screen reader navigation and to every table of contents generator, and it produces no ID to link to. Broken, then fixed:

**Environment variables**

### Environment variables

5. An anchor typed from the heading text. Capitals, spaces and punctuation do not survive. Broken, then fixed:

[jump](#Setting Up the API Key (v2.1))

[jump](#setting-up-the-api-key-v21)

When a heading refuses to behave, paste it into the editor on its own, with a blank line above and below. If it renders there, the problem is context: an indent, a missing blank line, or a list item it was trapped inside. The complete Markdown guide puts headings in sequence with every other element, and what Markdown is explains why a plain-text format cares so much about blank lines. For what usually goes under a heading, see the code blocks and images references.