Markdown headings define the structure of a document. Instead of changing font size or applying styles, you create headings by adding one or more # characters before your text.

Syntax#

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

Live Preview#

Each additional # creates a lower heading level, allowing you to organize content into sections and subsections that are easy to follow.

Most Markdown applications—including GitHub, GitLab, VS Code, Obsidian, and many static site generators—recognize this syntax and render it as HTML headings (<h1> through <h6>).

If you're new to Markdown, start with Markdown Basics before learning document structure.

Markdown supports six heading levels. Each level has a specific role in creating a logical document outline.

Think of headings as an outline rather than styling. Each level should naturally fit beneath the level above it. For most README files and documentation pages, H1 through H3 are enough; H4–H6 are typically only needed in large technical documents.

A typical documentation page follows a structure like this:

# Project Documentation

## Installation

### Windows

### macOS

## Configuration

### Environment Variables

## FAQ

This hierarchy improves readability, makes large documents easier to navigate, and helps automatically generated Tables of Contents (TOCs) reflect the structure of your content.

Headings do more than create larger text—they define the organization of your document.

A clear hierarchy helps:

• Readers quickly scan long pages.
• Documentation tools generate accurate Tables of Contents.
• Screen readers understand the relationship between sections.
• Teams maintain consistent documentation across projects.

Avoid choosing heading levels based only on appearance. An H3 isn't simply a smaller H2; it represents a subsection that belongs under an H2.

