Notion Export to Markdown: Why Pages Arrive Flat

Unzip a Notion export and the hierarchy has moved house. What used to be a page inside a page inside a teamspace is now a folder inside a folder, with the page itself sitting at the bottom as a Markdown file. Notion documents the rule in a single line: "Any non-database Notion page can be exported as a Markdown file."

One page, one file. Read that as a constraint rather than a feature and the rest of the export makes sense. Anything in your workspace that was not a page — the three-column layout, the toggle somebody kept meeting notes in, the synced block mirroring the onboarding checklist into four different places — has to fit inside that one file or it does not appear at all. The database side of this problem, where relation columns come out as plain text URLs, is its own article. This one is about the pages.

One file per page is the whole design

The Markdown & CSV option produces two kinds of artefact and the split is documented in one sentence: "Full page databases will be exports as a CSV file, with Markdown files for each subpage."

Note what that sentence specifies and what it does not. Full page databases become CSVs. A database that lives inline on a page, as a block among other blocks, is not mentioned anywhere on the export page. Neither is a linked view of a database that lives somewhere else. The silence is not a promise in either direction, which makes an inline database the single most useful thing to test before you trust the export at scale.

There is a matching gap in Notion's own API, and it explains the shape of the problem. A page nested inside another page appears in the parent's block list as a child_page object whose entire payload is a title string. The parent does not contain the child. It contains the child's name. Every system that reads Notion, the exporter included, has to walk that reference to find the content, and every system that writes Notion back has to recreate the reference from whatever it can find. The folder tree in your ZIP is that reference, rendered as directory names.

The hierarchy lives in the folder names, and one checkbox deletes it

Notion's description of the folder layout is short, and worth quoting because it is where the structure is committed to. When you export with subpages included, "you'll see them neatly organized in their own folders when you unzip the file. These folders will also contain the images and other assets on your pages saved separately."

So the ZIP holds three things — Markdown files, CSVs, and asset folders — and the containment relationships are expressed entirely in path names. Which brings us to the checkbox.

Unchecking Create folders for subpages "keeps all pages and files in a single folder, reducing the total path length," which is Notion's own first suggestion when a Windows extraction fails on path length. It works, and it takes the nesting with it: a page that lived four levels deep under a teamspace becomes a sibling of everything else in one directory, and nothing inside any file says otherwise. That trade — nesting against path length, and the extraction tool that avoids having to choose — is the same one the database side of this export runs into, and it is worked through there rather than repeated here.

The paths are not quite the only record, though, and the exception is easy to miss in a folder listing. In the section on exporting a whole workspace, Notion says: "A sitemap (index.html) is included the export to help you navigate the exported workspace. The list items in the sitemap are locally linked to the exported pages in HTML and Markdown formats." The sentence is Notion's, typo included. Open that file first — it is generated for the Markdown export too, not only the HTML one, and it is the nearest thing the archive has to the sidebar you used to navigate by.

Two things about it are unstated, and both are cheap to settle on the day you export. Notion does not say whether those list items are nested or simply listed, which is the difference between a second copy of your hierarchy and an alphabetical index of page names. And the promise is made about the workspace export, not about the per-page one, so do not assume a single-page download brings an index with it.

The blocks Notion's own API will name but not read

If the export looks thin, the usual next move is to pull the same content through the API, which is a reasonable instinct and is how a proper full dump normally gets built. For Notion there is a documented ceiling on that route, and it sits lower than most people expect.

The block reference states it plainly: "The API does not support all block types. Only the block type objects listed in the reference below are supported. Any unsupported block types appear in the structure, but contain a type set to unsupported." The unsupported object then carries a single field, block_type, naming the internal type. The example values Notion gives are form, button, and drive.

I pulled that reference on 26 September 2026, and the next sentence is the one that closes the door: "This field is informational only and does not expose block content."

Read that as an inventory problem rather than a formatting problem. Through the API you can learn that a block exists and what kind of block it is. You cannot learn what it says. A workspace that leans on Notion forms for intake, or on buttons that create a template with fields pre-filled, has working procedure sitting in blocks that neither the export nor the API will hand over as data. The only route left is a person opening each one and writing down what it does.

While you are in that reference, notice a small dated line in the list of block types that support children: Meeting notes, "renamed from Transcription in 2026-03-11". The vocabulary itself moves. Any script written against block types has a shelf life, and so does any article about them, which is why the date at the bottom of this one matters more than the prose.

A duplicate synced block is a pointer, not a paragraph

Synced blocks are the feature most likely to make two exported files disagree, and the API shows the mechanism cleanly. Notion describes two versions of the object. The original holds a synced_from value of null plus its children. The duplicate holds nothing except a synced_from.block_id, an identifier for the original, and no content of its own.

That is a sensible design for a live product and an unpleasant one for an archive. The text you see in four places exists once. Anything reading blocks has to follow the pointer to find it, and anything that cannot follow the pointer holds four references to nothing.

