Markdown Headings Guide: H1 to H6, Best Practices, and SEO

Headings are the backbone of any Markdown document. They define structure, enable navigation, affect accessibility, and influence SEO. This guide covers everything about Markdown headings — syntax, hierarchy rules, platform differences, and best practices.

Heading Syntax

Markdown headings use the # symbol (ATX-style). The number of # characters determines the heading level:

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

There’s also the Setext style (only H1 and H2):

Heading 1
=========

Heading 2
---------

ATX-style (#) is preferred — it’s more explicit and works for all six levels.

What Each Heading Level Means

Most documents use only H1–H3. H4–H6 usually indicate the document structure is too deep.

H1: One Per Page

An H1 heading should appear exactly once per Markdown document. It represents the document’s title or the main topic of the page.

Good:

# How to Convert Word to Markdown

Avoid:

# Section One
...
# Section Two  ← Don't use multiple H1s

Search engines and accessibility tools expect a single H1 per page. Multiple H1s confuse both.

Heading Hierarchy Rules

Always progress headings in sequence. Don’t skip levels:

Correct:

# Document Title
## Section
### Subsection
#### Detail

Incorrect:

# Document Title
#### Jumped to H4  ← Skips H2 and H3

Skipping heading levels breaks the document outline and fails WCAG accessibility guidelines.

Converting Word Headings to Markdown

When you convert a Word document with WordToMD, Word’s built-in heading styles map directly:

The most common issue: writers manually bold and increase font size instead of applying the Heading style. This creates text that looks like a heading in Word but converts to plain bold text in Markdown. See Word to Markdown Formatting Guide for how to fix this.

Heading IDs and Anchor Links

Most Markdown processors automatically generate IDs from heading text:

## Getting Started

Generates: <h2 id="getting-started">Getting Started</h2>

You can link to it:

See the [Getting Started section](#getting-started).

Rules for auto-generated IDs:

• Lowercase all characters
• Replace spaces with hyphens
• Strip special characters except hyphens

Examples:

• ## API Reference → #api-reference
• ## What's New? → #whats-new
• ## Step 1: Install → #step-1-install

Tables of Contents

For long documents, generate a TOC using heading anchor links:

## Table of Contents
- [Installation](#installation)
- [Configuration](#configuration)
  - [Basic Settings](#basic-settings)
  - [Advanced Options](#advanced-options)
- [Usage](#usage)
- [FAQ](#faq)

GitHub automatically generates a TOC in the top-left corner of any Markdown file with headings.

SEO Considerations

For Markdown used in static sites (Jekyll, Hugo, Astro) and published to the web:

• H1 = page title — Include your primary keyword. One per page.
• H2s = major sections — Include secondary keywords naturally
• H3s = subsections — More specific topics
• Keep headings descriptive — “How to Install Dependencies” beats “Installation”
• Headings are indexed by search engines — make them scannable

See Word to Static Site Generator for publishing Markdown documents to the web.

Accessibility

Screen readers use heading hierarchy to help users navigate. Guidelines:

• Don’t skip heading levels (H1 → H3 without H2)
• Don’t use headings just for visual formatting (use bold or CSS instead)
• Make heading text meaningful — avoid “Section 1”, “Part A”
• Keep headings concise but descriptive

Heading Rendering by Platform

Notion only supports three heading levels (called Heading 1, 2, and 3 in their editor, mapping to H1–H3).

Common Mistakes

Forgetting the space after #

#Not a heading    ← Missing space
# This is correct

The space between # and the heading text is required in CommonMark.

Using headings for styling, not structure Using ### to make text slightly smaller without it being an actual subsection breaks document structure. Use styled text or CSS classes instead.

Over-nesting If you need H5 and H6, consider whether the content should be split into separate pages.

FAQ

What’s the difference between ATX and Setext heading styles? ATX uses # characters. Setext uses underlines (=== for H1, --- for H2). ATX is preferred because it’s unambiguous and works for H1–H6.

Can I have multiple H2s? Yes — that’s the whole point. H2 defines major sections, and a document typically has several.

Will skipping heading levels affect SEO? It affects accessibility more than SEO directly, but a clean semantic structure is a positive signal. Search engines prefer well-structured content.

My converted document has all headings at the same level. What went wrong? The Word document used manual formatting instead of Heading styles. See Word to Markdown Formatting Guide for the fix.

Conclusion

Markdown headings are simple in syntax but important in impact. Use H1 once as the document title, H2 for major sections, and H3 for subsections. Keep the hierarchy clean, skip no levels, and write descriptive heading text. When converting Word documents with WordToMD, ensure the source uses Word’s built-in Heading styles for clean conversion.