Moving your knowledge
without losing it.

Sooner or later, every knowledge base moves. The tool changes, the company standardizes, the pricing changes, or you simply outgrow what you chose three years ago. Migrations have a bad reputation because most people attempt one exactly once, with no mental model of what is actually happening, and get surprised by what arrives broken on the other side.

This lesson is migration literacy: how exports and imports actually work, what reliably survives and what reliably does not, how to keep hierarchy intact, how to run two tools during a transition without losing your mind, and a step-by-step plan you can adapt. The examples lean on Notion because it is the migration people most often ask about, but the mechanics apply to moving between any two note tools, in any direction.

How exports and imports actually work

There is no magic pipe between two note apps. A migration is always the same three steps: the source app serializes your content into files (usually Markdown, HTML, or a structured format like JSON or CSV), those files travel, and the destination app parses them and rebuilds pages from what it can understand. Anything the export format cannot express, or the importer cannot parse, is silently gone.

That sentence explains almost every migration surprise. Markdown cannot express a kanban board, so a board exports as something flatter. An importer that does not understand the source's link syntax turns internal links into dead text. The export is a translation between two languages with different vocabularies, and translation is lossy exactly where the vocabularies do not overlap.

What survives, what breaks

Across tools, the pattern is remarkably consistent. Plan around it rather than discovering it.

• Text and basic structure: survives. Headings, paragraphs, lists, to-dos, quotes, code blocks, and simple tables travel well through Markdown or HTML. This is the bulk of most workspaces, and it usually arrives clean.
• Images and attachments: mostly survive, verify. Good exports bundle files alongside pages; weak ones export links pointing back at the old vendor's servers, which die when the account does. Check this specifically.
• Databases: partially survive. Rows and properties typically export (often as CSV plus a page per row), but views, filters, sorts, formulas, and relations between databases usually need rebuilding by hand. Budget real time for this; it is the biggest single line item in most migrations.
• Internal links: fragile. Links between pages depend on the importer mapping old page identities to new ones. Expect a percentage to break, and plan a link-fixing pass on your most important pages.
• Permissions: do not survive. Who can see what is configuration in the source tool, not content. You will re-grant access in the destination, from scratch. Treat it as a chance to clean up rather than replicate old sprawl.
• Comments and version history: do not survive. Discussion threads and page history almost never export anywhere. If a comment thread contains a decision that matters, paste the decision into the page body before you migrate. History stays behind; accept it.

Hierarchy: keeping the tree intact

Your page tree is real information: "Runbook: Deploys" living under Engineering is part of what it means. Flat exports (one folder of files) throw that away, and rebuilding nesting by hand across hundreds of pages is the kind of work that stalls migrations permanently.

Two things preserve hierarchy. First, an export format that encodes it: folders mirroring the page tree, or a structured format that records parent-child relationships. Second, an importer that actually reads it. Check both ends before committing, using a small test batch: export one branch of your tree, import it, and see whether the nesting arrives intact.

Direct integrations beat file exports here. NoteX imports from Notion through Notion's own API rather than through exported files: on NoteX Desktop you connect your Notion account, browse your pages in the sidebar, and import pages or the whole workspace with hierarchy preserved. Because the import reads live data through the API, page relationships come across as structure, not as a folder convention someone has to guess at. See Notion import & sync.

Running two tools during the transition

The riskiest migration is the big bang: export everything Friday, import over the weekend, declare the old tool dead on Monday. It fails because day one in the new tool is exactly when you most need to check the old one, and because stragglers keep editing the old workspace, creating a fork in your team's truth.

The safer pattern is a transition period with three rules:

• One tool is the source of truth for each area, always. Migrate area by area (start with one team or one hub), and at any moment everyone can answer "where does this content live now?" Ambiguity, not effort, is what kills migrations.
• The old tool goes read-only per area as it moves. Announce it, then stop editing migrated areas at the source. A frozen source cannot fork.
• Keep a live bridge while both tools are in play. This is where linked sync earns its keep. NoteX Web's Notion sync is two-way: import pages and databases, keep them linked, pull updates from Notion, and push NoteX edits back, with conflicts flagged rather than silently overwritten. A team can work in NoteX for weeks while colleagues still in Notion see current content, which removes the pressure to move everyone in one weekend. (Two-way sync is web only; desktop import is one-way, Notion to NoteX.)

A migration plan template

Adapt the scale to your workspace; the sequence stays the same.

• 1. Inventory and prune (before anything else). List your top-level areas and rough page counts. Archive what is dead. Migrating garbage costs the same as migrating gold, and no team has ever regretted pruning first.
• 2. Pilot one branch. Pick a representative area (some prose, some databases, some images) and migrate only it. Verify against a checklist: nesting, links, images, database properties. The pilot tells you what your real migration will break, while the stakes are still low.
• 3. Map the gaps. From the pilot, write down what needs manual rebuilding (usually database views and relations) and who owns each rebuild. This list, not the page count, is your real effort estimate.
• 4. Migrate area by area. Move each hub with its owner (lesson three's ownership pays off here), freeze the source area, fix links on the pages that matter most, and re-grant permissions deliberately.
• 5. Run the bridge, then close it. Keep linked sync or the read-only source available during the transition, set an end date, and honor it. A migration without an end date is two knowledge bases forever.
• 6. Verify your exit before you settle in. The final step of arriving anywhere: run the exit audit from lesson two on the new tool. Bulk-export, open the files without the app, confirm you could leave again. That is the habit that makes this migration your last stressful one.

Migration literacy is leverage

Notion, Obsidian, NoteX, and whatever comes next all deserve evaluation on their merits, and honest tools compete on merits rather than on exit costs. Knowing how migrations work changes how you choose: you stop asking "which tool will I never leave?" (nobody can promise that) and start asking "which tool respects that I might?" Formats you can read, exports that preserve structure, APIs that let you take a continuous copy: those are the properties that make every future migration boring. If this course has one through-line, from blocks to files to wikis to AI, it is that structure you own compounds, and boring migrations are what owning your structure feels like.

If Notion is your starting point specifically, the practical comparison lives at NoteX vs Notion, and stray Markdown from any export can be cleaned up with the Markdown converter.