Markdown headings

A Markdown heading is a line that starts with one to six hash marks (#), followed by a space and the heading text. One hash is the top level, six is the lowest. So # Title is the biggest heading and ###### Detail is the smallest.

The hash mark is the number sign on your keyboard, the same # you'd type anywhere else. Markdown reads it at the very start of a line as "this is a heading, not a paragraph."

Here are all six levels:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Each line drops a size as you add a hash mark. Level 1 is the document's title. Level 2 marks a main section. Levels 3 through 6 are subsections nesting under those, the way 1.1.1 nests under 1.1 in a numbered outline.

Two rules trip people up. There must be a space between the hashes and the text, so #Heading (no space) renders as plain text in most readers, not a heading. And the hashes have to start the line. A # in the middle of a sentence stays a literal hash mark.

A real document usually only needs the first three levels. You write one # for the title, an ## for each section, and an ### where a section splits into parts:

# Trip notes: Lisbon

## Where we stayed

### Alfama
### Bairro Alto

That produces a title, one section heading, and two subsection headings underneath it. The reader sees the structure at a glance, and so does any tool that reads the headings.

The underline style (setext)

There's a second way to write the top two levels, called setext. Instead of hashes, you underline the text with = for level 1 or - for level 2:

Heading 1
=========

Heading 2
---------

That renders the same as # Heading 1 and ## Heading 2. It only reaches two levels, so once you need an H3 you're back to hashes anyway. Most people pick one style and stay with it. The hash style is more common because it scales to all six levels and reads clearly even in raw text.

The number of = or - characters doesn't have to match the text length. One is enough. A line of dashes can also mean a horizontal rule, so the underline only counts as a heading when there's text on the line directly above it.

In Unmarked

All six heading levels render in Unmarked, in Read mode and in Split mode's live view, sized so the hierarchy is obvious. The setext underline style renders the same as its hash equivalent.

Headings do more than set type size here. The outline sidebar is built straight from them: every heading becomes a line in the sidebar, nested by level, and clicking one jumps the document to that spot. The clearer your headings, the better you can move around a long file. In Write mode you can insert any level with ⌘1 through ⌘6, or ⌘0 to turn a heading back into normal text.