Markdown cheatsheet · Headings
Markdown headings, from H1 to H6
A heading is a line that starts with one to six # signs and a space. The number of signs sets the level: # is the page title, ###### is the smallest subheading.
The syntax
# Heading level 1 ## Heading level 2 ### Heading level 3 #### Heading level 4 ##### Heading level 5 ###### Heading level 6
#Heading without a space after the # is not a heading in most renderers (including GitHub); it stays plain text. Always write # Heading.The alternate syntax
H1 and H2 also have an older "underline" form: put the heading text on its own line and underline it with = or - signs. Any number of signs works.
Heading level 1 =============== Heading level 2 ---------------
Most people stick with # signs: they cover all six levels and are easier to scan. The underline form only reaches H2.
Good practice
Use one # H1 per document, as the title, and don't skip levels: an ### should live under an ##. This keeps the document outline clean, which matters for accessibility and for tools that build a table of contents from your headings.
Put a blank line before and after each heading. Some renderers cope without it, but others glue the heading to the previous paragraph.
Common questions
How do I link to a heading?
Most renderers (GitHub, GitLab, most static site generators) auto-generate an anchor from the heading text: lowercase, spaces turned into dashes, punctuation dropped. ## Getting Started becomes #getting-started, so [see setup](#getting-started) jumps to it.
Can I make text bigger without it being a heading?
Not in pure markdown; font size isn't part of the syntax. Headings are semantic, not styling. If you control the renderer, inline HTML like <span style="font-size:1.5em"> works, but it won't render everywhere.