Navigate a Long Note by Its Outline (No App Feature Needed)

To navigate a long Markdown note, give it a clean heading hierarchy and let the outline build itself. The outline pane, the fold arrows, the jump-to-heading list — those are not features your app invented. They are derived from the # headings in your file. Write the headings well and the navigation comes with the text, in any editor.

This matters more than it sounds. Most people treat a long note as a wall of text and reach for an app feature to tame it — a table-of-contents plugin, a saved outline view, a sidebar mode. But that view is a render of your text. The structure that produces it lives in the file. Open the same note in a different editor and the outline reappears, because the editor is reading the same headings yours did.

Steph Ango, the CEO of Obsidian, put the principle behind this in one line: "Apps are ephemeral, but your files have a chance to last." ¹ The navigation of a note should last with the file, not with the tool. Headings are how you make that true — they are the one structural element that renders identically everywhere, because the heading is the syntax and the outline is just a reading of it.

How do I make a table of contents in a Markdown note?

You don't build one — you write headings, and any conforming renderer derives the contents. GitHub's own documentation says it plainly: "Each heading title is listed in the table of contents and you can click a title to navigate to the selected section." ² The list is generated from your headings at read time, not a thing you maintain.

The same is true beyond GitHub. MDN's reference for HTML heading elements — the rendered cousin of Markdown headings — notes that "heading information can be used by user agents to construct a table of contents for a document automatically." ³ The contents are a property of the heading hierarchy. Get the headings right and the table of contents is a by-product, not a chore. There is nothing to update when you add a section; the new heading simply appears.

How does a heading become an outline?

A heading is text marked by # characters, and its level is the count of them. The CommonMark specification defines an ATX heading as "a string of characters, parsed as inline content, between an opening sequence of 1–6 unescaped # characters and an optional closing sequence." ⁴ One # is an H1, six is an H6.

The level is what builds the tree. The spec is exact: "The heading level is equal to the number of # characters in the opening sequence." ⁵ So ## nests under #, and ### nests under ##.

Stack them in order and you have written an outline — a nested structure the renderer reads top to bottom. The fold arrows and the indented sidebar are both just visualizations of that one rule. You are not configuring an outline; you are spelling one out, line by line, in characters that survive every tool.

How do I jump to a heading or link to a section?

The anchor you click is generated from the heading text — derived, not stored by hand. GitHub Docs describes the mechanic: "hover over the section heading to expose the icon and click the icon to display the anchor in your browser." ⁶ Hover, reveal, copy. The deep link is a slug of the words you already wrote.

This is also real navigation, not decoration. MDN notes that "a common navigation technique for users of screen reading software is to quickly jump from heading to heading in order to determine the content of the page." ⁷ Your headings are a jump table for a screen-reader user and for you.

One honest caveat: the exact anchor string differs between renderers, so a deep link copied from one tool may not resolve byte-for-byte in another. The heading is portable; the slug is renderer-specific. Link within a note freely, and re-copy a cross-tool anchor rather than trusting it to survive the move.

How do I fold or collapse sections in a long note?

Folding operates on the heading hierarchy in your file, but the fold interface is a per-app convenience that varies by editor. Some editors collapse a heading and everything under it; some don't fold at all; the keybindings differ. What folds is your structure — the H2 and the lines beneath it, down to the next same-or-higher heading.

This is the load-bearing distinction. The structure is durable and portable: the heading hierarchy travels in the plain text wherever the note goes. The fold chrome is not guaranteed — cat and grep don't fold anything, and two editors fold differently.

So do not lean on the fold UI as if it were stored in the note; it isn't. Lean on the headings. An editor that can't fold can still show you the outline, jump you to a section, and let a reader skim the structure — because all of that comes from the same # marks, which every tool reads.

What's the difference between ATX and Setext headings?

ATX headings use # characters and reach six levels on one line; Setext headings underline the previous line and reach only two. The CommonMark spec sets the limit: a Setext heading "is a level 1 heading if = characters are used in the setext heading underline, and a level 2 heading if - characters are used." ⁸ Two levels only, spanning two lines.

For a deep, stable outline, prefer ATX. The reason is expressiveness, not breakage — Setext still renders; it is in the spec. But an outline that needs H3 through H6 simply cannot be written in Setext, and a two-line heading is more fragile to edit than a #-marked one. ATX gives you six levels — one line each — and a uniform mark you can grep for. That is what makes the auto-outline usable for a note that runs thousands of words.

