Your Docs Should Live in Plain Markdown (Even With a Visual Editor)
Why plain Markdown is the portability contract for documentation — greppable, diffable, AI-ready — and how a visual editor can round-trip it cleanly.
· 7 min read · The Nibleaf team
There is one question that tells you almost everything about a documentation platform: if you leave next year, what do you walk away with?
Some platforms answer with a folder of Markdown files you can open in any editor, commit to any repo, and feed to any static site generator. Others answer with a JSON export of proprietary blocks, an API you have to crawl before your contract lapses, or a support ticket. The difference is not cosmetic. It determines whether your documentation is an asset you own or a liability you rent.
Our position is simple: docs should be stored as plain Markdown, full stop — and this is true even when the authoring experience is a visual editor. The two are not in tension. A WYSIWYG editor is a view; Markdown is the contract.
Two ways a platform can store your writing
Every documentation tool sits in one of two camps, whatever its editor looks like.
| Markdown files | Database of blocks | |
|---|---|---|
| Canonical storage | Plain text on disk (or in a column, but as text) | Proprietary JSON/XML rows |
| Export | Copy the files | Vendor exporter, fidelity varies |
| Diff and review | git diff, line-by-line | Opaque or vendor-specific |
| Search your own content | grep, ripgrep, any indexer | Vendor API |
| Feed to an LLM | Directly | Extraction pipeline first |
| Migration cost | Near zero | A project with a deadline |
Block-database platforms are not built by malicious people. A database of structured blocks is genuinely easier to build real-time collaboration and granular permissions on top of. But the storage choice quietly becomes a switching cost, and switching costs quietly become pricing power. When your 2,000-page knowledge base exists only as rows in someone else's database, every renewal negotiation starts from a weaker position.
What "WYSIWYG over Markdown" means technically
The common objection is that visual editors require a richer document model than Markdown can express, so lock-in is the price of a good editor. That is half true and fully avoidable.
Modern block editors (TipTap, ProseMirror, Lexical and friends) do maintain an internal document tree — that is how they give you slash menus, drag handles, and inline formatting. The lock-in question is not whether that tree exists. It is whether the tree is ever persisted.
A Markdown-native editor treats the internal model as ephemeral:
- On load: parse the stored Markdown into the editor's document tree.
- While editing: operate on the tree — blocks, slash commands, keyboard shortcuts, all of it.
- On save: serialize the tree back to Markdown. The tree is discarded. Nothing editor-internal ever touches storage.
This is a round-trip invariant, and it is a real engineering constraint: any feature that cannot serialize to Markdown (plus a documented component vocabulary — more on that below) does not ship. What lands in storage looks like this, always:
## Configure the webhook
Set the endpoint URL in your dashboard, then verify the signature
on every request:
```ts
const valid = verifySignature(payload, header, secret);
```
<Callout title="Rotate your secrets">
Webhook secrets should rotate on the same schedule as API keys.
</Callout>
Contrast this with editors that persist their internal JSON and offer Markdown only as an export. Export-to-Markdown is a one-way, best-effort conversion that runs when you ask for it. Round-tripping Markdown means Markdown is the record, every save, verifiable by opening the file.
What you gain when Markdown is the storage format
Export is cp -r. There is no exporter to trust because there is nothing to convert. Your docs directory is the deliverable. Point Docusaurus, Astro, Hugo, or a different platform at it and most content renders immediately.
Your existing tools work. git diff shows exactly what changed in a review. grep -r "deprecated-endpoint" finds every reference in milliseconds. CI can lint prose, check links, and block merges — the whole docs-as-code toolchain applies because docs are, in fact, code-shaped.
LLMs read it natively. This matters more every quarter. The llms.txt convention exists specifically to serve Markdown to models. RAG pipelines chunk Markdown cleanly along heading boundaries with no HTML-stripping or block-JSON flattening step. Coding agents can read, cite, and patch your docs the same way they handle source files. Content trapped in a block database needs an extraction pipeline before any of this works — and extraction pipelines lose structure, drift out of date, and break silently.
Portability disciplines the vendor. This is the underrated one. When leaving is cheap, the platform has to win your renewal on merit — editor quality, search, hosting, collaboration — rather than on the cost of getting your content back out.
The trade-offs, stated honestly
Markdown-as-storage is not free. Two costs are worth naming rather than hand-waving.
Rich layouts need MDX components. Tabs, multi-language code groups, and callouts exceed CommonMark. The honest solution is MDX: component tags with documented, human-readable semantics living inside the text file. <Tabs> in a plain-text file is still greppable and diffable, and its meaning is obvious — but if you migrate to a renderer without an equivalent component, you will map or rewrite those tags. That is a real cost. It is also bounded and visible in a way a proprietary block schema never is: you can find every component usage with one grep.
Conflict resolution is per-page, not per-character. Block databases with CRDTs can merge two people editing the same paragraph live, Google-Docs-style. Plain-file storage generally resolves at page granularity — last write wins, or an explicit conflict to reconcile. For documentation, where pages have natural owners and edits flow through review anyway, this is usually the right trade. Anchored review comments cover the collaboration case that actually matters: feedback on specific blocks before publishing. But if your team routinely has five people typing in the same paragraph simultaneously, a CRDT-based editor genuinely serves you better, and you should weigh that.
Where the popular platforms land
Credit where due — several platforms get this right, each with different trade-offs.
Mintlify stores docs as MDX in your own git repository, and its web editor commits changes back to the repo. It passes the plain-text test; the differences are elsewhere — it is a closed-source managed service, so the platform (hosting, search, analytics) is not something you can run yourself. See our Mintlify alternatives breakdown for the full picture.
Docusaurus is Markdown/MDX files all the way down, fully open source, and a strong fit if your whole team is comfortable in git and React. What it does not ship is a hosted editor, search infrastructure, or a publishing workflow for non-developers — you assemble those. Our Nibleaf vs Docusaurus comparison goes deeper.
GitBook is editor-first: content lives in the platform, and its bi-directional Git Sync feature can mirror content to Markdown files in a repo. That is meaningfully better than no bridge at all, though the platform remains the primary residence and some block types map imperfectly onto files. The Nibleaf vs GitBook comparison covers where the models diverge.
Notion-style workspaces and Confluence sit furthest toward the block database. Both can export to Markdown or HTML, but export is a conversion event, not the storage format, and fidelity depends on which blocks you used.
How Nibleaf implements the contract
Nibleaf is an open-source (AGPL-3.0) documentation platform built around exactly this invariant. The editor is Notion-style — blocks, slash menu, the authoring experience non-developers expect — and it round-trips plain Markdown on every save. MDX components (callouts, tabs, code groups) cover the layouts Markdown alone cannot express. Nothing proprietary is ever persisted.
Because storage is Markdown, the rest of the system composes on top of it: built-in Orama full-text and fuzzy search (with a dedicated Arabic tokenizer) indexes your actual content, publishing produces immutable snapshots so readers never see half-written pages and you can roll back to any previous snapshot, and per-language page trees keep translations as parallel Markdown, including Arabic and RTL layout.
You can self-host the entire stack — app, API, worker, PostgreSQL, cache, and S3-compatible storage — with one docker compose up; the open-source release is the full platform, not a feature-gated tier. Or use the managed cloud, currently in free beta.
The test to run before you commit
Ask any documentation vendor two questions. First: what exactly is written to storage when I press save? Second: if I export everything today, will the files render somewhere else tomorrow?
If the answers are "Markdown" and "yes," the platform is competing for your renewal on quality. Any other answer, and part of what you are paying for — now or eventually — is the difficulty of leaving.
Platform details for Mintlify, GitBook, and Docusaurus reflect their public documentation as of July 2026 and may change.
Frequently asked questions
- Can a WYSIWYG editor really store plain Markdown?
- Yes. The editor parses Markdown into an in-memory document model for editing, then serializes back to Markdown on every save. As long as nothing editor-internal is ever persisted, the stored format stays plain Markdown.
- Is Markdown expressive enough for a real documentation site?
- Standard Markdown covers most documentation. For richer layouts — tabs, callouts, code groups — MDX components fill the gap while keeping the file plain text you can read, grep, and version.
- Why does Markdown matter for AI tools and RAG pipelines?
- LLM tooling consumes Markdown natively. Conventions like llms.txt serve Markdown to models, and heading structure gives RAG pipelines clean chunk boundaries without an extraction step.
- How do I migrate docs off a platform that stores content as JSON blocks?
- You depend on the vendor's exporter or API, and fidelity varies by block type. With a Markdown-based platform, migration is copying files — the content renders anywhere Markdown is understood.