Headings in Markdown: turning a file into a book's structure

A Markdown manuscript has no chapters, parts or sections in the way a layout application understands them. It has lines that start with hash marks, and a renderer that decides what those mean. Get the hashes consistent and the book falls into shape on its own. Get them inconsistent and you will be fixing the same problem three times — once on the page, once in the contents and once in the ebook's menu.

What each level becomes

Six levels exist; a book needs three, occasionally four. What matters is that each level means the same thing everywhere in the file.

The reason the mapping has to be fixed is that three consumers read it. The typesetter picks a size and a space-before for each level — the type scale is built on those levels being consistent. The contents page, whether you write it or something generates it, is a list of a level. And the EPUB's navigation document, the menu a Kindle shows when a reader taps the top of the screen, is the heading outline verbatim. A ### that is really a chapter appears as an indented afterthought under the wrong parent, on every device, forever.

One title, and only one

The single most common structural fault in a Markdown manuscript is more than one #. It happens when chapters were drafted as separate files, each with its own # Chapter Three, and then combined into one. Every file's top heading was correct on its own; together they are six titles and no chapters.

Fix it before you do anything else. The # is the book. Chapters are ##, whatever they were called in their own files. If you write in separate files, write the chapter files with ## at the top from the start, so the merge needs no editing at all.

Do not skip a level

Jumping from ## straight to #### because the #### looked the right size in the preview is a layout decision made with a structure tool. The preview was showing you one renderer's default sizes; the outline it produced has a hole in it. An EPUB reader that builds navigation from the outline will either invent an empty level to hold the orphan or drop it, and neither is what you meant.

If a heading looks too big, the fix is the heading's *style* — its size in the typography settings — not its level. Level is meaning. Size is appearance. Keeping the two apart is the whole discipline, and it is the same one that makes a book easy to re-typeset later without touching the text.

Numbering chapters

Type the number into the heading if you want one: ## 3. The second winter. Do not rely on the renderer to count for you, because most Markdown renderers do not, and the ones that can be configured to will renumber the moment you insert a chapter — which sounds like a feature until a cross-reference in chapter nine still says "see chapter four".

For fiction, most books number nothing and title everything, or the reverse. For non-fiction, a number on chapters and none on sections is the convention, and it is a good one: readers refer to chapters by number and to sections by what they are about. Numbered sections (3.2.1) belong to manuals and theses, where the reader is being sent to a paragraph rather than invited to read.

Headings that are too long

A chapter heading is set large. At 24pt on an A4 page with sensible margins, roughly 35 characters fit on a line; a heading of 70 will wrap to two lines and, in the contents, to two lines again with the page number stranded on the second. Look at any bookshelf — chapter titles are short because they have to be set large.

• Keep `##` headings under about 40 characters. If the idea needs more, the extra goes in the first sentence of the chapter, not the heading.
• Section headings can run longer, because they are set smaller, but a ### that wraps still looks like a sentence that lost its full stop.
• No terminal punctuation. A heading is a label, not a sentence. Question marks are the one exception, and even those read better as a statement.
• Sentence case or title case, but pick one. Mixing them across chapters is invisible in the file and glaring in the contents.

Front matter and back matter are headings too

A dedication, a preface, the contents page, acknowledgements, an afterword: in a word processor these are formatted by hand as one-off pages. In Markdown they are ## headings like any chapter, each followed by a page break, in the order a printed book puts them. That keeps them in the outline — an EPUB reader can jump to the preface — and it keeps them consistent with everything else, so a change to the heading style changes them too.

# The Quiet Hour

---

## Contents

One · The Letters
Two · The Bridge

---

## One · The Letters

The first letter arrived on a Tuesday.

Two things are worth noticing in that fragment. The contents page is typed, which is the honest way to do it in a format that has no page numbers until it is rendered. And the page breaks are written as --- on their own line — the convention bukpress uses, where a line of three dashes is a hard page break rather than a horizontal rule, so a chapter heading starts at the top of a fresh sheet without any HTML in the file.

What the renderer does with it

In bukpress the three levels are styled from the title and body type settings you choose once — the same face and colour rules apply to every heading of a level, so the hierarchy is uniform without any per-heading work — and the same outline is used as the document structure in both exports. The PDF gets the sizes; the EPUB gets a navigation menu built from the ## and ### lines, which is why getting the levels right is the step that cannot be skipped. A book whose chapters are all ## has a working ebook contents before its author has thought about one.

The reverse is also true. If the outline is wrong, no amount of typography fixes it, because the structure is being read by machines that do not look at the page. Three marks, used consistently, is the entire job.