Outlining Long Documents in Markdown: Headings That Stay Navigable

A long Markdown file is only as usable as its headings. Get the hierarchy right and the same structure that organizes your thinking becomes your outline, your table of contents, and your section links — all for free. Get it wrong and a 4,000-word document collapses into a wall of text nobody can navigate, you included.

This guide walks through how headings carry structure, the syntax worth knowing, how headings turn into navigation, how to keep them stable as a document grows, and a simple workflow for outlining before you write a word.

Headings are the backbone of a navigable document

People don't read long documents start to finish. They scan. Nielsen Norman Group found that 79% of users scan any new page while only 16% read word-by-word, and your headings are the anchors they scan against. The same research is blunt about what works: use "meaningful sub-headings (not 'clever' ones)" that say what the section actually contains.

This only matters more as documents get longer. For content over 1,000 words, NN/G recommends structuring before formatting — a table-of-contents overview, clear sections, and in-page links to specific parts. Headings pull double duty here. They signal hierarchy to the human eye, and they hand your tools the structure they need to build navigation on their own. In a long document, headings aren't decoration; they're the index.

ATX, Setext, and choosing heading levels

Markdown gives you two heading syntaxes. ATX headings use one to six leading # characters to set levels 1 through 6, and a space after the `#` is required. Setext headings, from the original Markdown spec, "underline" text with = for level one and - for level two — but they stop at two levels.

## Section
### Subsection
#### Rarely go deeper than this

Default to ATX. It covers all six levels, reads clearly in plain text, and is what most modern Markdown tools expect.

For levels, restraint beats range. Use one H1 for the title, H2s for major sections, and H3s for sub-points inside a section. Don't skip levels — jumping from H2 straight to H4 breaks the outline tree your tools build. And if you keep reaching for H4 or H5, that section is usually asking to be promoted to its own H2.

How headings turn into navigation

Here's the payoff for clean headings: most environments build the navigation from them, with no extra work from you. On GitHub, two or more headings auto-generate a table of contents through the Outline menu. Editor outline panes and static-site generators behave the same way — a clickable tree built straight from your heading structure.

Each heading also becomes a linkable anchor. The rule is predictable: text is lower-cased, spaces become hyphens, and punctuation is stripped, so ## Advanced Features turns into #advanced-features. Duplicate headings pick up numeric suffixes (-1, -2). That lets you link to any section from anywhere in the document:

See the [installation steps](#installing-on-macos) below.

You can also hand-roll custom HTML anchors with <a name="..."></a>, but those are left out of the auto-generated outline. So reserve real headings for anything you want to show up in the table of contents.

Keeping headings navigable as the document grows

There's one catch worth knowing. Because anchors are generated from heading text, editing or reordering headings changes their anchors, which quietly breaks any links pointing at them. A few habits keep the outline stable as the document grows:

• Settle a heading's wording before you link to it, and update links when you do rename a section.
• Keep headings short and front-load the keyword — "Installing on macOS" beats "How you might go about installing things on a Mac."
• Make headings grammatically parallel so the outline reads as a clean list.
• Keep one idea per section. If a section sprawls past its heading, split it.

The reward is an outline a reader — or a future you — can actually trust.

Doing this with Carets

Outlining is a write-the-headings-first workflow, and it moves faster in an editor that treats headings as structure rather than just bold text. Carets is a fast, native Markdown editor for iPhone, iPad, and Mac, and a few of its features fit this task directly.

Because your work stays plain text, the heading hierarchy you build is portable and future-proof — the same # structure reads correctly in any Markdown tool, with nothing locked to a proprietary format. Syntax highlighting keeps the heading levels visually distinct as you draft, so an imbalanced outline is easy to catch at a glance. Organizing notes into files, projects, and tags means a long document lives next to the related drafts and snippets it draws on, instead of off in a silo. And because it's native to Apple platforms rather than a web wrapper, it stays responsive in the large files where outlining matters most.

A practical rhythm: draft the H2/H3 skeleton first as your outline, read the headings top-to-bottom to confirm the structure tells the whole story, then fill in prose under each. For more writing workflow guides, browse the Carets blog, where we collect practical Markdown how-tos like this one.

Download Carets on the App Store for iPhone, iPad, and Mac.

Frequently Asked Questions

How many heading levels should a long Markdown document use?

In practice, three is plenty: one H1 for the title, H2s for major sections, and H3s for sub-points within a section. Markdown supports six levels, but anything past H3 tends to make the outline harder to scan rather than clearer. If you find yourself reaching for H4 or H5, that section probably wants to be split into its own H2.

Why do my heading links break when I edit a document?

Most renderers generate a heading's anchor from its text — lower-cased, spaces turned into hyphens, punctuation stripped. When you reword a heading, the anchor changes, so any link pointing at the old anchor breaks. Reordering headings that share identical text also shifts their numeric suffixes. Settle on heading wording before you link to it, and update links when you rename a section.

Should I use ATX (#) or Setext (underline) headings?

ATX headings — one to six leading hash marks — are the safer default. They cover all six levels, read clearly in plain text, and are what most modern Markdown tools expect. Setext underlines only reach two levels and are easy to miss in a diff. Use ATX unless a specific tool or house style asks otherwise.

Do I need to write a table of contents by hand?

Usually not. Many Markdown environments — GitHub, editor outline panes, static-site generators — build a navigable table of contents automatically from your headings. Your job is to keep the heading hierarchy clean and descriptive; the outline falls out of that structure for free.