NanoFile

Markdown headings

A heading is a line that starts with one to six hash signs and a space. The number of hashes is the level, so # is the title and ### is a sub-sub-section.

All six levels
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5
Heading 6
The underline style, for levels 1 and 2 only
Heading 1
=========

Heading 2
---------

Heading 1

Heading 2

Called setext headings. They only go two levels deep, which is why almost everyone uses hashes.

What usually goes wrong

  • The space after the hash is required. #Heading renders as literal text with a hash in front of it, and on Discord it becomes a channel link instead.
  • A heading must start at the beginning of the line. Indent it by four spaces and it turns into a code block.
  • Some renderers want a blank line before a heading. If a heading right under a paragraph is not rendering, that is why.
  • Closing hashes (## Heading ##) are allowed and ignored. They are not required.

Where it behaves differently

PlatformBehaviour
GitHubAll six levels, and every heading gets an anchor link you can point at.
DiscordOnly three levels, # to ###. A fourth hash renders as text.
SlackNo headings at all. Use bold text as a stand-in.

Questions

How many heading levels does markdown have?

Six, matching HTML's h1 to h6. Going past ### is rare in practice, and Discord stops at three.

Should a document have more than one H1?

For HTML it is allowed, but for a markdown file that becomes a page, one H1 is the convention: it is the document's title and everything else nests under it.

Related