How and why we moved our knowledge base from Notion to Markdown

# Motivation

There is nothing wrong with Notion. I still enjoy using it privatly. In the beginning, it felt like a very capable Markdown editor with nice abstractions. Over the years though, it got a bit too crowded for my taste. We used Notion as our knowledge base and partially for project management for years. The knowledge base part is what we cared about the most. Hopefully, these thoughts are usefuls for others.

Side note: I can imagine Microsoft buying them at some point. There is a lot about Office that is antiquated and Notion could fill that gap (Hello Notion CoPilot!).

# Ownership over our content

Freedom of tools. Content rules. Some of us use Obsidian to edit, but the same folders open in any code editor. I enjoy writing Markdown. I do it for the blog and the docs every day. Keeping the knowledge base in the same format removes friction.

# Saving costs

Our internal structures changed and require less ongoing work on internal policies. We also adopted Linear for project management (hello next vendor lock-in). So Notion was neglected. It can also be hard for humans to find information in a large knowledge base, or to keep parts of it up to date. We already pay for an AI subscription. Paying extra for Notion AI on top was never something I wanted to do.

# Privacy

The files are ours now. Full data sovereignty. But we still want to share them across the team, so we trust a Git repo provider with the content (Obsidian sync is another option). When we run batch edits with AI, we may leak data to whichever provider we use. But we do not store secrets in our knowledge base — no API keys, no passwords, no trade secrets.

# How we moved

We used the Obsidian Importer plugin and the Notion API flow. There are plenty of tutorials on how to do that, so we will skip the basics and stick to the gotchas.

# Missing internal links

A significant number of internal links broke during the import. Incremental imports left links pointing to NOTION_PAGE:(UID) references that no longer resolved. I fixed most of them with a local AI agent. About 150 broken links remained. I checked many of them manually and found they were either broken in Notion already or pointed to trashed documents. Good enough.

# Team spaces to vaults

In Notion, we had a few "team spaces" with separate access management. In Obsidian, the rough equivalent is a vault - think of it as a Git repo. We decided one mono-vault without access management beats multiple vaults. Searching and linking across vaults is not easy, and a flat structure matches how we actually work.

# Assets

Notion abstracts files away. It is all content. With Obsidian, files are real things you have to think about. We created one global Assets folder and put everything in it. Most of it is images, and we plan to use fewer files going forward.

# Databases

Notion databases are very capable and cool. Obsidian recently added databases too, but they are way more basic. The concepts are different. We will see how useful they turn out to be in practice. I already miss the fancy databases.

# File structure

The file structure works differently. The relation between a database and its entries shows up in the file system — each entry exists as its own file. That takes some time getting used to, but it makes the content portable.

# Web forms

We used Notion web forms to accept job applications. We need a different solution for this. Open task.

# No real-time collaboration

We can no longer co-edit a document live during a meeting. We will see how much we miss it. Our hunch: less than expected.

# Other Notion features

We did not use Mail or Calendar in Notion. We will not miss those.

# Takeaway

Owning the files matters more than we expected. Plain Markdown in a Git repo means we can search it, edit it with any tool, version it like code, and pipe it through AI when we want to.