Beyond Flat Reads: How OKF and Two Decades of Markdown Build Machine-Readable Maps
Our current web interaction is surprisingly shallow. When an AI agent visits your website, it performs a "flat read"—scouring pages one by one, losing the implicit connections that make your content a cohesive body of knowledge. We’ve treated websites as collections of HTML documents, but for agents, that perspective is becoming a bottleneck.
Google’s recently published Open Knowledge Format (OKF) offers a different approach, transforming a body of knowledge into a directory of linked markdown files. While ostensibly designed for internal corporate data, its implications for the public web are profound. When combined with the nearly twenty-year history of Markdown as a machine-readable format, OKF points toward a future where websites aren’t just collections of pages, but structured knowledge graphs traversable by any capable agent.
The Anatomy of the Open Knowledge Format (OKF)
At its simplest, OKF is a method for representational clarity. Published by Google on June 13, 2026, it organizes information as a directory of Markdown files supplemented by YAML frontmatter. Google describes this structure in three pithy phrases: “just markdown,” “just files,” and “just YAML frontmatter.”
Each concept—whether it’s a metric, a runbook, a product, or a foundational idea—is captured in its own Markdown file. The YAML frontmatter acts as a queryable metadata layer, housing fields like type, title, description, resource links, tags, and timestamps. Crucially, the Markdown body allows for content explanation, while ordinary Markdown links connect these documents. As Google notes, this simple act of linking turns a static directory into a graph of relationships.
This structure avoids the complexity of heavy runtimes or SDKs. It prioritizes accessibility—both for humans and, more importantly, for the machines ingesting the information. While currently focused on locked-away internal company knowledge, the experiment highlights a structural necessity that public websites have largely ignored: the importance of explicit, queryable relationships between ideas.
Replacing Flat Page-Reads With Knowledge Graphs
Today’s web content architecture is overwhelmingly flat. Even when sites provide a machine-readable mirror—like Cloudflare’s Markdown at the edge or the increasingly common llms.txt—this remains a "page-for-page" copy. It captures the content of each page, but it fails to communicate the context.
A knowledge graph, by contrast, preserves the relationship layer. When pages link together, an agent learns more than just the definition of individual concepts; it learns how, for example, a framework sits atop a specific capability, or how a narrower goal relates to a broader strategy. These relationships are often implicit to human readers but invisible to agents parsing HTML. OKF provides a lightweight, off-the-shelf mechanism to make these relationships explicit. By structuring content via standard Markdown and YAML, sites can offer agents a traversable map rather than a pile of disparate documents, enabling a far more sophisticated understanding of the underlying website knowledge.
Experimenting With OKF: A Practical Perspective
The promise of OKF isn’t just theoretical; it can be implemented with minimal overhead. Implementing an OKF bundle essentially involves auditing your core concepts—defining what matters, understanding the hierarchy, and mapping the connections.
In practice, a concept file, such as one detailing a "Framework," would contain its metadata YAML up top, followed by a concise explanation in the body. The most critical component is the set of bracketed Markdown links at the bottom—the graph's infrastructure. These links dictate the ontology, allowing an agent to traverse from a broad concept directly to its related components. This exercise has a secondary, unexpected benefit: it forces authors to state plainly what their website actually knows. It surfaces gaps in both content and conceptual clarity that are easily missed when writing conventional HTML pages. If your ideas aren't clear enough to map, they likely aren't clear enough to communicate to an agent.
The Maintenance Tax of Parallel Layers
While compelling, an OKF bundle represents a second copy of what your website already says. And herein lies the unavoidable maintenance tax. Just like maintaining an llms.txt file or a Markdown mirror, your OKF bundle must remain in sync with your live website. If the underlying site changes and the bundle is not updated, the representation the agent reads becomes inaccurate.
This is not a failure of the OKF format itself, but the reality of any parallel, machine-readable layer. The version an agent reads is only as accurate as the operational discipline behind it. For organizations, this means treating machine-readable bundles not as "set-and-forget" files, but as core infrastructure that requires parity updates alongside the human-facing pages. Discipline is the price of agent-readiness.
Markdown: A Decades-Old Machine-Readable Foundation
The core technology underneath OKF—Markdown—is hardly a new concept, though its role has evolved drastically. Created by John Gruber in 2004 with Aaron Swartz acting as a beta-tester, Markdown’s original goal was purely human-readable plain text that could convert cleanly to HTML. Its design was brilliant in its simplicity: legible without rendering, yet ready for the web.
Two decades later, this exact property has made it the undisputed standard for the machine-readable web. From GitHub and Reddit to the internal knowledge bases of major AI companies and the chat boxes of current AI tools, Markdown has won by remaining accessible. It has become a predictable, standardized substrate that machines can reliably parse. OKF is not inventing a new language; it is merely leveraging the existing, deep-rooted convergence of plain text formats that the web has been moving toward for twenty years. It is a refinement of how we use a tool already in our kit.
The Direction for Website Knowledge Graphs
It is essential to note that OKF is v0.1 and Google’s stated goal is internal knowledge. However, the direction it indicates—and the shape it provides—is invaluable for anyone thinking about the agentic web.
We may see a future where identity files (like current iterations of llms.txt) evolve into full-fledged knowledge graphs. The map could become the canonical layer, with human-facing HTML pages becoming just one, curated rendering of that structured data. Agents, in turn, would query this map as a primary source, abandoning the costly process of scraping HTML pages individually. While this vision remains speculative and agent behavior has yet to fully catch up, the structural shift itself is inevitable. Web architecture is moving away from the isolated page toward the linked entity, and the tools to make that move are already here in our text editors.
Closing Observations on Structuring Knowledge
OKF is the news of the week, but the foundational technology—plain, linked text—has been consistent since 2004. What Google has added to the conversation is a standard and a name.
Whether or not the current OKF spec becomes a widely adopted standard for public websites, the exercise it prompts is necessary. If you want to see where your website stands, take thirty seconds: paste a key page into a text editor and strip the formatting. If the links don't explain how the ideas relate to the broader context of your site, you are relying on flat reads. Bridging that gap—through OKF or simply more structured, deliberate linking—is the foundational work required for making a website truly accessible to an AI-driven future. The knowledge graph is finally landing on our doorstep; it’s time to start mapping it.