Google's Open Knowledge Format Skips the Hardest Part: Your PDFs

This week Google Cloud published the Open Knowledge Format (OKF), and my corner of the internet hasn’t stopped arguing about it since. If you missed it: OKF is a way to store a body of knowledge as a folder of linked Markdown files, each with a little YAML header on top (a type, a title, some tags). Agents read the files, follow the links, and answer from real, curated context instead of guessing.

I think OKF is basically right about the thing that matters. But there’s a quiet assumption sitting underneath the whole spec, and almost nobody in the thread is saying it out loud. So I will.

Disclosure: I build pdfmarkdown.app, an in-browser PDF→Markdown converter, so I have an obvious stake in the “your knowledge should be Markdown” argument. I’ve tried to keep the take honest and the claims checkable. Test anything here yourself.

The two reactions everyone had

Watching the replies roll in, the response split almost perfectly in two.

The first half: “isn’t this just a wiki?” And, well, kind of. A directory of cross-linked Markdown files is not a new invention. What’s new is the consumer. A wiki was built for a human to click through. OKF is built so an agent can walk fifteen files in one pass without getting bored or forgetting a cross-reference. Same artifact, different reader. That reframe is small but it’s real.

The second half, and the louder one: “why would I hand Google more of my data?” This one’s worth answering because the answer is the best part. You’re not handing Google anything. OKF is just Markdown files that live on your own disk or your own git repo. You could point a fully local LLM at them and Google never sees a byte. The format is the opposite of lock-in, and that’s the cleverest thing about it.

That second point is the one I want to pull on, because it’s exactly how I already think about documents: if you want AI to read something, the format should be plain, portable, and yours. OKF says that out loud for org knowledge. I’ve been saying it about the PDF on your hard drive.

The assumption nobody’s naming

Here’s what the spec quietly takes for granted. Every OKF example starts from knowledge that’s already clean text: a table schema, a metric definition, a runbook someone typed into a Markdown file. The hard problem OKF solves is organizing that knowledge so an agent can navigate it.

But that’s not where most knowledge lives.

Walk into any real company or any researcher’s folder and the knowledge isn’t sitting in tidy .md files waiting to be linked. It’s in a 90-page vendor contract. A scanned lab report. A dense academic paper with two columns and a wall of equations. A quarterly deck exported to PDF. The actual knowledge, the stuff you’d want an agent to read, is locked inside documents that were designed to be printed, not parsed.

OKF assumes the Markdown already exists. For most people, producing that Markdown is the whole job. The diagram up top is the shape of it: OKF lives on the right, where the files are already clean. The expensive, ignored step is everything to the left, turning the PDFs, scans and papers into clean Markdown in the first place.

Why “just convert the PDF” is harder than it sounds

If the missing step is “turn the PDF into Markdown,” you might assume that’s solved. Drop it into any converter, get Markdown out, done.

It isn’t, and it’s worth knowing exactly where it breaks, because these are the same five places that wreck an OKF bundle the moment you feed it a real document:

• Scanned pages are just photos. No text layer at all. Without OCR, the converter hands back an empty file and your agent confidently makes things up about a document it never actually read.
• Multi-column pages scramble. A two-column paper gets stitched left-line then right-line, so the sentences interleave into nonsense. The reading order, the one thing Markdown is supposed to make explicit, comes out wrong.
• Tables collapse. Rows and columns flatten into a run-on line. The number that lived under “2024” is now floating next to a label from a different row. In an OKF file that’s supposed to be the authoritative schema, that’s not a typo, it’s a lie.
• Formulas turn to gibberish. E = mc² becomes E mc2, subscripts drift, and the equation a paper is about becomes unreadable.
• Figures vanish. Charts and diagrams get dropped, or at best pulled out as a bare image with no caption, so the meaning is gone even when the pixels survive.

A clean OKF file built on a broken conversion is worse than no file at all, because it looks authoritative. The agent trusts it. That’s the trap.

What “OKF-ready” Markdown actually requires

So if you’re going to build any of this, OKF bundle or RAG pipeline or an Obsidian vault you point an agent at, judge your converted Markdown on the parts that carry the meaning, not on whether the first paragraph looks fine. Five checks:

1. Tables survived as real rows and columns, not a flattened blob.
2. Formulas survived as readable math, not E mc2.
3. Scanned pages were recognized, or at least flagged honestly instead of returned as empty.
4. Reading order is correct on multi-column layouts.
5. Figures made it in, ideally with a caption that preserves what they meant.

This is the bar I hold pdfmarkdown.app to. It runs in your browser, shows you the original PDF and the Markdown side by side so you can verify those five things before you trust the output, and when a page is genuinely unparseable it tells you up front instead of faking it. It’s a floor I can show you, not a “perfect conversion” promise, because nobody in this space can honestly make that one yet.

If you want the longer version of why PDFs are so hostile to AI in the first place, I wrote that up separately in why AI can’t read your PDFs, and compared the main converters honestly in the best PDF to Markdown tools.

The part OKF gets exactly right

I don’t want this to read as a knock on OKF. It gets the big call right, and the big call is this: Markdown is becoming the default format for handing knowledge to AI. Plain text, explicit structure, no proprietary container, readable by a human and an agent alike. Models were trained on mountains of it. It greps. It diffs. It lives in git. A PDF does none of that.

And the privacy instinct in those replies is the same one I build around. The reason OKF being “just files on your disk” matters is that your knowledge shouldn’t have to be uploaded to anyone’s server to be made AI-readable. That work can happen on your own device. It’s why my converter runs in the browser and never sends your file anywhere. Same worldview, one step earlier in the pipeline.

OKF drew the map for where org knowledge should end up. The honest footnote is that most of your knowledge starts a long way from there, sitting in PDFs, and somebody has to make that trip clean before any of the agent magic works.

The short version

• OKF is right: Markdown is the format for feeding knowledge to AI, and keeping it as local files (not a vendor’s database) is the smart part.
• OKF assumes the Markdown already exists. For most people, most knowledge is trapped in PDFs, scans and papers first.
• Converting that cleanly is the real work, and it breaks in five predictable places: tables, formulas, scans, reading order, figures. A clean-looking file built on a broken conversion is worse than none, because the agent trusts it.

If you’ve got a PDF you want to make agent-readable, the fastest way to see what I mean is to run one through it and watch the five breakpoints yourself. Try it on a real document at pdfmarkdown.app (it’s in your browser, your file never leaves your machine), and check the tables and formulas before you trust a word of the output. That habit, verify the hard parts first, is the one thing that’ll save you whether you’re building an OKF bundle, a RAG index, or just a smarter notes vault.