Markdown vs block editors: why canonical markdown wins for team docs

Open a Notion-style editor and a markdown editor side by side and they look like cousins. You type a heading, a list, a code block; both render something clean. The difference is invisible until you try to leave, diff a change, or hand a page to an automated agent. It lives in one question: what is actually stored when you hit save?

For a team wiki, the answer matters more than the editing experience. Here is the case for canonical markdown as the source of truth — and an honest accounting of what you give up to get it.

What a block editor actually stores

A block editor doesn't store your document as text. It stores a tree of typed blocks in a database. Each paragraph, heading, toggle, callout, and table row is a record with an ID, a type, properties, and a parent pointer. The page you see is that tree, rendered. The model is genuinely powerful: because every block is a first-class object, you can give blocks relations, roll them up into databases, embed one page inside another, and build layouts a flat text file could never express.

In that world, markdown is an export format. When you click "export to markdown," the editor walks its block tree and flattens it into text. That flattening is lossy by design. A relation between two database rows, a synced block, a multi-column layout, a custom property — there's no markdown for those, so they get dropped, stringified, or approximated. Re-import the file and you don't get your tree back. Markdown is a one-way door out, not the thing itself.

None of this is a flaw. It's the correct architecture if your product is a flexible app builder. It's just worth being clear-eyed that markdown is a guest there, not the resident.

The costs, for a wiki specifically

When the canonical form is a proprietary block tree, a few costs follow — and they compound over the years a wiki actually lives.

Lock-in by data model, not by contract. You're not locked in because a vendor is hostile; you're locked in because your content's true shape only exists inside one system's schema. Moving out means accepting the lossy export and rebuilding what didn't survive.

Export drift. Because the export is a projection, the exported file and the live document are never quite the same artifact. The file you back up, email, or commit is a lossy snapshot — close enough to read, not faithful enough to be the original.

No clean grep or diff. This is the one that bites engineers daily. You can't grep -r "rate limit" across a block-tree database the way you can across a folder of text files. You can't get a line-by-line diff of what changed between Tuesday and Friday, because there are no lines — there's a tree mutation. Code review culture runs on git diff; block-tree docs sit outside it.

Every integration is a translation layer. Want to publish a doc to your static site, pipe it into a search index, feed it to a script, or let an agent edit it? Each integration has to speak the editor's block schema and translate to and from it. With text, most of those integrations are just... reading a file.

The case for canonical markdown

Make markdown the canonical form — the thing that's stored, not a thing that's exported — and the costs above invert into properties.

Portability. The document is a text file. It opens in any editor, on any OS, in fifty years. There is no "export" step because there's nothing to flatten; the file you can walk away with is the document.

Version control. Markdown lives natively in git. You get real diffs, blame, branches, and review on your prose the same way you get them on code. For a team that already ships software, the docs join the workflow you already trust.

Agent-readability. This is the part that's quietly becoming decisive. An LLM agent reads markdown fluently and writes it fluently. When markdown is canonical, an agent reads exactly what it writes — there's no block-tree round-trip to corrupt, no schema to learn, no translation layer to drift out of sync. As more of the writing and maintenance of a wiki gets delegated to agents, "the source of truth is plain text the agent already understands" stops being a nice-to-have.

To be fair to block editors: the gap isn't about which tool can talk to an agent — plenty expose rich APIs and their own agent surfaces. The point is narrower and more durable. When the canonical store is plain markdown, the agent operates on the real document with no intermediary representation in between. Fewer moving parts, fewer places to drift.

The honest tradeoff

Canonical markdown is not free. You give up the arbitrary block-and-layout model — the very thing block editors are best at. No relational databases of pages, no synced blocks, no pixel-arranged multi-column dashboards. Markdown has headings, lists, tables, code, links, images, and a handful of extensions. That's the ceiling.

For a team wiki, that ceiling is high enough, and the constraint is mostly a feature: docs stay documents, readable and greppable, instead of drifting into fragile mini-apps. But be honest about where it's the wrong call. If you're building a design tool, a relational workspace, a project tracker, or anything whose value is the rich interactive block model, forcing everything through canonical markdown would throw away the point. Block editors win those use cases cleanly, and it's not close.

The choice isn't "markdown good, blocks bad." It's matching the storage model to the job. Documents that need to be portable, diffable, and agent-legible for years want text. Interactive relational surfaces want blocks.

tela: canonical markdown, all the way down

tela is a team wiki built on exactly this bet. pages.body is canonical markdown, forever — there is no block table behind the scenes. The editor (Milkdown) gives you a modern WYSIWYG surface, but it parses markdown in and serializes markdown out; the markdown is the document, not an export. Content syncs to plain .md files over WebDAV, so your wiki is also just a folder of text files you fully own. And because the canonical form is markdown, an agent reads exactly what it writes — no translation layer in between.

That foundation is what makes the rest possible. tela ships a built-in MCP server (39 tools) so agents are first-class editors, not bolt-ons. Its Atlas feature generates a cited wiki from the git history and Jira tickets you already produce — the wiki that writes itself, from the code you already ship. The core is open-source (AGPL — the whole product, not a stripped "community edition"), built on Go and Postgres; you can self-host it or use the free cloud tier.

You can pick a block editor for a wiki and many teams happily do. But if you want your docs to outlive the tool, diff like code, and stay legible to the agents increasingly doing the writing, the storage model is the decision that matters — and canonical markdown is the one that ages well.