The reference adds a second line worth knowing if you were planning to fix this by script: "The API does not supported updating synced block content." The typo is Notion's. The limitation is not — you cannot write resolved text back into the duplicates through the API before exporting.

So the order of operations runs the other way. Find the synced blocks first, while the workspace is live, and decide for each one whether the copies need to carry the words after the move. Usually two or three matter: a standard disclaimer, a support hours block, a safety note pasted into every job page. Paste the real text into those by hand, or accept that the duplicates may come out as empty references and write down where they were.

Build one deliberately awkward page and export it

None of the above needs a full workspace export to check. Put the difficult constructs on a single page, export that page on its own, and read what comes out. It is a short job, and it replaces every guess in this article with a result from your own workspace.

1. Make a page with two columns, a toggle containing a short paragraph, a callout, a code block, an inline database of three rows, a linked view of a database that lives elsewhere, a duplicate synced block, and a link to another page in the workspace.
2. Export it as Markdown & CSV with Include subpages on and Create folders for subpages on.
3. Open the .md file in a plain text editor. Not in a Markdown previewer — the previewer renders whatever is there and hides what is not.
4. Work down your list and mark each construct present, degraded, or absent. Notion commits to exactly one outcome in advance: "Callout blocks will be exported as HTML, as there is no Markdown equivalent." Everything else on that list is undocumented, and therefore yours to establish.
5. Check what the link to another workspace page became, and whether an index.html came with the download. Notion documents the sitemap for the workspace export; whether a single-page export gets one is not stated, and those two answers together decide whether the archive is browsable.
6. Export the same page again as HTML and compare. That path is the one Notion documents for comments: "When you export as HTML, you can also export comments at both the page and block levels. This includes resolved and unresolved comments and any files, pages, or users mentioned in them." Nothing equivalent is promised for Markdown, and nothing stops you keeping both files.

Whatever you find is true for that build of Notion, on that date. Write the date beside the findings. The point of the test is not a permanent table; it is an hours estimate for the real workspace, plus a short list of things somebody will have to rebuild by hand.

Callouts, columns, and the notation Markdown does not have

The callout sentence is the tell. Notion did not decide that callouts should become HTML. Markdown simply has no way to express a box with an emoji and a background colour, so the exporter falls through to a format that does. Everything with that same property is a candidate for the same treatment, or for quiet loss.

Columns are the clearest case. In the API a column_list is a parent block whose children are column blocks, each optionally carrying a width_ratio between 0 and 1, and "when omitted, the default is to use equal widths for all columns." The ratios are expected to add up to 1. Two numbers and a nesting relationship. Markdown has a notation for neither. A two-column page is, in linear text, just one thing after another, and the reading order you designed becomes a guess made by whatever wrote the file.

Toggles sit in the same category. The API lists Toggle among the block types that support child blocks, alongside headings "when the is_toggleable property is true". Collapsed content is still content. Whether it arrives, and whether it arrives marked as having been hidden, is not something the export page addresses at all.

This is the general argument that a CSV is not a backup, applied to prose instead of records. The file honestly contains what the format can hold. What the format cannot hold does not generate a warning.

The PDF path, the HTML fallback, and one rule about printing

PDF is the option people pick when they want something a non-Notion person can open, and it carries more switches than the other two.

• An Include content dropdown lets you "export everything, or exclude files and images."
• Page format sets paper size, and a Scale percent field adjusts the fit.
• Include subpages on the PDF path needs a Business or Enterprise plan, and it produces a ZIP of PDFs plus folders of images and assets.
• "Custom emojis will not be appear in PDF exports." Notion's typo again, and a real cost if page titles use them as status markers.

Before you build a plan on any of that, check which PDF you mean. Notion is withdrawing the workspace-level one: "The option to export workspace content as a PDF is going away. This change will be rolled out to workspaces gradually between now and August 31, 2026. You can still export workspace content as an HTML, Markdown, or CSV file, and export individual pages as a PDF." That rollout date has passed as this is written, and it was gradual, so whether the option is still in your own settings is a question about your workspace rather than about the product. Page-level PDF export is unaffected. A whole-workspace PDF archive is the one plan here with an expiry date on it.

Then the line that should change how you verify a PDF run: "If a PDF export fails, Notion will instead export as HTML." A failure that silently succeeds in a different format is only cheap to discover while the account is still open. Check the extension of what you actually received, not merely that a file arrived.

One more limit belongs here, because it surprises anyone planning a paper archive of a tracker: you cannot print a full-page database from the browser. Notion's instruction is to export it as a PDF first and print that.

Where the download goes, and why some people wait for an email that never arrives

Two delivery routes exist, and file size picks between them without telling you which one it picked.

"If a file is very large (depending on the number of sub-pages included), we may send you an email with a download link rather than automatically starting a download. This is not always the case. No email will be sent if you were able to download the file right away."

