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

For a standalone document, a single # title is usually a clear starting point. In a publishing system that already supplies the page title, begin the body with ##. Describe the document accurately rather than inserting keywords for their own sake.

# 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 supports two levels (H1 and H2), and its underline can use one or more matching markers. A blank line helps separate a heading from earlier content, but is not required before every Setext 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 Markdown extensions support a custom-ID form, but {#my-id} is not part of core Markdown or GFM:

## Custom Heading {#my-id}

The current MD File Viewer tool preview does not add heading IDs and does not implement that custom-ID form. Check anchors at the publishing destination. The table of contents guide explains the difference between heading syntax and application-generated navigation.

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.

• A clear page title. A single descriptive main heading is a useful convention for a standalone document. The correct body level also depends on headings supplied by the surrounding page.
• 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.

A clear hierarchy helps readers navigate the document; it does not guarantee a search ranking.

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 headings. Some renderers disambiguate repeated names with suffixes; others may create conflicting anchors. Inspect the generated links and give sections distinct names when that improves clarity.

Frequently Asked Questions

How many H1 tags should a Markdown document have?

A single main title is a useful convention for a standalone file. If the publishing system already renders the title, the article body can start with ##. Use a clear hierarchy; Markdown itself does not impose a one-H1 validation rule.

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?

Only when the application adds them. Core Markdown does not require heading IDs, and the MD File Viewer tool preview currently does not generate them. Other applications can add IDs with different slug rules. Test section links at the final destination.

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.