Skip to content
markdown→html

Syntax Reference

Markdown Headings

Markdown headings convert to HTML heading elements. ATX style uses 1 to 6 hash characters for h1 through h6. Setext style underlines text with equals signs for h1 or hyphens for h2.

Key facts

HTML output
<h1> through <h6>
Heading levels
6
ATX syntax
1 to 6 hashes plus a space
Setext syntax
=== for <h1>, --- for <h2>

How do Markdown headings convert to HTML?

Markdown headings convert to the 6 HTML heading elements, <h1> through <h6>. The number of leading hash characters sets the level: 1 hash becomes <h1>, 2 becomes <h2>, and so on through 6 hashes for <h6>.

Headings define the document outline that browsers and search engines read. Markdown supports two heading styles, ATX and Setext, both covered below. For the full syntax set, see the Markdown Syntax Guide, or jump to the Markdown Cheat Sheet for every element at a glance.

markdown
# Title
## Section
### Subsection
html
<h1>Title</h1>
<h2>Section</h2>
<h3>Subsection</h3>

How do you write an ATX heading in Markdown?

Write an ATX heading by starting a line with 1 to 6 hash characters, a space, then the text. One hash converts to <h1>, six hashes convert to <h6>. The space after the hashes is required.

ATX is the most common heading style. Without the space after the hashes, the parser treats the line as plain paragraph text, so #NoSpace renders as a <p>, not a heading.

markdown
#### Fourth-level heading
###### Sixth-level heading
html
<h4>Fourth-level heading</h4>
<h6>Sixth-level heading</h6>

How do you write a Setext heading in Markdown?

Write a Setext heading by underlining text on the next line. A row of equals signs converts the text to <h1>; a row of hyphens converts it to <h2>. Setext supports only these 2 levels.

Setext covers just <h1> and <h2>, so use ATX hashes for levels 3 through 6. The underline needs at least 1 equals sign or hyphen, and any length works.

markdown
Title
=====

Section
-------
html
<h1>Title</h1>
<h2>Section</h2>

How many heading levels does Markdown support?

Markdown supports 6 heading levels, matching the 6 HTML heading elements <h1> through <h6>. ATX style reaches all 6 levels with 1 to 6 hashes. Setext style reaches only 2 levels, <h1> and <h2>.

Seven or more hashes exceed the range, so ####### Text renders as a paragraph rather than a heading. Stay within 6 hashes to produce a valid heading element.

When should a page use only one H1 heading?

A page should use exactly one <h1> as its main title. Use <h2> through <h6> to nest sections beneath it. A single <h1> gives the document one clear top-level topic for browsers and search engines.

Skipping levels, such as an <h2> followed by an <h4>, breaks the outline. Keep heading levels sequential. This converter seeds its live demo at <h2> so the example never competes with the page's single <h1>.

What other Markdown heading rules affect the HTML output?

Optional closing hashes are stripped, so ## Heading ## still converts to <h2>Heading</h2>. Inline syntax inside a heading converts too: **bold** becomes <strong> and `code` becomes <code> within the heading element.

These details round out the heading syntax. To see headings alongside every other element, open the Markdown Cheat Sheet or return to the Markdown Syntax Guide hub.

markdown
## Heading with `code` ##
html
<h2>Heading with <code>code</code></h2>

Frequently Asked Questions

What HTML element does a Markdown heading become?
A Markdown heading becomes an HTML heading element, <h1> through <h6>. The hash count sets the level: 1 hash is <h1>, 2 is <h2>, continuing to 6 hashes for <h6>. Setext underlines produce <h1> or <h2>.
Why is my Markdown heading not converting to HTML?
A missing space after the hashes is the usual cause. ATX headings require a space between the hashes and the text, so #Title renders as a paragraph while # Title converts to <h1>. Seven or more hashes also fail.
What is the difference between ATX and Setext headings?
ATX headings prefix text with 1 to 6 hash characters and reach all 6 levels. Setext headings underline text with equals signs for <h1> or hyphens for <h2>, supporting only those 2 levels.
Can a Markdown heading contain bold or links?
Yes. Inline Markdown inside a heading converts normally. Bold becomes <strong>, italic becomes <em>, links become <a>, and inline code becomes <code>, all nested inside the heading element.