Markdown heading sizes: H1-H6 syntax, hierarchy, and best practices

If you searched for "markdown heading", "markdown headers", "markdown h1", or "markdown heading sizes", you likely need a fast reference and a practical formatting model.

This guide explains heading syntax, hierarchy strategy, and common mistakes for production docs.

Quick answer: how do markdown heading sizes work?

Markdown headings are defined by leading # symbols.

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

More # means lower heading level.

Markdown heading syntax table

Example:

# API Authentication Guide

## Prerequisites

### Generate an API key

### Store secrets safely

## Send your first request

### Inspect response headers

Recommended heading hierarchy

Use headings as an outline, not visual decoration.

Good hierarchy:

• one H1 per page
• H2s for major sections
• H3s for scoped details under H2
• avoid jumping from H2 directly to H5

This improves:

• reader navigation
• table-of-contents generation
• accessibility for assistive technology

Common markdown heading mistakes

1. Multiple H1 titles on one page

Use one H1 as the canonical page title.

2. Using headings for visual size only

If text should look larger but not introduce a new section, use styles, not deeper heading levels.

3. Missing space after hashes

Correct:

## Correct heading

Incorrect:

##Incorrect heading

4. Skipping heading levels without structure

Avoid abrupt jumps unless there is clear structural reason.

Markdown heading examples by use case

README structure

# Project Name

## Installation

## Usage

## Configuration

## Contributing

## License

Tutorial structure

# Build an SMTP sender in Node.js

## What you will build

## Prerequisites

## Step 1: Install dependencies

## Step 2: Configure credentials

## Step 3: Send a test message

## Troubleshooting

## FAQ

API documentation structure

# Inbox API

## Authentication

## Endpoints

### Create inbox

### List inboxes

### Delete inbox

## Error handling

## Rate limits

Heading IDs and linkable anchors

Many markdown renderers auto-generate heading IDs.

Example:

## SMTP troubleshooting

Often becomes anchor:

#smtp-troubleshooting

Use stable, descriptive heading text to avoid brittle links.

Markdown headings and SEO snippets

Heading quality affects how content is interpreted by crawlers and users.

Strong heading patterns:

• explicit problem statement (## Why SMTP auth fails)
• answer-style sections (## Quick answer: ...)
• stepwise labels (## Step 1, ## Step 2)

For technical content, this often improves snippet eligibility and scannability.

Testing markdown output before publishing

Before shipping markdown-heavy pages:

1. Render in your target platform (GitHub, docs site, CMS)
2. Check heading levels in preview
3. Verify TOC or anchor links
4. Confirm no duplicate section names where possible
5. Validate code block formatting

If your docs include email workflows, you can pair markdown docs with real send-receive tests using MailSlurp testing tools. For a broader syntax reference, use the complete Markdown syntax collection before publishing long-form technical docs.

FAQ

Is markdown heading size configurable?

Semantically, heading level is fixed by # count. Visual size can be changed by CSS in your renderer.

Can markdown have multiple H1 headings?

Technically yes, but one H1 per page is the best default for structure and SEO clarity.

Does heading level affect GitHub rendering?

Yes. GitHub renders H1-H6 according to heading level and uses headings for navigation/anchors.

Should I use H4-H6 often?

Usually no. Most docs remain clear with H1-H3.

Final take

Markdown headings are simple syntax with high leverage. A clean hierarchy makes your docs easier to read, easier to maintain, and easier to rank.

Convert heading quality into release quality

Good markdown structure reduces ambiguity. Ambiguity is where broken flows usually start.

Use this handoff model when your docs describe email or notification behavior:

If your docs include send/receive examples, run them against Email Sandbox and keep implementation references aligned with your Email API path. That keeps docs trustworthy and makes onboarding faster for new engineers.