Markdown: Markdown Heading Syntax and Hierarchy Guidelines

Headings are the skeleton of your document — they tell both readers and search engines how your content is organized.

1. What You'll Learn

• Both Markdown heading syntaxes: ATX and Setext
• How to use the six heading levels correctly
• Heading hierarchy rules and best practices
• Common heading mistakes and how to fix them
• How headings affect SEO and accessibility

2. A Document Maintainer's Real Story

(1) Pain Point: Chaotic Heading Hierarchy

Sarah took over a technical blog project and found that past articles used headings haphazardly — some used #, some used ##, some had no headings at all, and others jumped from H1 straight to H3, skipping H2 entirely. As a result, the site's table of contents generator was completely broken, and readers complained they couldn't find content.

(2) Solution: Standardized Heading Rules

Sarah established heading rules: each article has only one # heading, and headings must progress step by step (## → ### → ####) without skipping levels. She used a script to fix all 50 articles in bulk. After the fix, the auto-generated table of contents worked again, and reader time-on-page increased by 40%.

3. Two Heading Syntaxes

Markdown provides two heading syntaxes:

graph TB
    A[Markdown Headings] --> B[ATX Style]
    A --> C[Setext Style]
    B --> D[# through ######]
    B --> E[Most common]
    C --> F[=== and ---]
    C --> G[H1 and H2 only]

graph TB
    A[Markdown Headings] --> B[ATX Style]
    A --> C[Setext Style]
    B --> D[# through ######]
    B --> E[Most common]
    C --> F[=== and ---]
    C --> G[H1 and H2 only]

(1) ATX Style (Recommended)

ATX style uses the number of # symbols to indicate heading level — one # for H1, two ## for H2, and so on:

# Heading Level 1 (H1)
## Heading Level 2 (H2)
### Heading Level 3 (H3)
#### Heading Level 4 (H4)
##### Heading Level 5 (H5)
###### Heading Level 6 (H6)

(2) Setext Style

Setext style places === or --- under the heading text:

Heading Level 1
=======

Heading Level 2
-------

▶ Example: Comparing the Two Heading Styles

# ATX Style H1
ATX Style H2
============

Note: the line with === underneath renders as an H1, even though the text says "H2".

4. Heading Hierarchy Guidelines

(1) Using Hierarchy Correctly

Document headings should have a clear hierarchy, like the table of contents of a book:

# Document Title (only one H1)
## Chapter 1 (H2)
### 1.1 Section (H3)
#### 1.1.1 Subsection (H4)
### 1.2 Section (H3)
## Chapter 2 (H2)

(2) Impact on SEO and Accessibility

Heading hierarchy matters a lot for SEO and screen readers:

▶ Example: Correct vs. Incorrect Heading Hierarchy

✅ Correct:
# CSS Layout Tutorial
## Flexbox
### Flex Container Properties
### Flex Item Properties
## Grid
### Grid Container Properties

❌ Incorrect:
# CSS Layout Tutorial
### Flex Container Properties (skipped H2)
## Flexbox
#### Flexbox Properties in Depth (H3→H4 awkward jump)
## Grid

5. Formatting and Special Characters in Headings

(1) You Can Use Bold, Italic, and Code in Headings

## Installing Dependencies With `npm install`
## Understanding **flex-grow**, **flex-shrink**, and **flex-basis**
## What Is *Responsive Design*?

(2) Avoid Overly Long Heading Content

❌ Avoid:
## A Detailed Tutorial on How to Use Python's requests Library to Send HTTP Requests

✅ Recommended:
## Sending HTTP Requests With the requests Library

▶ Example: Before and After Heading Optimization

❌ Too long:
## This Article Will Teach You How to Set Up a Python Development Environment in VS Code on Windows

✅ Optimized:
## Setting Up Python in VS Code

6. Full Example: Heading Structure of an Article

# Data Analysis With Python

## 1. Data Preparation
### (1) Importing Libraries
### (2) Reading Data
### ▶ Example: Reading a CSV File

## 2. Data Cleaning
### (1) Handling Missing Values
### ▶ Example: Filling Null Values
### (2) Removing Duplicates

## 3. Data Visualization
### (1) Line Charts
### ▶ Example: Plotting a Trend Chart
### (2) Bar Charts

Expected result: A clearly layered document structure that both readers and search engines can quickly understand.

❓ FAQ

📖 Summary

• Two heading syntaxes: ATX (#) and Setext (===); recommend using ATX throughout
• Always put a space after #, or it won't be recognized as a heading
• One H1 per page, progress step by step without skipping levels
• Keep headings short (H1 ≤ 60 chars); avoid keyword stuffing
• Headings can include code, bold, italic, and other formatting
• A good heading hierarchy serves both readers and search engines

📝 Exercises

1. Beginner: Write a short Markdown piece with H1, H2, and H3 headings (choose the topic yourself — a reading note or study plan). Make sure each heading level has exactly one more # than the level above it.

2. Intermediate: Open a document you recently wrote and check if its heading hierarchy follows the rules. If there are level skips or messes, fix them. Then count how many H1s you have (the correct answer is 1).

3. Challenge: Use the Markdown All in One extension in VS Code to generate a table of contents (type [TOC] or use the command) and verify your heading hierarchy is correct. If the generated TOC looks off, your heading levels need adjusting.

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

About Us