Markdown supports two ways to create headings: ATX headings (using #) and Setext headings (using underline characters).

While both are valid, modern Markdown editors and documentation projects almost always use the ATX style because it supports all six heading levels and is easier to maintain. Learn every formatting rule in the Markdown Syntax reference.

ATX Headings#

Syntax#

# Project Title

## Installation

### Configuration

Live Preview#

This is the standard style you'll find in GitHub repositories, documentation websites, knowledge bases, and Markdown editors.

Setext Headings#

Project Title
=============

Installation
------------

= creates an H1 heading, while - creates an H2 heading.

Because Setext only supports two heading levels, it isn't suitable for larger documents with multiple nested sections.

Recommendation: Use ATX headings for new Markdown documents unless you're maintaining older content that already uses the Setext style.

Good Markdown documents are organized like an outline. Each heading level should naturally belong to the level above it.

# User Guide

## Getting Started

### Installation

### Configuration

## Features

### Authentication

### API Access

## Troubleshooting

Each H2 introduces a major topic, while H3 headings divide that topic into smaller sections.

This structure keeps documentation easy to navigate and helps readers understand how different sections relate to one another.

Heading levels define document structure, not visual size.

Choose H2 or H3 because they fit the document hierarchy—not because they appear larger or smaller on screen. If you only want different text styling, use CSS or your publishing platform's theme settings instead of changing heading levels.

This is one of the most common beginner mistakes: picking #### because it "looks right" instead of because the content is a fourth-level subsection under an H3.

If your document regularly reaches H5 or H6 headings, consider splitting it into multiple pages instead of creating deeply nested sections.

Large documentation projects are usually easier to navigate when related topics are organized into separate pages connected through internal links. For example, split a monolithic API guide into separate pages for Authentication, Endpoints, and Error Codes—each with its own H1 and a clear H2 outline.

Use the Documentation Index to link related guides, and preview how your outline reads in the Markdown Editor before publishing.

A typical project README often follows a structure like this:

# My Project

## Features

## Installation

## Quick Start

## Configuration

## Usage

## Contributing

## License

A longer documentation guide might include another level:

# API Documentation

## Authentication

### API Keys

### OAuth

## Endpoints

### Users

### Projects

### Billing

Both examples are easy to scan because each heading level follows a consistent hierarchy.

Need a complete Markdown overview? See the Markdown Syntax reference for all supported elements, or continue with Markdown Paragraphs to learn how headings and paragraphs work together in well-structured documents.

Many Markdown platforms automatically create anchor links for headings. These links let readers jump directly to a specific section instead of scrolling through the entire document.

For example, this heading:

## Installation Guide

may generate an anchor like:

#installation-guide

You can then link directly to that section:

[Go to Installation](#installation-guide)

This is commonly used in README files, long documentation pages, and automatically generated Tables of Contents.

Note: Anchor generation isn't part of the original Markdown specification. GitHub-specific behavior is covered in GitHub Flavored Markdown (GFM).

GitHub automatically creates an ID for every heading when rendering Markdown.

In most cases GitHub:

• Converts text to lowercase.
• Replaces spaces with hyphens (-).
• Removes most punctuation.
• Adds numeric suffixes if multiple headings have the same name.

If the same heading appears more than once, GitHub automatically creates unique anchors:

#installation
#installation-1
#installation-2

This prevents duplicate IDs within the same document.

Related: Learn more about GitHub-specific behavior in the GitHub Flavored Markdown (GFM) guide.

Most modern Markdown parsers allow inline formatting inside headings.

Links

## [API Documentation](https://example.com)

Inline Code

## Installing `npm`

Emojis

## 🚀 Getting Started

These elements are widely supported by GitHub, GitLab, Obsidian, and many documentation tools.

However, avoid adding excessive formatting inside headings, as it can make large documents harder to scan.

A well-structured heading hierarchy allows many tools to generate a Table of Contents (TOC) automatically.

# User Guide

## Installation

## Configuration

### Environment Variables

## Troubleshooting

can produce a navigation menu similar to:

User Guide
  • Installation
  • Configuration
    • Environment Variables
  • Troubleshooting

Many documentation platforms, static site generators, and Markdown editors build navigation directly from heading levels, making consistent hierarchy more important than visual appearance.

If you're creating large documentation projects, keep heading levels consistent so your TOC remains clean and easy to navigate.

Generate navigation automatically with the Markdown TOC Generator.

Heading anchors are useful for more than external links.

They can also help you:

• Link to a specific section from another part of the same document.
• Share direct links to troubleshooting steps or API endpoints.
• Create documentation that readers can navigate quickly.
• Build cross-references between related guides.

For long technical documents, using heading anchors can significantly improve navigation without adding extra menus or duplicate content.

The basic heading syntax works consistently across most Markdown applications, but some platforms add features that improve navigation and document organization.

Although the syntax remains the same, navigation features such as heading anchors, outlines, folding, and automatic Tables of Contents depend on the application you're using.

Related: Learn more about platform differences in the GitHub Flavored Markdown (GFM) guide.

Headings don't just make documents look organized—they also provide structure that browsers, search engines, and assistive technologies rely on.

A logical heading hierarchy helps:

• Screen readers navigate documents efficiently.
• Readers scan long pages more quickly.
• Documentation tools generate accurate outlines.
• Search engines better understand page structure.

# User Guide

## Installation

### Windows

### macOS

## Configuration

### Environment Variables

## Troubleshooting

Each heading level builds on the one above it. Jumping between unrelated levels can make documents harder to understand, especially in long technical guides.

Well-written headings make documentation easier to maintain as projects grow.

Follow these recommendations:

• Use a single H1 for the document title.
• Keep headings concise and descriptive.
• Follow a logical H1 → H2 → H3 hierarchy.
• Leave one space after each #.
• Use sentence case or title case consistently throughout the document.
• Choose heading levels based on structure—not visual size.
• Keep similar sections at the same heading level.

Read Markdown Best Practices for writing consistent documentation across projects. Test your heading hierarchy in the Markdown Editor before publishing.

✅ Good

# User Guide

## Installation

## Configuration

## Troubleshooting

❌ Less effective

# User Guide

#### Installation

## Configuration

##### Troubleshooting

The second example creates an inconsistent outline that's harder for both readers and documentation tools to interpret.

Most heading issues are caused by small formatting errors rather than incorrect Markdown syntax.

If headings don't render correctly, check for missing spaces, inconsistent formatting, or unsupported Markdown features in your editor.

As documentation grows, consistent heading structure becomes more important than the headings themselves.

A few habits can make large projects easier to maintain:

• Use the same heading style across every document.
• Keep section names consistent between related guides.
• Avoid changing heading text unless necessary, as it may affect existing anchor links.
• Review the generated Table of Contents before publishing long documentation.
• Break very large sections into smaller H2 and H3 topics instead of creating long scrolling pages.

These small practices make documentation easier to navigate, maintain, and update over time.

For broader documentation standards, see Markdown Best Practices and the Markdown Style Guide. Preview your heading hierarchy in the Markdown Editor before publishing.