Common mistakes that break the outline

The outline is only as clean as your nesting. Most broken outlines come from a handful of avoidable habits, each of which a renderer faithfully reproduces as a confusing tree.

• No space after the #. The spec requires it: "At least one space or tab is required between the # characters and the heading's contents, unless the heading is empty." ⁹ #Heading renders as literal text; # Heading renders as an H1. The missing space is the single most common reason a heading silently disappears.
• Skipped levels. Jumping H2 to H4 confuses the tree. MDN warns that skipping levels "may create confusion, as the person navigating this way may be left wondering where the missing heading is." Go H1, H2, H3 in order; do not leap.
• Multiple H1s. Use one. Google's documentation style guide is direct: "Use one H1 heading as the title of your document. Subsequent headings should be H2 or deeper." ¹⁰ More than one H1 gives you several competing roots and an outline with no clear top.
• Setext for a deep note. Reaching for === and --- underlines caps you at two levels (see above). For anything that needs subsections, write ATX #.
• Trusting fold state to travel. Folding is an app view, not file data. The headings travel; the collapsed/expanded state does not. Don't organize a note around a fold you can't take with you.

How this works when you own the file

When the note is plain Markdown on your own device, the outline is a property of your text, not of any one app — and that is the whole point. Write the headings cleanly and the navigation is encoded in the file itself: it works in your editor, in grep, in a static-site build, and in whatever tool you open next year.

There is no app-specific outline file to lose, because there is no app-specific outline file at all. The structure rides along in the same characters that spell the note.

This is also where headings differ sharply from some other Markdown niceties. Wiki-style [[links]] are an editor convention that does not survive a move to plain CommonMark; an embedded image can quietly break when the file travels without it. Headings are the element that doesn't break — ATX # is core CommonMark, and it renders identically everywhere.

So a long note's structure is the most portable thing about it. The same logic that lets a heading hierarchy act as an outline you own across a document applies inside a single note: a tool like MNMNOTE keeps your notes as plain Markdown you own, which means the outline you wrote today is the same outline a different reader, on a different device, derives tomorrow.

Frequently asked questions

How do I make a table of contents in a Markdown note? You don't build one by hand — your # and ## headings are the table of contents, and any conforming renderer derives it. GitHub's docs confirm "each heading title is listed in the table of contents and you can click a title to navigate." ² Add a heading and the contents update themselves; there is nothing to maintain.

How do I collapse or fold sections in a long Markdown note? Folding works on the heading hierarchy already in your file, but the fold interface is a per-editor convenience — some editors fold, some don't, and keybindings differ. The durable part is the structure: the heading tree travels in the plain text everywhere, even where the fold UI doesn't exist.

How do I jump to a heading or link to a section in Markdown? The anchor is auto-generated from the heading text. In GitHub's words, "hover over the section heading to expose the icon and click the icon to display the anchor." ⁶ It is derived from your words, not stored. Note the exact slug can differ between renderers, so re-copy a cross-tool link rather than trusting it to survive the move.

Why isn't my #Heading showing as a heading? Because there is no space after the #. CommonMark requires "at least one space or tab between the # characters and the heading's contents." ⁹ Write # Heading, not #Heading, or the renderer treats the whole line as ordinary text.

What's the difference between ATX and Setext headings — which should I use? ATX (#) reaches six levels and lives on one line; Setext (=/- underlines) reaches only two and spans two lines (CommonMark §4.3). ⁸ Both render, but for a deep, stable outline prefer ATX — it can express H3 through H6 and is easier to edit and grep.

Should I use one H1 per document? Yes. Google's style guide says to "use one H1 heading as the title of your document" and make "subsequent headings H2 or deeper." ¹⁰ One H1, H2 for sections, H3 for subsections, no skipped levels — that discipline is what makes the auto-derived outline usable in every tool.

Is the outline an app feature or part of my file? It is a reading of your file. Even named apps describe it that way: Obsidian's Outline plugin "lists the headings in the active note." ¹¹ Remove the app and the headings still encode the structure; the outline is a property of your text, so it survives whatever tool you opened the note in.

This builds on the people who defined and documented the form — the CommonMark specification authors, the GitHub and MDN documentation teams, and Steph Ango's "file over app" principle. Credit them, then keep your own copy of the work.

Write your long notes with clean headings, and the navigation is already done — not in an app's saved view, but in the file you own.