Notion to a book: exporting a workspace into something readable

A lot of good writing lives in Notion, mostly because the writing started as notes and became a book without anyone deciding it had. Then it needs to leave, and the export is where people discover how much of what they were looking at was Notion rather than their document.

Choose the right export, once

Notion offers PDF, HTML and Markdown & CSV from a page's overflow menu. For a book, take the Markdown.

The PDF is tempting because it is one click and looks finished. It is the same trap as printing from any preview: the layout is a screen layout, the margins are a web page's margins, and there is no page structure underneath it. It is a document, not a book.

Two settings on the Markdown export matter. Include subpages — on, or you get one page and none of its children. Create folders for subpages — on if the book has real nesting, off if you want a flatter pile of files to concatenate.

What the export actually contains

Unzip it and the first surprise is the filenames. Every page carries its Notion ID:

Chapter One 8f3a91c4e2b7401d9c6a5e3f2b1d0a7c.md
Chapter One 8f3a91c4e2b7401d9c6a5e3f2b1d0a7c/
  screenshot%202024.png

The hash is how Notion keeps links between exported files working. It also means every image reference in your Markdown is a long URL-encoded path into a folder named after a hash, and that nothing sorts into reading order on its own.

• Page titles become an H1 at the top of each file, so a concatenated manuscript has one per chapter — which is usually what you want, and occasionally one level off.
• Callouts lose their icon and colour and come out as blockquotes.
• Toggles are flattened; the heading and the hidden content end up adjacent.
• Databases export as CSV files, not as tables in the text. An inline table you were treating as content is now a spreadsheet sitting beside the prose.
• Synced blocks and mentions resolve to whatever they were pointing at, or to nothing.
• Equations, embeds and third-party blocks — Figma, Loom, anything embedded — become a bare URL.

The cleanup, in order

Do these in sequence. Each one makes the next easier to see.

1. Decide the order and rename. Prefix the chapter files 01-, 02- and so on and drop the hashes. This is the step everything else depends on, and it is also the first time you look at the book as a book.
2. Move the images into one folder and rewrite the paths. URL-encoded %20 in filenames is legal but hostile; rename them to something you can read.
3. Concatenate. One file, in order.
4. Fix the heading levels. If every chapter title is an H1 and your sections are H2 and H3, you are fine. If Notion's nesting produced H1s inside chapters, demote them now rather than wondering later why the table of contents is strange.
5. Deal with the callouts. Each one was either an aside, a warning or an emphasis. Decide which, and make it a blockquote, a heading, or plain prose.
6. Re-make the database tables you actually wanted as prose tables, from the CSV.
7. Delete the residue — status properties, meeting notes, "TODO: rewrite this", the tags you were using to organise drafting.

# After renaming to 01-..., 02-...
cat *.md > manuscript.md

# Strip Notion's page IDs from image paths
sed -i '' -E 's/%20[0-9a-f]{32}//g' manuscript.md

That second line is a starting point rather than a spell — check what your export actually produced before running anything with -i over it, and keep the original zip until you are finished.

The editorial pass nobody warns you about

The mechanical cleanup is an afternoon. The real work is that notes written inside a workspace assume the workspace.

• Cross-references to pages that are not in the book. "See the onboarding doc" means nothing to a reader who has one file.
• Second-person instructions to yourself. Drafting notes read as instructions to the reader once the context is gone.
• Sections that were placeholders. A page with a title and two bullets was a stub in a workspace; in a book it is a chapter that stops.
• Wildly uneven chapter lengths, because notes grow where the thinking happened rather than where a reader needs them.

This is the same pass a blog archive needs — turning posts into an ebook covers it in more detail, and the problem is identical: material written as pieces has to be re-read as a sequence.

Then design it once

Once you have one clean Markdown file, you are back on the ordinary path: set the typefaces, margins and paper once, put a page break where each chapter starts, and export. bukpress takes the file as it stands — drop it in, and the preview paginates while you keep editing, which is where the remaining Notion residue tends to become visible.

The thing worth keeping from this: your manuscript now lives as a plain text file rather than inside a product. That is the property that makes the next export, and the one after it, uneventful. The sample book is what the other end looks like.