Markdown Headings

Headings are the foundation of document structure. Markdown provides simple heading syntax with support for six heading levels.

Basic Syntax

Use # symbols to create headings, where the number of # symbols indicates the heading level:

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

Heading Levels

Heading Level 1 (H1)

Level 1 headings are typically used for document titles or chapter titles:

# Document Title

Heading Level 2 (H2)

Level 2 headings are used for main sections:

## Main Section

Heading Level 3 (H3)

Level 3 headings are used for subsections:

## Subsection

Level 4 to Level 6 Headings

Used for more refined content hierarchy:

#### Level 4 Heading
##### Level 5 Heading
###### Level 6 Heading

Alternative Syntax

Setext Style Headings

Use = and - to create level 1 and level 2 headings:

Level 1 Heading
==========

Level 2 Heading
----------

Note: This method only supports level 1 and level 2 headings.

Heading Best Practices

1. Use Spaces

Add a space between the # symbol and the heading text:

✅ Recommended
# Heading

❌ Not Recommended
#Heading

2. Blank Lines Before and After Headings

Add blank lines before and after headings to improve readability:

This is a paragraph.

## Heading

This is another paragraph.

3. Maintain Hierarchy Structure

Follow the heading hierarchy without skipping levels:

✅ Recommended
# Level 1 Heading
## Level 2 Heading
### Level 3 Heading

❌ Not Recommended
# Level 1 Heading
### Level 3 Heading (skipped level 2)

4. Avoid Using Too Many Levels

Usually 3-4 heading levels are sufficient:

# Main Heading
## Section
### Subsection
#### Details (optional)

5. Keep Headings Concise and Clear

✅ Recommended
## Installation Steps

❌ Not Recommended
## This is a very detailed description of how to install the software

Heading IDs

Some Markdown parsers automatically generate IDs for headings:

## My Heading

Generated HTML:

<h2 id="My Heading">My Heading</h2>

Custom Heading IDs

Some parsers support custom IDs:

## My Heading {#custom-id}

Heading Links

Create Table of Contents

Use heading IDs to create a document table of contents:

## Table of Contents

- [Chapter 1](#Chapter 1)
- [Chapter 2](#Chapter 2)
- [Chapter 3](#Chapter 3)

## Chapter 1

Content...

## Chapter 2

Content...

## Chapter 3

Content...

Link to Heading

Jump to [Installation Steps](#Installation Steps)

## Installation Steps

Detailed steps...

Heading Numbering

Manual Numbering

# 1. Chapter One
## 1.1 Section One
## 1.2 Section Two

# 2. Chapter Two
## 2.1 Section One

Automatic Numbering

Some editors and parsers support automatic numbering:

/* CSS Auto Numbering */
h1 { counter-reset: h2counter; }
h2 { counter-reset: h3counter; }
h2:before {
  content: counter(h2counter) ". ";
  counter-increment: h2counter;
}

Heading Styles

Add Emojis

# 📚 Document Title
## 🚀 Quick Start
## 💡 Tips

Add Icons

## ⚙️ Configuration
## 🔧 Tools
## 📝 Notes

Headings and SEO

In web pages, headings are important for SEO:

Best Practices

1. Use only one H1 per page: As the main heading
2. Use by hierarchy: H1 → H2 → H3
3. Include keywords: But naturally
4. Keep it concise: Within 50-60 characters

# Python Beginner Tutorial: Learn Python from Scratch

## What is Python

## Why Learn Python

## How to Install Python

Headings on Different Platforms

GitHub

GitHub automatically generates anchor links for headings:

## Installation Steps

You can link to this heading using #Installation Steps.

Blog Platforms

Most blog platforms support heading syntax and automatically generate tables of contents.

Documentation Tools

VitePress, Docusaurus and other tools automatically generate sidebar navigation.

Heading Shortcuts

VS Code

• Ctrl/Cmd + Shift + ]: Increase heading level
• Ctrl/Cmd + Shift + [: Decrease heading level

Typora

• Ctrl/Cmd + 1-6: Set heading level directly
• Ctrl/Cmd + 0: Set as paragraph

Obsidian

• Ctrl/Cmd + 1-6: Set heading level

Practical Tips

1. Quickly Generate Table of Contents

Use tools to automatically generate table of contents:

<!-- Auto-generated Table of Contents -->
- [Chapter 1](#Chapter 1)
  - [Section 1](#Section 1)
  - [Section 2](#Section 2)
- [Chapter 2](#Chapter 2)

2. Heading Templates

Create commonly used heading structure templates:

# Project Name

## Introduction

## Installation

## Usage

## API Documentation

## FAQ

## Contributing Guide

## License

3. Use Heading Outline

Use the outline view in your editor for quick navigation:

• VS Code: Ctrl/Cmd + Shift + O
• Typora: Sidebar outline
• Obsidian: Right outline panel

Common Questions

Special Characters in Headings

## `Code` in Headings
## **Bold** in Headings
## [Links](URL) in Headings

Headings Too Long

If a heading is too long, consider:

1. Simplifying the heading text
2. Using a subheading
3. Detailed explanation in the main text

## Installation

Detailed installation instructions...

Duplicate Headings

Avoid using the same heading text, or anchor link conflicts may occur:

✅ Recommended
## Python Installation
## Node.js Installation

❌ Not Recommended
## Installation
## Installation

Heading Checklist

• [ ] Used appropriate heading levels
• [ ] Blank lines before and after headings
• [ ] Space after #
• [ ] No skipping of heading levels
• [ ] Headings are concise and clear
• [ ] Only one H1 per page
• [ ] Headings reflect content

Summary

Headings are the skeleton of Markdown documents. Using headings properly can:

• Improve document readability
• Help readers quickly locate content
• Automatically generate table of contents and navigation
• Improve SEO effectiveness

Next: Learn detailed usage of Markdown Text Formatting.