What to Check Before Moving a Notion Export into Obsidian

matt well — Wed, 05 Aug 2026 08:30:18 +0000

Moving notes from Notion to Obsidian looks simple: export a ZIP, unpack it, and copy the folder into a vault.

The part that usually causes trouble happens before the import. A Notion export can contain temporary image references, HTML-based callouts, long filenames, CSV databases, and Markdown that is technically valid but awkward to use in a local vault.

Here is a practical checklist for checking the export before you build links and folders around it.

1. Keep the original ZIP

Do not unpack the only copy and start editing files in place. Keep the original Notion ZIP untouched, then create a separate working copy for cleanup.

This gives you a reference when a page looks different after repair. It also makes it easier to separate a conversion problem from an Obsidian configuration problem.

Keep both copies until you have reviewed the imported vault:

the original Notion export;
the repaired or cleaned export;
the final Obsidian vault copy.

2. Inspect one note and its assets

Open one or two representative Markdown files in a plain text editor. Then inspect the folders next to them.

Look for these common problems:

image links pointing to a separate asset folder;
image filenames that no longer match the links;
page and asset names with long UUID suffixes;
callouts or toggles exported as raw HTML;
code fences without a language label;
blank lines or indentation that make lists render incorrectly.

Do not assume every file has the same problem. Choose one note with images, one note with callouts or tables, and one code-heavy note if your workspace contains them.

3. Treat images as a separate migration check

Markdown text can look correct while every image is broken. Check an image-bearing note before importing the whole workspace.

The useful questions are:

Does the image file exist in the exported folder?
Does the Markdown link point to the actual relative path?
Does the filename contain characters that are difficult to handle on your target system?
Is the original export still available if an image was not included at all?

If the source export does not contain the image data, a Markdown converter cannot recreate it. Keep a list of missing assets instead of silently accepting a broken vault.

4. Repair the repetitive problems before importing

Some cleanup is mechanical and safe to automate. Typical examples include normalizing image references, simplifying UUID-heavy filenames, reducing excessive blank lines, and adding missing language labels to code blocks.

Other changes require your judgment. Complex tables, embedded content, permissions, comments, page history, automations, and database views do not have a perfect Markdown equivalent.

For a browser-based cleanup pass, Notion Export Fixer accepts a Notion export and produces a repaired ZIP locally in the browser. Review the report and keep the original ZIP before downloading the result.

5. Review a small sample after repair

Before moving the entire export into your vault, compare a few important notes with their originals.

Check:

headings and nested lists;
images and relative links;
callouts, toggles, and tables;
code blocks;
filenames and folder paths;
links between related notes.

File counts are not enough. A migration can contain the expected number of files and still have broken image paths or unreadable blocks.

6. Import into Obsidian last

Create a temporary vault or copy the repaired folder into a test location first. Open several notes and let Obsidian finish indexing before reorganizing anything.

Only after the sample looks correct should you:

move the reviewed folder into the main vault;
rename notes or folders;
add Obsidian-specific links and tags;
archive the original and repaired ZIPs outside the vault.

This order keeps the migration reversible. It also prevents you from building a large set of links on top of files that still need repair.

What a Notion export will not preserve perfectly

Notion and Obsidian use different document models. A Markdown export can preserve readable text and many basic structures, but it will not reproduce every interactive feature.

Expect separate handling for database CSV files, complex nested table cells, third-party embeds, permissions, comments, page history, and database views. The goal is a usable and portable Markdown archive, not a pixel-perfect clone of the Notion workspace.

DEV Community: matt well