A modest export therefore lands in the browser and generates no email, and a large one generates an email and no browser download. Both behaviours are correct, and each looks like a failure if you were expecting the other. There is a third case underneath: if the account running the export has email notifications switched off, the link goes to the in-app inbox instead.

The workspace-wide route is a different menu from the per-page one: Settings in your sidebar, then General, then Export all workspace content. It is desktop or web only — there is no workspace export from a phone. Per-page exports do work there, where the result comes out through the share menu on your phone rather than as a file download, with the same email link as a backstop.

That route also has a scope limit worth reading before you treat its output as complete: "Pages that the exporter doesn't have access to, such as private pages of other users, will not be included in the export." Notion adds that admins on the Enterprise plan can grant themselves access to specific pages so those pages are covered next time, and that "some content also may not be exported based on teamspace settings." So a workspace export is the workspace as your account sees it, not as it exists. On the way out of a company, that difference is usually somebody's private notes about a customer, and the export gives no sign they were skipped.

Putting it back somewhere is metered by file count

Whether you are moving to a fresh Notion workspace or into something else entirely, the round trip has limits that have nothing to do with what the export contains. Notion states the headline itself: "You can't instantly recreate your workspace by reuploading your exported workspace content."

The import documentation fills in why, and the numbers are the part to plan against.

Three of those deserve spelling out.

Anchor links do not import. A wiki is mostly links. If your workspace worked because everything pointed at everything else, the Markdown route hands you the words and drops the wiring. Notion's own suggested workaround is to "recreate navigation in Notion using headings and a table of contents," which is an accurate description of manual labour.

The ZIP route counts files, not megabytes. A workspace export with folders for subpages, plus a separate asset file per image, reaches five figures of files long before it reaches 5 GB. Notion also warns that "hidden folders or files (like .DS_Store) can cause failures," and that files with nonstandard extensions, its example being .md copy 273, "may not convert as expected." Anyone who unzipped on a Mac, tidied the folders and re-zipped has probably produced both problems at once.

CSV mapping rewrites values quietly. Dates import in MM/DD/YYYY. A cell containing a comma breaks when mapped to a Select property, and Notion's advice is to map that column to Text instead. Currency amounts, percentages and negative numbers get the same advice. A column with mixed types comes in as text "to avoid data loss", and the Title property does not support formatting at all. None of that produces an error message. It produces a column that used to be a number and is now a string.

One operational note on failure: "If the UI says failed, check your workspace for partially imported pages before trying again." Imports add rather than update, so a blind retry after a partial run is how you end up with two of everything.

What you need in order to read it in 2031

The reason to care about any of this is that the archive has one job, years from now, when nobody has a Notion login.

Markdown is a good answer to that. It is plain text, it stays readable in any editor, and Notion added a detail in its own favour: "You can open up to 10 Markdown files at once in Notion Desktop to read with Notion's formatting. Opening a Markdown file creates a read-only copy of the file in Notion." Right-click the file, open it with Notion, and it arrives in a tab as a read-only preview — no import, no rate limit, nothing written back into a workspace.

Read the extension list under that paragraph closely, though, because of what is not on it. Notion names the supported file types as .markdown, .mdown, .mkdn, .mkd and .rmd. .md — the extension Notion's own exporter writes — is absent from the list as published. That is either a gap in the list or a gap in the feature, and the documentation does not say which. Test it with one file out of an export you already have before you make "the files open in Notion" part of anyone's archive plan.

What plain text cannot hold is the shape. Between the folder tree and the sitemap, getting from page to page is the part that is reasonably well covered; what is missing is everything that was true inside a page and had no notation for itself. So the archive worth keeping is the ZIP plus a short written record of exactly that: the layout of the two or three pages where columns carried meaning, the synced blocks and what they said, the forms and buttons the API would only name, the views and their filters, whose private pages were never in scope, and the date each of those notes was taken. A single page of that is enough, and it is the difference between a folder of files and a readable archive.

It costs an afternoon while the workspace is open. After cancellation it is not available at any price, because the only copy of the shape was the rendering on screen.

Verified against Notion documentation on 26 September 2026. The one-file-per-page rule, the callout and HTML behaviour, the subpage folder layout, the single-folder workaround, the index.html sitemap, the private-pages scope limit, the PDF switches and HTML fallback, the withdrawal of workspace PDF export, the comments-in-HTML behaviour, the printing limitation, the delivery-by-size FAQ and the workspace export path come from Export your content. The Markdown, HTML, ZIP and CSV import limits, the H4 downgrade, the anchor-link exclusion and the read-only Markdown preview with its list of supported extensions come from Import data into Notion. The unsupported block type, the child_page title object, the synced block pointer and the column_list structure come from the block reference. Quoted sentences are reproduced as published, including the three typos. Notion revises all three pages without notice, so re-read them before you rely on a number here.