The six levels
| Write | Level | Use it for |
|---|---|---|
# Text | 1 | The title, once per document |
## Text | 2 | Main sections |
### Text | 3 | Parts of a section |
#### Text | 4 | Rarely needed |
##### Text | 5 | Almost never needed |
###### Text | 6 | Almost never needed |
Most documents need only the first three. If you reach level five, the document may be easier to read split in two.
Use one title
A document reads best with a single # title and ## sections under it.
Search engines and screen readers use the title to understand the page, and a
reader builds its contents list from the levels below it.
The underline style
An older way: underline the text with = for level 1 or - for level 2. It
only goes two levels deep, so most people use #.
You write
A title
=======
A section
---------You see
A title
A section
Link to a heading
Every heading gets an anchor made from its text: lower case, with hyphens for
spaces and no punctuation. Link to it with # and the anchor.
You write
## Getting started
Skip ahead to [the next section](#getting-started).You see
Getting started
Skip ahead to the next section.
The full rules, with examples, are in the guide to Markdown links.
Give a heading your own anchor
If the heading text might change, add an HTML anchor with a fixed name, and link to that instead. GitHub supports this too.
You write
<a name="install"></a>
## How to install the app
[Jump to the install steps](#install)You see
Formatting inside a heading
Bold, italic, code and links all work inside a heading, though a heading is already bold in most apps.
You write
### The `config.json` fileYou see
The config.json file
Common problems
- No space after
#.#Headingstays as text. Write# Heading. - A heading straight after text. Leave an empty line before it, so it is not lost in the paragraph above.
- Text became a heading by accident. A line of
---right under text makes it a level 2 heading. Leave an empty line between them.
Questions
How many heading levels does Markdown have?
Six, from # to ######.
How do I make a heading without the # showing?
The # never shows on the page. If it does, there is no space after it, or
it is inside a code block.
Can a heading have a number, like 1.2?
Yes. Write the number into the heading text: ## 1.2 Setup. Markdown does
not number headings for you.
Next
- How to make a table of contents in Markdown, built from your headings.
- Read a long document with its contents in the margin.