Nobody on my team ever decided to build a database. We added a docs folder, then ADRs, then runbooks, then specs, then a prompt library, then the agent instruction files. I looked up one day and we had a few hundred markdown files with consistent frontmatter, a naming convention, and build tooling that parses all of it. That’s not a docs folder anymore. That’s a data store, and GitHub is the admin panel.
What does markdown as a database actually look like?
Worth being literal about the mapping, because once you see it you start holding the repo to the standards the analogy implies.
| Database concept | Repo equivalent |
|---|---|
| Row | One markdown file |
| Table | A directory, plus a naming convention |
| Schema | YAML frontmatter keys, enforced by whatever reads them |
| Primary key | The file path, or a slug in frontmatter |
| Foreign key | A relative link to another file |
| Audit log | Git history, with authorship and timestamps built in |
| Write path | A pull request |
| Query | Grep, or a build step that parses every file |
Why do teams end up here?
Not laziness. The repo already ships the features you’d otherwise go build a system to get: versioning, blame, diffing, branching, access control, review, all there on day one, no new service to run, no new login for anyone to lose. A row change arrives with an author, a timestamp, a rationale in the commit message and a discussion thread attached. Most internal tools never get that far. There’s a quieter reason too: Microsoft Research found, in its study of modern code review, that knowledge transfer is one of the real payoffs of reviewing at all. Keeping the ADRs and specs in the same tree as the code is how that knowledge outlives whoever had it.
The newer reason is that agents read markdown natively. A repo full of structured prose is directly consumable by the same tools writing your code, which is the shift I wrote about in markdown in pull requests is the new source code: AGENTS.md didn’t exist before August 2025 and, per the agents.md site, it’s now in over 60,000 open-source projects. Once your instructions, conventions and ADRs are all files in the same tree, the repo isn’t just where the prose lives. It’s the thing your agents query.
Where does the analogy break?
At every guarantee you gave up to get here, and the failures are all quiet ones.
- No constraints. A frontmatter field can be misspelled, missing, the wrong type, or a string where the reader wants a list. Nothing rejects the write. It’s valid markdown, so it lands, and your build either skips it or misreads it.
- No referential integrity. This is the big one. Rename a heading and every anchor link pointing at it breaks. Move a file and every relative link into it breaks. Neither throws an error anywhere. Links rot silently in both directions until a reader hits a 404.
- No transactions. A change touching ten files is atomic per commit, not per meaning. Merge the PR that adds a field and the one that consumes it in the wrong order and you’ve got a half applied migration with no rollback story.
- Search is not a query engine. Grep answers questions about strings, not about records. The first time you want every record with
status: draftowned by a team that no longer exists, you’re writing a parser.
The fixes are boring and they work. Pin the frontmatter contract somewhere machine readable, a JSON schema or a typed parser, and fail CI on a record that doesn’t match. Run a link checker over the whole tree on every PR, anchors included, so a renamed heading breaks the build instead of the reader. Treat a change to the frontmatter contract as a migration that needs a plan for existing records, same discipline that makes config and infra changes reviewable. And keep all of it on the same review checklist as everything else, or it drifts within a quarter.
If markdown is the database, what is a pull request?
It’s the write path, and that’s the part that actually bothers me. In a real database you’d never inspect a write by reading its bytes, you’d look at the row. But when the store is markdown and the interface is GitHub, bytes are exactly what review hands you: the raw source of the record, in diff form, with no view of what the record looks like after the merge. Reviewing a docs change that way is reviewing a migration as a hexdump. All the information is technically there. Nobody catches anything.
The failures follow from that directly. A table gains a column and the pipes stop lining up, which reads as noise in source and as a broken table in a render. A link gets pointed at a path that doesn’t exist, invisible in a diff, obvious in a render. A frontmatter key gets renamed in nine files out of ten. Those are record-level errors a database would have rejected outright, arriving through a surface that shows you characters instead of records. One more reason the review surface, not the workflow around it, is the constraint.
What I want out of the write path
To see the record. That’s the whole ask, and it’s why rendered document review exists in our own reviewer (disclosure: I work on Pyor). Any renderable file in a PR gets a toggle between the source diff and a rendered preview, the default for Markdown and MDX (a Source button brings back the raw diff), with a switcher for the head version, the base version, or the diff. The rendered diff highlights inserts and deletes at word level inside a block, so a changed table cell reads like a changed cell instead of a pile of pipes. Comments go on the rendered document itself, and comments left on the diff show up there too, so a thread doesn’t vanish when you switch views.


None of that gives you constraints back, and it shouldn’t pretend to. Referential integrity is a CI problem, schema drift is a parser problem, and both deserve real tooling. But the repo-as-database pattern is a good pattern: cheap, versioned, reviewable, and readable by the agents that increasingly depend on it. The weak link was never the idea. It’s that the write path shows you syntax when the thing you’re approving is a record.
Frequently asked questions
What does using markdown as a database actually mean?
It means keeping structured prose in a git repo instead of an application database. Files are records, directories act like tables, YAML frontmatter acts like a schema, git history is the audit log, and pull requests are the write path. Teams land here for docs, ADRs, runbooks, specs, prompt libraries and agent instruction files, because the repo already does review and versioning.
Where does the markdown as a database analogy break down?
At every guarantee a real database gives you. No constraints, so a typo in a frontmatter field is still a valid file. No referential integrity, so renaming a heading silently breaks every link pointing at it. No transactions, so a change spanning ten files can land half applied. And grep is not a query engine.
How should teams review changes to a markdown store?
Treat frontmatter changes like schema migrations: say which fields moved, and check the existing records still parse. Run a link checker in CI so broken cross references fail the build instead of the reader. And read the rendered record rather than the raw diff, because tables and links are the parts most likely to break and the parts a source diff hides.