A Markdown heading is created by prefixing text with one or more # characters — no font-size changes, no styling tags. Parsers convert # through ###### directly into HTML <h1>–<h6>.

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

Live Preview#

Two compatibility rules most guides skip:

• Always leave one space after the #. Some parsers silently ignore ##Heading with no space — it just prints as plain text.
• Leave a blank line before and after every heading. Most modern parsers tolerate missing blank lines, but stricter processors — and some Jekyll/Hugo setups — will merge the heading into the paragraph above it if you skip this.

Some paragraph text.

## Correct: blank line above and below

More paragraph text.

If you're brand new to Markdown, start with Markdown Basics first.

Most README files and blog posts never need past H3. If you're reaching for H5/H6 regularly, that's usually a signal to split the document (see When to Split Large Documents), not to keep nesting.

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

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

= produces an H1, - produces an H2. Because Setext caps out at two levels, it can't represent real document hierarchy — treat it as legacy syntax, not a style choice.

Treat headings as an outline, not a font-size picker — pick a level because of where the content sits in the document, never because a heading "looks right" on screen. If you want different visual styling without changing structure, that's a CSS/theme decision, not a heading-level decision.

# User Guide
## Getting Started
### Installation
### Configuration
## Features
### Authentication
### API Access
## Troubleshooting

Each H2 is a major topic; each H3 splits it further. Skipping levels (H2 straight to H4) is the most common hierarchy mistake — see Common Heading Mistakes.

If a document regularly reaches H5 or H6, it's usually doing too much in one page. Split it into linked pages instead — e.g., one monolithic API guide becomes separate pages for Authentication, Endpoints, and Error Codes, each with its own H1 and a shallow H2/H3 outline.

Preview your outline in the live editor before publishing, and link related pages through a Documentation Index.

A project README:

# My Project
## Features
## Installation
## Quick Start
## Configuration
## Usage
## Contributing
## License

A technical API reference (deeper nesting, justified by content volume):

# API Documentation
## Authentication
### API Keys
### OAuth
## Endpoints
### Users
### Projects
### Billing

A blog post converted to HTML (SEO-driven structure — see next section):

# 10 Ways to Speed Up Your Website
## 1. Optimize Images
## 2. Enable Caching
## 3. Minify CSS and JavaScript

Notice the pattern: H1 count never exceeds one, and H2 count matches the number of real, distinct sections a reader would look for — not the number of paragraphs.

When Markdown compiles to HTML — for a blog, docs site, or CMS — headings stop being just visual structure and become on-page signals search engines use to parse the page.

• Use exactly one H1 per page, matching the primary topic. HTML5's sectioning model technically permits multiple H1s, and some component-based frameworks generate them by accident — but a single H1 remains the strongest, most consistently supported signal for search visibility.
• Write H2s in the language people actually search — "How to Add a Table of Contents" ranks better than a vague "More Info."
• Don't repeat near-identical headings across a page purely for keywords; it reads as duplication to both readers and crawlers.
• Keep the hierarchy unbroken — search engines pull heading structure into featured snippets, so a broken H1→H4 jump can mean your best content gets skipped for one.

Most platforms auto-generate a clickable anchor for every heading, letting readers jump straight to a section — this is platform behavior, not part of the original Markdown spec.

How auto-anchors work:

## Installation Guide

That generates an anchor like #installation-guide, which you link to as:

[Go to Installation](#installation-guide)

GitHub's specific algorithm — GitHub builds the anchor ID by: lowercasing the text, replacing spaces with hyphens, stripping most punctuation, and appending -1, -2, etc. if the same heading repeats.

Overriding the anchor with a custom ID — the one thing most guides don't cover. If you rename a heading later, the auto-generated anchor changes and every external link to the old one breaks. Setting a custom ID keeps the anchor stable even when the visible text changes:

Rule of thumb: if you're publishing on a platform that supports custom IDs, set one for any heading likely to be renamed or linked from outside the page.

Syntax is universal; auto-TOC generation is not:

If you're publishing docs on a static site generator, verify your specific theme's anchor and TOC behavior before hardcoding #anchor links — Hugo in particular varies by theme.

Most parsers allow links, inline code, and emoji inside headings:

## [API Documentation](https://example.com)
## Installing `npm`
## 🚀 Getting Started

Widely supported on GitHub, GitLab, and Obsidian — but avoid stacking multiple formatted elements in one heading, since it hurts scannability and can break some auto-generated TOC renderers.

Separate from this site's own page navigation — this is about the TOC generated inside your own Markdown document when it's rendered. A consistent hierarchy is what makes that possible:

# User Guide
## Installation
## Configuration
### Environment Variables
## Troubleshooting

That produces a nav tree that mirrors the outline exactly. Generate one automatically with the Markdown TOC Generator.

Screen readers jump directly from one heading to the next by level — so a broken hierarchy (H2 straight to H4) isn't just a visual inconsistency, it's a navigation dead-end for assistive tech users. Keep every level sequential and reserve H1 for the single page title.

For general Markdown formatting slips beyond headings, see Common Markdown Mistakes.

• Follow H1 → H2 → H3 in sequence — never skip a level
• One space after every #, blank line before and after each heading
• Set a custom anchor ID ({#id}) if the heading text may change later
• Keep heading text under ~60 characters where possible