Headings in Markdown

Headings and paragraphs

Markdown syntax

Works everywhere

# Heading 1

One # per level, up to six. A space after the # is required.

Start the line with one # for a top-level heading, two for the next level, and so on to six. Use one H1 per document and don't skip levels; tables of contents and screen readers both rely on the order.

All ways to write it

```
# Heading 1
```
One # per level, up to six. A space after the # is required.Works everywhere
```
## Heading 2
```
Works everywhere
```
Heading 1
=========
```
Underline style, for levels 1 and 2 only.Works everywhere
```
Heading 2
---------
```
Works everywhere

Example

You type

# Release notes

## Version 2.4

### Fixed

Exports with more than 500 pages no longer time out.

You get

Release notes

Version 2.4

Fixed

Exports with more than 500 pages no longer time out.

Questions

Why is my # heading showing as text?

CommonMark needs a space after the # signs: #Heading is a paragraph, # Heading is a heading.

How do I link to a heading?

Most renderers give each heading an ID: lowercase, spaces turned into hyphens, punctuation removed. Link with [text](#the-heading-id).

Why did my text turn into a heading after a line of dashes?

A line of --- directly under text makes it a level 2 heading. Leave a blank line before --- when you want a horizontal rule.

Headings in Confluence

Headings render in a Markdown Macro+ macro, and Markdown Importer turns them into Confluence headings, so the page's own Table of contents macro picks them up. Markdown Exporter writes headings H1 to H6 back out with # signs.