Markdown syntax

How to Make a Heading in Markdown
(# H1 to H6, and common fixes)

You want a heading in Markdown, a big title line above a section, but typing # isn't turning into one. Headings are made with the # sign, and the most common reason they don't work is a missing space. Here is how to make all six levels and fix the usual traps.

The # heading syntax (H1 to H6)

Put one or more # signs at the start of a line, then a space, then your text. The number of # signs is the heading level.

You write You get
# Heading H1 (biggest)
## Heading H2
### Heading H3
#### Heading H4
##### Heading H5
###### Heading H6 (smallest)

So one # is the biggest heading (H1) and six of them is the smallest (H6). This is the standard way, called ATX headings.

The #1 reason a heading doesn't work: the missing space

This trips up almost everyone. There must be a space between the # and your text:

#Heading   → stays plain text (no space)
# Heading  → renders as a heading

If your heading is showing up as a normal line with a # in front, add the space after the # and it will render.

The other way: underline headings (=== and ---)

Markdown has a second heading style, called Setext: you write the text and underline it on the next line.

Heading 1
=========

Heading 2
---------

A row of = makes the line above an H1, and a row of - makes it an H2. It only covers those two levels, and it renders the same as # and ##.

One catch worth knowing: a single - or = is not enough, so a line with just one dash under it is treated as a normal paragraph, not a heading.

Careful: this is why a divider can become a heading

Because --- under a line of text is read as an H2 underline, a divider you meant to draw can accidentally turn the line above it into a heading. The fix is to leave a blank line between the text and the ---. There is a full walkthrough in how to make a horizontal line in Markdown.

See your headings rendered

In a plain text editor you only see the # symbols. To see the actual sized titles, open the .md file in a Markdown editor.

  1. Open app.noteloom.cc in Chrome / Edge / Arc and mount the folder with your file.
  2. Open the .md in the reading view to see the headings rendered, or live view to write and preview as you go.
  3. Your file stays a plain .md on disk; nothing is uploaded.
How do you make a table of contents in Markdown? Your headings are exactly what a table of contents is built from.

Related reading

How to make a horizontal line in Markdown The --- divider, and the heading trap it can cause. How to make a list in Markdown Bullets, numbers, and nested items under your headings. How to write Markdown The core syntax, from headings to links, in one place. How do you open a .md file? Where to open and read the file once you have written it.

FAQ

How do you make a heading in Markdown?
Start a line with a # sign, then a space, then your text: # Heading. Add more # signs for smaller levels, up to ###### for a level-6 heading. The space after the # is required.
Why is my #Heading showing up as plain text?
Almost always a missing space. #Heading with no space is not a heading, it stays a normal paragraph; # Heading with a space after the # is. Add the space and it renders.
How many heading levels does Markdown have?
Six, from H1 down to H6, written with one to six # signs. Most tools style H1 the largest and H6 the smallest, the same idea as heading levels in a document outline.
What is the difference between # and === headings?
They render the same. # (called ATX) works for all six levels and is the common way. Underlining a line with === (for H1) or --- (for H2), called Setext, only covers those two levels.
Why did my --- turn the line above it into a heading?
Because --- placed directly under a line of text is read as a Setext H2 underline, so the text above becomes a heading. Put a blank line between the text and the ---, or see the guide on horizontal lines.
Does NoteLoom show Markdown headings?
Yes. NoteLoom’s reading and live views render # headings (and === / --- Setext headings) as sized titles, straight from your local .md file, with nothing uploaded.

See your headings rendered

Write your # headings in a .md file, open NoteLoom in Chrome / Edge / Arc, mount the folder, and read it in the reading view with every heading sized and in place. No install, no account.

Open NoteLoom and try it