#) followed by a space and your heading text. One hash is H1, two hashes is H2, up to six hashes for H6.
The Six Heading Levels
Markdown supports all six HTML heading levels:
# Heading 1 — the page title, largest text (use once per document)
## Heading 2 — major sections
### Heading 3 — sub-sections within H2
#### Heading 4 — sub-sub-sections (use sparingly)
##### Heading 5 — rarely needed
###### Heading 6 — the smallest heading level (almost never needed)
The number of # symbols maps directly to the HTML heading level. Six hashes create an element.
The Space After # is Required
This is the most common mistake beginners make:
#Heading — wrong: no space between # and text, will NOT render as a heading
# Heading — correct: space is required
The CommonMark specification mandates a space (or up to three leading spaces before the #). Without the space, the line renders as plain text with a literal hash character.
Alternative Setext Syntax (H1 and H2 Only)
An older syntax — called Setext-style — creates H1 and H2 by underlining:
My Page Title
=============
A Section Heading
------------------
The equals signs create H1; hyphens create H2. The underline must have at least one character; it doesn't need to match the heading length exactly.
Setext style is rarely used today. The hash syntax is preferred because:
- It supports all six levels (Setext only does H1 and H2)
- It's immediately clear what level you're at without counting characters
- It's consistent with every markdown tutorial and guide
Heading Anchors for Internal Links
Every heading automatically receives an anchor ID. You can link to it from anywhere in the document:
[Go to Installation](#installation)
The anchor ID is derived from the heading text:
- Lowercased:
## Getting Started→#getting-started - Spaces become hyphens:
## My Section→#my-section - Special characters removed:
## API (v2)→#api-v2 - Numbers are kept:
## Step 1→#step-1
Platform-by-Platform Breakdown
GitHub and GitLab
Full support for all six heading levels. GitHub also generates anchor links for every heading and shows a floating table of contents in the left panel for long README files. The space after # is strictly required.
Obsidian
All six heading levels supported. Obsidian's outline panel lists all headings in a sidebar, making navigation easy in long notes. H1 headings can be used as note titles.
Notion
Notion supports H1, H2, and H3 in its markdown import — H4 through H6 are downgraded to H3. In the Notion editor, use /heading1, /heading2, /heading3 commands.
Discord
Discord does not support markdown headings. Lines starting with # render as a large bold line in newer Discord clients (2023+ update), but this is a special Discord feature, not standard heading markup.
Slack
Slack does not render markdown headings. Hash symbols display as plain text.
Common Mistakes and How to Fix Them
Missing Space After Hash
#Introduction → renders as plain text #Introduction
# Introduction → renders as an H1 heading
Skipping Heading Levels
Going from H2 directly to H4 violates document structure conventions, harms screen reader navigation, and hurts SEO:
Bad structure:
## Section
#### Sub-section ← skipped H3
Good structure:
## Section
### Sub-section ← correct progression
Using Multiple H1s
A document should have exactly one H1 (the main title). Multiple H1 headings confuse search engines about the document's primary topic and signal poor document structure to screen readers.
Inline Formatting Inside Headings
Bold and italic work inside headings (## Important Section), but use them sparingly. Headings are already visually prominent; adding bold inside a heading is usually redundant.
Headings and SEO
When you export markdown to HTML or PDF using MarkdownTools, headings map directly to HTML heading elements ( through ). This matters for:
- Search engine indexing — search engines use heading hierarchy to understand document structure
- Accessibility — screen readers use headings to let users navigate documents without reading every line
- Table of contents generation — tools like the TOC Generator rely on proper heading hierarchy
Real-World Use Cases
Technical Documentation
A typical README structure uses H1 for the project name, H2 for Installation, Usage, Configuration, and Contributing sections, and H3 for sub-topics within each.
Meeting Notes
Meeting notes often use H1 for the meeting title + date, H2 for each agenda item, and H3 for sub-discussions or decisions within each agenda item.
AI-Generated Reports
When exporting ChatGPT or Claude output as a PDF via MarkdownTools, heading levels determine the visual hierarchy of the rendered document. A well-structured H1/H2/H3 hierarchy creates a document that looks like a professional report rather than a wall of text.
Full reference: Markdown Headings.
Ready to put this into practice? Paste your markdown into the free MarkdownTools PDF exporter or HTML converter — no signup required.