Markdown Headings Guide: How to Use H1–H6 Tags the Right Way

Headings are the skeleton of every document. They break up walls of text, give readers a roadmap, and tell search engines and screen readers what matters most. If you're new to the format, our what is Markdown primer is a good starting point — but this guide zooms in on one piece: markdown headings, including how to write the all-important markdown h1.

In Markdown, you create headings by prefixing a line with one to six hash symbols (#). It's fast, readable, and renders cleanly to HTML <h1> through <h6> tags. This guide covers the exact ATX syntax, when to use each level, the older Setext style, auto-generated heading anchors, accessibility and SEO best practices, and the mistakes to avoid. Once you know the rules, headings become second nature.

ATX syntax: prefixing lines with #

The most common heading syntax is ATX style, popularized by John Gruber's original Markdown and used almost everywhere today. You write one to six hash characters followed by a space and then the heading text:

# Heading level 1
## Heading level 2
### Heading level 3
#### Heading level 4
##### Heading level 5
###### Heading level 6

A few rules worth memorizing:

• There must be a space between the # characters and the text. #Heading may render as a tag rather than a heading in some engines.
• You can use up to six # symbols — that maps to HTML's six heading levels.
• A trailing space after the text is fine and harmless.
• Closing hashes are optional. ## My Title ## is valid ATX and renders identically to ## My Title. Many writers add them because the line looks balanced, but they're not required.

For a quick reminder of every heading symbol in context, keep our markdown cheat sheet bookmarked.

The six heading levels and when to use each

Each level signals a different weight in the document outline. Here's how to think about them.

H1 — the document title

Use exactly one # (markdown h1) per page or post. It should describe the whole document, mirror the <title>, and contain your primary keyword. Think of it as the cover of a book.

# Markdown Headings Guide

H2 — major sections

Use ## for the top-level sections readers will scan. A typical article has three to seven H2s, each covering a distinct chunk of the topic. These usually appear as entries in a table of contents.

H3 — subsections

Use ### to break an H2 into smaller pieces. If an H2 is "Syntax," the H3s might be "ATX style" and "Setext style."

H4–H6 — deep nesting

Reserve ####, #####, and ###### for rarely needed deep structure — long technical references, nested API docs, or appendix material. Most everyday writing never goes past H3. If you find yourself at H5, consider whether the document is too flat or too sprawling.

A quick note on Setext headings

Before ATX became standard, Markdown also supported Setext style: underlining a line with = for an H1 or - for an H2.

A First-Level Heading
=====================

A Second-Level Heading
----------------------

Setext only supports two levels (H1 and H2), the underlines can be any length, and you need a blank line before the heading. Most modern parsers — including CommonMark and GitHub Flavored Markdown — still accept Setext, but it's considered legacy. Prefer ATX for new writing. If you'd like to see how Setext behaves in a richer parser, our GitHub Flavored Markdown guide walks through the GFM extras.

Heading IDs and auto-generated anchors

Most renderers automatically generate an id attribute on each heading so you can link directly to it. The slug is usually derived by lowercasing the text, stripping punctuation, and replacing spaces with hyphens:

## Best Practices for Markdown Headings

…renders to:

<h2 id="best-practices-for-markdown-headings">Best Practices for Markdown Headings</h2>

You can then link to it from within the same document:

See the [best practices](#best-practices-for-markdown-headings) section.

Slug rules vary slightly across tools (GitHub, Pandoc, MDX), so a heading like ## C++ & You may produce c-you on one engine and c--you on another. Some flavors, including GFM, also let you set a custom ID:

## Custom Heading {#my-id}

If you're building a navigation list from those anchors, our table of contents guide explains how to collect and order them reliably.

Heading level → HTML tag → typical use

Level	Markdown	HTML	Typical use
1	# Title	<h1>	Document title (once per page)
2	## Section	<h2>	Major sections
3	### Subsection	<h3>	Subsections within an H2
4	#### Group	<h4>	Grouped details, minor nesting
5	##### Item	<h5>	Deep reference material
6	###### Note	<h6>	Fine print, rarely needed

That mapping is one-to-one: write six hashes, get an <h6>.

Accessibility and SEO best practices

Headings aren't just visual — they're a structural contract with assistive tech and search engines.

• One H1 per page. Screen reader users and crawlers use the markdown h1 to grasp the page's purpose. Multiple H1s dilute that signal.
• Don't skip levels. Jumping from ## straight to #### breaks the outline that screen readers navigate by. Go H2 → H3 → H4, not H2 → H4.
• Keep a logical hierarchy. Each heading should nest under a higher-level one the way a chapter nests under a part.
• Write descriptive text. "Conclusion" is fine; "Next steps" is better. Avoid clickbait or keyword-stuffed titles.
• Don't use headings for styling. If you want bigger text in a paragraph, use bold or a styled span — not an <h3>. Headings convey structure, not font size.

Following these rules improves both SEO rankings and the experience for readers using screen readers.

Common mistakes to avoid

• Starting the body with ## when you meant #. Remember: in many publishing systems the page title is already the H1, so your first in-body heading should be ##. In a standalone .md file, though, you usually want a single # at the top.
• Forgetting the space after #. #Title won't render as a heading in strict parsers.
• Using bold (**text**) as a fake heading. It looks similar but carries no semantic weight for accessibility or SEO.
• Five levels deep everywhere. If every section reaches H5, your document is probably too flat — promote sections or split the file.
• Mismatched title and H1. If your frontmatter title is "Markdown Headings Guide," your H1 should match, not say "A Deep Dive Into Headers."
• Duplicate IDs. Two headings with the same text get the same auto-slug, breaking anchor links. Rename one or assign a custom ID.

Frequently Asked Questions

How many H1 tags should a Markdown document have?

Exactly one. The markdown h1 is the document's title and should mirror the page <title>. Multiple H1s confuse screen readers and dilute the SEO signal. Put your keyword-rich title at the top and use ## for everything else.

What's the difference between ATX and Setext headings?

ATX uses leading hash symbols (# to ######) and supports all six levels. Setext underlines text with === (H1) or --- (H2) and only supports two levels. ATX is the modern default; Setext is legacy but still parsed for backward compatibility.

Do Markdown headings get auto-generated IDs?

Yes, in most renderers. The text is lowercased, punctuation is stripped, and spaces become hyphens, producing an anchor you can link to with #slug-text. Slug rules differ slightly between GitHub, Pandoc, and MDX, and some flavors let you override the ID with {#custom-id}.

Can I use headings to make text bigger?

You can, but you shouldn't. Headings convey document structure, not visual styling. If you want larger text without changing the outline, use bold, italics, or a styled element. Using an <h3> as a "big paragraph" hurts accessibility and SEO.

Wrapping up

Markdown headings are simple — a few hash characters — but using them well is what separates a scannable, accessible document from a wall of text. Stick to ATX syntax, keep exactly one markdown h1, nest levels logically, and let auto-generated anchors do the navigation work. Write your next document in the online editor and watch the outline come together as you type.