Why your docs belong in Git, not a database
Every documentation tool makes the same quiet decision on your behalf: your writing goes into their database. It’s such a default that most teams never question it. But that one choice is the root of almost every documentation frustration you’ve ever had — the lossy exports, the disappearing history, the migration you keep putting off because you know it’ll hurt.
There’s another way to store a knowledge base, and developers have been living it for years with their code: plain files, in Git. Here’s why that model is the right one for docs too.
The problem isn’t the editor. It’s the storage.
When your content lives in a proprietary database, three things follow, whether the vendor intends them or not:
You can’t really leave. “Export to Markdown” is the escape hatch every tool advertises and none of them do well. What you get back is a brittle dump full of platform-specific blocks, broken internal links, and formatting that renders nowhere but the tool you’re trying to leave. The export exists so the box can be ticked, not so you can actually go.
Your history isn’t yours. Revision history is one of the most valuable things a docs tool holds — who changed what, when, and why. But it lives inside the vendor’s database, often capped at 30 or 90 days, visible only through their UI, and gone the moment you stop paying. You’re renting your own memory.
Your knowledge is opaque. A blob of HTML or proprietary XHTML in a database row is readable by exactly one thing: the application that wrote it. Not your scripts, not your CI, not the growing pile of LLMs and agents your team now uses every day. To get your own content out, you go through their API, on their terms.
None of these are editor problems. You can’t fix them with a nicer WYSIWYG. They’re storage problems.
What “docs as files in Git” actually means
Flip the storage model and the frustrations invert with it. Store each page as a
plain Markdown file — .md, with a little YAML frontmatter for metadata — in an
ordinary Git repository that you own.
Now:
- You own the data, completely. The docs are files on disk in a repo you control. Clone it, grep it, back it up, script against it, or walk away entirely. There is nothing to export because nothing was ever locked in.
- History is native Git history. Every change is a commit: author, message, timestamp, diff. Full history, forever, in your repo — the same review and blame tooling you already use for code, applied to prose.
- It’s readable by everything. Markdown is plain text. Your team reads it,
grepreads it, your static site generator reads it, and every LLM or agent reads it directly — no export step, no API, no translation layer.
That last point is quietly the biggest shift of the last two years. The value of a knowledge base is increasingly how easily machines can read it, because your team now works alongside models that answer questions, draft changes, and reason over your internal knowledge. Content trapped in a database is invisible to them. Content sitting in Git as Markdown is already in the exact format they consume best. You don’t have to make your docs “AI-ready” — plain Markdown in Git simply is.
”But a database gives me features”
The reasonable objection: databases exist for a reason. Don’t you lose search, structure, collaboration, and diagrams by going to flat files?
You don’t have to. A file is where content lives; it says nothing about what you build on top. A full-text index can be rebuilt from files on every change. Cross-document links can resolve by title or slug across the whole repo. Comments can live in a sidecar next to the Markdown, so discussion is preserved without polluting the content itself. Diagrams can be authored inline and stored as text that diffs cleanly. Two people editing the same page is a merge — a solved problem in Git — not a mystery locked inside a service.
The database was never the source of those features. It was just the default place to keep them. Move the source of truth to Git and you keep every capability while shedding the lock-in.
The migration you keep postponing
The deepest cost of database-backed docs is the one you don’t see on any invoice: the migration you never do. Everyone knows their current tool isn’t quite right. Almost nobody switches, because the export is lossy and the history won’t come along, so the effort feels like starting over. That inertia is the product. It’s what you’re actually paying for.
Files in Git remove the trap at the root. When your docs are already plain Markdown in a repo you own, “switching tools” stops being a migration at all — it’s just pointing a different tool at the same files. The leverage moves back to you, permanently.
Try the model, not just the argument
This is the model DocuCommit is built on: a self-hostable documentation platform where every page is a Markdown file in your Git repo. No database. Native Git history. A desktop editor for writing and a read-only server for publishing — both reading from the same files. Our own documentation is written in exactly this on-disk format — plain Markdown in a Git repository.
This post is the opinionated case. For the neutral, full-length treatment — including when this model is a poor fit — see Git-backed documentation, explained.
The fastest way to judge the idea is to see it work. There’s a live demo, no signup required:
And if you want to run it on your own infrastructure, the 14-day trial needs no credit card.
Own your docs from day one — because they were never anywhere you couldn’t reach.