How to Create Headings in Markdown
Create headings in Markdown by starting a line with 1-6 hash symbols followed by a space: # for an H1 down to ###### for an H6. The space after the hashes is required by CommonMark — #Heading without it will not render as a heading on GitHub.
Platform Support
The hash-based style is called ATX headings, and it is what you should use almost everywhere. Markdown also supports setext headings, where you underline text with equals signs (for H1) or dashes (for H2). Setext only covers two levels, is easy to break accidentally — a stray line of dashes under a paragraph turns it into an H2 — and confuses diff tools because the heading spans two lines. ATX headings are unambiguous, support all six levels, and are the convention in virtually every modern codebase.
Headings define your document outline, so use them hierarchically: one H1 per document (usually the title), H2 for major sections, H3 for subsections. Skipping levels (jumping from H2 to H4) hurts accessibility because screen reader users navigate by heading level, and it breaks automatically generated tables of contents. On GitHub, every heading automatically gets an anchor ID derived from its text (lowercased, spaces to hyphens, punctuation stripped), so ## Getting Started becomes linkable as #getting-started.
Two formatting rules prevent most heading bugs. First, headings need a blank line before and after them in many renderers — text jammed directly against a heading line can merge into one paragraph. Second, the heading must start at the beginning of the line (up to three leading spaces are tolerated; four turns it into an indented code block). Trailing hashes are optional and ignored: ## Title ## renders the same as ## Title.
Avoid using headings purely for visual size. If you want big bold text without adding a section to the document outline, use bold text or platform-specific features instead. Search engines and accessibility tools treat headings as structure, and a document whose outline is a series of decorative H3s is harder to navigate for everyone.
Examples
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Create headings using # symbols. The number of # symbols determines the heading level (1-6).
Heading 1
=========
Heading 2
---------Heading 1
Heading 2
Alternative syntax for H1 and H2 using underlines.
See the [installation section](#installation) below.
## InstallationSee the installation section below.
Installation
GitHub auto-generates anchors from heading text: lowercase, spaces become hyphens.
## Section Title ##Section Title
Trailing hashes are allowed and ignored — purely cosmetic.
Common Mistakes
#Heading without a space# Heading with a spaceCommonMark (and GitHub) require a space between the hashes and the text. Without it, the line renders as plain text.
# Title
### Subsection (skipping H2)# Title
## Section
### SubsectionSkipping heading levels breaks document outline navigation for screen readers and table-of-contents generators.
Some paragraph text
---Some paragraph text
---A line of dashes directly under text creates a setext H2, not a horizontal rule. Add a blank line before --- to get a divider.
Platform Notes
GitHub
All six levels supported, with automatic anchor links and a hover link icon. Heading anchors power README table-of-contents links.
Discord
Supports # H1, ## H2, and ### H3 only (added in 2023). Deeper levels render as plain text with visible hashes.
Slack
No heading support at all. Hashes render literally. Use *bold* lines as pseudo-headings in Slack messages.
Obsidian
All six levels supported. Headings drive the outline pane, folding, and [[Note#Heading]] deep links.
Frequently Asked Questions
How do I make a heading in Markdown?
Start a line with 1-6 hash symbols followed by a space: # Heading 1, ## Heading 2, and so on down to ###### Heading 6.
Why is my heading not rendering?
The usual causes: no space after the hashes (#Title), no blank line before the heading, or the line is indented four or more spaces (which makes it a code block).
What is the difference between ATX and setext headings?
ATX headings use leading hashes (# Title) and support six levels. Setext headings underline text with = (H1) or - (H2) and only support two levels. ATX is the modern convention.
How do I link to a heading in Markdown?
On GitHub, every heading gets an auto-generated anchor: lowercase the text, replace spaces with hyphens, and strip punctuation. Link to it with [text](#my-heading-anchor).
How many H1 headings should a document have?
One. The H1 is the document title; use H2 for major sections and H3+ for subsections. Multiple H1s weaken the document outline for accessibility and SEO.
Related Syntax
Horizontal Rule
Learn how to add a horizontal rule (divider line) in Markdown with three dashes, asterisks, or underscores — and how to avoid accidentally creating a heading.
Bold
Learn how to make text bold in Markdown using double asterisks or underscores.
Links
Learn how to create links in Markdown: inline links, reference links, autolinks, and titles.