Back to blog
·

Markdown Heading Levels Guide: H1-H6 Explained

Markdown heading levels guide: Learn H1-H6, structure, accessibility, SEO, and best practices for GitHub, README files, and docs—read more.

Introduction

Markdown headings give your document a clear heading hierarchy from H1 to H6. In Markdown, that hierarchy does more than change text size. It creates semantic structure that helps readers, screen readers, and search engines understand how the content is organized.

That matters for readability, accessibility, and SEO. Well-placed headings help people scan a page, understand the relationship between sections, and find information faster. They also help tools interpret the document correctly, whether you’re writing in CommonMark, GitHub Flavored Markdown, or another Markdown parser.

This guide explains what Markdown heading levels are, how to write H1 through H6, when to skip levels, how headings work in GitHub and GitLab, and how to use them in a README or longer documentation project. You’ll also see common mistakes, accessibility considerations, and how headings support a table of contents and anchor links.

If you’re new to Markdown, start with Markdown basics for beginners and plain text formatting with Markdown. If you want a broader writing workflow, see Markdown writing tips and Markdown style guide examples.

What Are Markdown Heading Levels?

Markdown heading levels are section titles that organize content from broad to specific. In a typical heading hierarchy, H1 is the main title, H2 marks major sections, H3 introduces subsections, and H4, H5, and H6 add deeper layers of detail. The CommonMark spec defines six heading levels, and most Markdown tools follow that standard.

Heading levels are part of the document’s semantic structure, not just its appearance. A Markdown heading tells a Markdown editor or Markdown parser how sections relate to one another, which is why headings matter in technical writing, documentation, and static site generators.

How Do You Write H1 to H6 in Markdown?

Markdown headings use hash marks at the start of a line:

# H1
## H2
### H3
#### H4
##### H5
###### H6

The number of hashes determines the level. One hash creates H1, two hashes create H2, and so on through H6.

What Is the Correct Syntax for Markdown Headings?

The standard syntax is a hash mark followed by a space, then the heading text:

# Heading
## Heading
### Heading

In CommonMark and GitHub Flavored Markdown, the space after the hash is required for normal heading parsing. #Heading is not treated as a proper heading in standard Markdown. Some tools may be forgiving, but the safest rule is to always include the space.

A few parsers also support closing hashes, like ## Heading ##, but those trailing hashes are optional and should not replace the required leading syntax.

How Many Heading Levels Are There in Markdown?

Standard Markdown supports six heading levels: H1 through H6. That is the maximum heading depth in CommonMark and GitHub Flavored Markdown.

What Is the Difference Between H1, H2, and H3 in Markdown?

Use H1 for the document title or main page topic. Use H2 for the page’s primary sections. Use H3 for subsections under each H2.

For example:

  • H1: the article or README title
  • H2: major topics such as Installation or Usage
  • H3: steps, examples, or subtopics inside those sections

This structure helps readers understand the heading hierarchy and helps assistive technologies interpret the page correctly.

Can You Use Multiple H1 Headings in One Markdown Document?

Usually, you should not. In most Markdown documents, one H1 is best because it clearly identifies the main topic and keeps the structure predictable for accessibility and SEO.

Some platforms may allow multiple H1 headings, but that pattern can make a document harder to scan and can weaken the overall semantic structure. For a blog post, use one H1 for the title and reserve H2 through H6 for the rest of the content.

Is It Okay to Skip Heading Levels in Markdown?

Technically, yes. Practically, it is better to avoid skipping levels unless the structure truly requires it.

For example, jumping from H2 to H4 can make the document harder to follow because it suggests a missing layer of content. That can confuse readers, screen readers, and anyone navigating by headings. If you need a deeper subsection, use H3 first, then H4 if the content really needs it.

How Do Markdown Headings Help SEO?

Headings help SEO by making content easier to understand, scan, and index. Search engines use headings as signals about page structure and topic relationships, so clear headings can support relevance and readability.

Use headings to describe the section accurately, not to repeat the same phrase over and over. For example, ## Markdown Heading Syntax is useful, while a heading stuffed with repeated keywords is not.

Headings can also improve the chance that a section is used in a featured snippet when it directly answers a question. That works best when the heading matches the user’s intent and the paragraph below it gives a direct answer.

Why Are Heading Levels Important for Accessibility?

Heading levels help screen readers and other assistive technologies move through a page efficiently. Many users navigate by heading order, so a logical hierarchy makes the content easier to understand.

A clean structure also helps people who use keyboard navigation or other accessibility tools. If headings are skipped or used out of order, the page becomes harder to navigate and the semantic structure becomes less clear.

How Do Headings Work in GitHub Markdown?

In GitHub Flavored Markdown, headings render as section titles and usually become anchor links automatically. That means a heading like ## Install the CLI can be linked directly from another part of the page.

GitHub uses this behavior in README files, issues, pull requests, and documentation pages. GitLab supports similar heading behavior, and many static site generators can build navigation from the same heading structure.

What Is the Best Heading Structure for a README File?

A strong README usually starts with one H1 for the project name, followed by H2 sections for the most important information:

  • Overview
  • Installation
  • Usage
  • Configuration
  • Contributing
  • License

Use H3 headings for examples, setup steps, or troubleshooting inside those sections. This structure keeps the file easy to scan in GitHub and GitLab, and it works well for technical writing and project documentation.

How Do You Create a Table of Contents from Markdown Headings?

A table of contents is usually built from your heading hierarchy. Many documentation tools, static site generators, and Markdown editors can generate one automatically from #-style headings.

To make TOC generation work well:

  1. Use one H1 for the page title.
  2. Keep headings in logical order.
  3. Write descriptive section titles.
  4. Avoid skipping levels unless necessary.

That structure makes it easier for tools to create anchor links and for readers to jump to the section they need.

What Are Common Markdown Heading Mistakes?

Common mistakes include:

  • Writing ###Heading without a space after the hashes
  • Using headings only to change font size
  • Skipping levels without a structural reason
  • Making headings too long or vague
  • Repeating the same keyword in every heading
  • Using multiple H1 headings when one would be clearer

A good Markdown editor can help catch some of these issues, but the best check is to review the document’s structure manually.

Quick Reference

  • # = H1
  • ## = H2
  • ### = H3
  • #### = H4
  • ##### = H5
  • ###### = H6

Standard Markdown supports six heading levels, and the correct syntax is a hash mark followed by a space.

Frequently Asked Questions

What is the maximum heading level supported by Markdown?
Markdown supports H6 as the deepest heading level.

Do you need a space after the hash in Markdown headings?
Yes. In CommonMark and GitHub Flavored Markdown, the space after the hash is required for standard heading syntax.

Can you use multiple H1 headings in one Markdown document?
Usually, no. One H1 is the clearest choice for most documents.

Is it okay to skip heading levels in Markdown?
Yes, but only when the structure truly calls for it. In most cases, keep the levels in order.

How do Markdown headings help SEO?
They clarify structure, improve readability, and help search engines understand the page.

Why are heading levels important for accessibility?
They help screen readers and other assistive technologies navigate the document in a logical order.

How do headings work in GitHub Markdown?
GitHub Flavored Markdown renders headings as section titles and often creates anchor links automatically.

What is the difference between H1, H2, and H3 in Markdown?
H1 is the main title, H2 is for major sections, and H3 is for subsections.

Related Guides