Markdown Headers and Titles: H1-H6 Syntax and Examples

A Markdown header starts with one to six # characters followed by a space: # Page title, ## Section and ### Subsection. The number selects the heading level; the app displaying the document controls its font size.

This is useful for README files, notes and documentation. If your title appears as plain text or your section link goes to the wrong place, the examples below help you find the cause.

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

Markdown	Rendered HTML	Typical use
# Title	<h1>	page title
## Section	<h2>	primary section
### Subsection	<h3>	nested section
#### Detail	<h4>	optional deep nesting
##### Note	<h5>	rare support heading
###### Meta	<h6>	rare technical label

Example:

# API Authentication Guide

## Prerequisites

### Generate an API key

### Store secrets safely

## Send your first request

### Inspect response headers

How to write a Markdown title

For a standalone document, put # My document title on its own line near the start. That becomes an H1 heading. It does not automatically set a browser tab's title or rename the file.

A documentation site may already render a title from its page metadata. In that case, start the article body at H2 so the title is not printed twice. Fields such as title: inside YAML frontmatter belong to the site's publishing system, not to core Markdown syntax.

Underline-style H1 and H2 headings

Markdown also supports Setext headings:

My document title
=================

A section heading
-----------------

An equals-sign underline creates H1; a hyphen underline creates H2. There are no underline forms for H3-H6. Use ### and more hashes for those levels. Keep the underline directly below the heading text. The CommonMark heading specification documents both forms.

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

On GitHub, copy a heading's link from the rendered page rather than guessing the punctuation rules. For repeated headings, the later anchors receive suffixes such as -1. Renaming a heading can break existing links; GitHub documents its section-link rules. Other renderers can generate different IDs.

Why a Markdown header is not rendering

• The hashes are visible: add a space after them. ##Section is ordinary text in CommonMark.
• The whole heading looks like code: move it outside the fenced code block. Four leading spaces can also create an indented code block.
• A bold line is missing from the outline: **Section** makes bold text, not an H2. Use ## Section.
• Every heading looks the same size: inspect the rendered HTML. If it contains H1-H6, the theme's CSS is controlling their appearance.
• A section link goes to the wrong heading: check for duplicate names. GitHub adds a numeric suffix to repeated anchors.

You do not need an extra Markdown plugin for ordinary headings. Preview the file in the application that will publish it before changing the syntax to work around a theme issue.

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 a useful default for a clear document outline.

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.

Check the rendered document

Open the preview, follow one section link and read the outline from top to bottom. The outline should describe the document without needing its body text. If a section only needs emphasis within a paragraph, bold text is usually enough.

For the rest of the syntax, see the Markdown reference. When your document describes an email integration, keep its examples runnable against MailSlurp test inboxes so readers can confirm the same result.