Setext Headings

Markdown supports a second heading style — setext — where the heading text is underlined by a row of = or - characters.

Hello World
===========

A Subheading
------------

renders the same as:

# Hello World

## A Subheading

Rules

• A line of = underneath -> <h1>
• A line of - (two or more) underneath -> <h2>
• Only H1 and H2 — no H3 setext exists
• The underline can be any length (1+ for =, 2+ for -)
• The line above must look like a paragraph (no #, no >, no list marker)

When does setext beat ATX? Setext is older (it predates ATX). It produces more visually obvious headings in plain text — the underline draws the eye even without a renderer. Most modern codebases prefer ATX for consistency, but a parser MUST support both because real-world Markdown contains both.

Trap: the --- form is ambiguous with a thematic break (<hr />). The rule is: if a non-empty paragraph line precedes a row of ---, it is a setext H2. Otherwise it is a thematic break. This means the renderer needs lookahead and lookbehind during block parsing — you cannot decide what --- means by looking at that line alone.