Headings mark the start of a section and establish its rank in the document hierarchy. Markdown provides six levels, written by prefixing a line with one to six # characters. Renderers map these to the equivalent heading tags in the output, and table-of-contents tools use them to generate navigation automatically.

Syntax

MARKDOWN

# My Heading Level One

## My Heading Level Two

### My Heading Level Three

#### My Heading Level Four

##### My Heading Level Five

###### My Heading Level Six

Output

My Heading Level One

My Heading Level Two

My Heading Level Three

My Heading Level Four

My Heading Level Five

My Heading Level Six

Best Practice

Use one or more # followed by a space, then the heading text, this works with every major Markdown flavour.
Add one blank line after the heading.
There should only be one Heading Level One per document, other levels can exist multiple times per document, this also follows the one <h1> per page convention for web search engine optimisation (SEO) and document clarity

Notes

ATX and Setext Styles

Markdown has two heading syntaxes.

ATX Style

The example below uses the ATX style, which prefixes the line with # characters.

MARKDOWN

# Heading One

## Heading Two

ATX takes its name from Aaron Swartz's own plain-text formatting language, which predated Markdown. The name most likely stood for 'Aaron's Text-to-XHTML'. When Gruber and Swartz created Markdown in 2004, the # heading convention was borrowed directly from ATX.

Setext style

CommonMark also defines a setext style for only the top two levels, using === or --- underlines on the following line:

MARKDOWN

Heading One
===========

Heading Two
-----------

Setext stands for 'Structure Enhanced Text', a plain-text document format created by Ian Feldman in the early 1990s for distributing newsletters over email. It used === and --- underlines to mark headings, a convention Gruber retained in the original Markdown spec.

Markdown Flavour Support

Supported by all major flavours.

Flavour Support Detail

Flavour	Support	Notes
Original Markdown	Yes	ATX and setext both defined in the original spec.
CommonMark	Yes	Requires a space between `#` and heading text; no space is invalid.
GitHub Flavored Markdown	Yes	Inherits CommonMark rules; space after `#` is required.
Pandoc Markdown	Yes	Supports both styles; ATX headings optionally closed with trailing `#` characters.

Practical Examples

Blog post structure: Use headings to divide a long post into readable sections. A food blogger might structure a recipe article like this:

Syntax

MARKDOWN

# Classic Lemon Drizzle Cake

## What You Will Need

## Method

## Tips and Variations

Output

Classic Lemon Drizzle Cake

What You Will Need

Method

Tips and Variations

Personal wiki page: Headings let you build the structure for something like a holiday plan.

Syntax

MARKDOWN

# Lisbon Trip — April 2027

## Getting There

## Where to Stay

## Things to Do

### Day Trips

Output

Lisbon Trip — April 2027

Getting There

Where to Stay

Things to Do

Day Trips

Reading notes: A hobbyist summarising a non-fiction book can use heading levels to mirror the book's own chapters and sections.

Syntax

MARKDOWN

# Notes: The Wim Hof Method

## Part One: The Cold

### Chapter 1 — The Iceman

## Part Two: The Breathing