How to write headings in Markdown
Try it — edit the markdown and watch the preview
Result
Runs entirely in this tab. Open the full editor to work on a real document.
The rule in one line
Hashes, then a space, then the text. The number of hashes is the level.
# H1
## H2
### H3
Six levels exist. Almost no document needs more than three, and a document that reaches H5 is usually a document that wants splitting up.
The mistake everyone makes once
#Not a heading
# A heading
Without the space, CommonMark and GitHub Flavored Markdown treat the line as ordinary text. Some older renderers were lenient about it, which is why the habit persists and why the same file can look right in one tool and wrong in another.
Headings do more than look big
A heading is structure, not size. Three things read it:
- Tables of contents — including the Contents panel in this editor
- Anchor links, generated from the heading text so sections can be linked to
- Screen readers, which use headings to move through a document
Which is why skipping a level — an H1 followed by an H3 — is worth avoiding even though it renders fine. The gap is invisible on screen and obvious to anything navigating by structure.
Setext: the other syntax
Title
=====
Section
-------
Equals signs make an H1, dashes make an H2, and there is no third level. It is rare in new documents but common in old READMEs, and it is the reason a row of dashes directly under a paragraph turns that paragraph into a heading instead of drawing a line.
Common questions
- How do I make a heading in Markdown?
- Put one to six hash characters at the start of a line, then a space, then the text. One hash is the largest heading and six the smallest. The space is not optional — "#Title" with no space is literal text in CommonMark and GitHub Flavored Markdown, and it is the single most common reason a heading does not appear.
- What is the difference between a header and a heading?
- Nothing, in Markdown. People search for "markdown header" far more often than "markdown heading", but both mean the same hash-prefixed line. A header in the HTML sense — the top region of a page — is a different thing entirely and Markdown has no syntax for it.
- Should a document have more than one H1?
- Usually not. One H1 names the document and everything below it nests under that, which is what a table of contents, a README renderer and a screen reader all expect. Markdown will happily render six of them; it just stops meaning anything.
- What are the equals signs and dashes under a line for?
- That is Setext syntax, the older style — equals signs under a line make it an H1, dashes make it an H2. It only reaches two levels, which is why hashes are what almost everyone writes. It also explains a common surprise: dashes directly under a paragraph make a heading, not a horizontal rule.
- Do I need a closing hash at the end?
- No. Trailing hashes are allowed and ignored, so "## Section ##" renders identically to "## Section". They are a stylistic habit from older Markdown documents and add nothing.
- Why do my headings have anchor links on GitHub?
- Renderers generate an id from the heading text so it can be linked to directly. That is also how a table of contents finds its targets — including the Contents panel in this editor, which builds itself from the H1s, H2s and H3s as you type.