Markdown Setext Headings
Last updated: 2026-10-14
Setext Headings CommonMark core
The legacy heading style: a line of = under text makes a top-level heading, a line of - makes level two — same result as ATX (#). Worth knowing to read old docs and dodge the --- surprise.
| Group | Edge Cases & Rules |
|---|---|
| Spec level | CommonMark core |
| Spec version | CommonMark 0.31.2 + GFM |
📝 Syntax
Heading
======
Heading
------▶ Live Example
Edit Markdown on the left, see the result on the right
💡 Key points
⚠️ Warning Classic trap: a stray --- under a paragraph silently turns it into a level-2 heading.
💡 Tip Use ATX (#) headings in new documents; Setext is trivia-plus-survival.
❓ FAQ
Q Why the name Setext?
A From the 1990s Setext (Structure Enhanced Text) format that Markdown inherited.
Q Are there higher levels?
A No — only levels 1 and 2; deeper levels require #.
Q How many = or - marks are needed?
A Any count of 1+ is valid; tradition writes them as wide as the text.
📚 See also
HeadingsCommonMark core Horizontal RulesCommonMark core