This is the twelfth post in the LocalPapa Notes dev-log series, and a long thread I've been brewing for several posts — the OKF knowledge pack. The fun part: this very blog is built, at heart, the exact same way as OKF. More on that below.
The problem: AI reads websites the hard way
When an AI agent wants to understand "what tools does LocalPapa have, and what does each do," it has to fetch your page's HTML. But that HTML is stuffed with navbars, ads, styles, tracking code — the actual "knowledge" is a small fraction; the rest is noise.
In 2026, Google Cloud released OKF (Open Knowledge Format) v0.1: a minimal open format — a stack of Markdown + YAML frontmatter files. Its claim is simple: pack an organisation's knowledge into a clean, interconnected Markdown map that AI can read directly, without parsing layout.
So we built LocalPapa a /okf/ knowledge pack, plus a root llms.txt as the AI entry point.
Don't hand-write — generate it
The most important decision: never hand-write those 50 Markdown files.
There are 38 tools, and the count keeps growing; hand-crafting is not only tedious but guaranteed to drift out of sync with the pages. So we wrote scripts/build_okf.py to extract automatically from existing assets:
- Categories and tool membership: parse
tool-category and tool-card in index.html.
- Each tool's English content: regex out the title, subtitle, steps and FAQs from the
'en' block of each tool page's _toolTranslations (handling backslash escapes).
- Canonical URL: from each page's
<link rel="canonical">.
- Related tools: from
.related-card hrefs, converted into ./slug.md relative links.
Add a tool? Just re-run the generator and the pack syncs itself. That's "single source of truth" — the content lives once, in the tool pages, and OKF is its projection.
Turning knowledge into a "graph"
OKF isn't just loose files — it's a knowledge graph. One .md per tool, frontmatter carrying type (OKF's only required field) plus title/description/resource/category/tags/timestamp; the body is How-to/FAQ/Related.
The key is the links: category files link to their tools, tools link back to categories, the root links to two indexes — 338 relative links woven into a graph in total (verified with 0 broken links after generation). An AI agent can navigate the whole site from any node, like walking a map.
One detail worth noting: timestamp uses a fixed build date, not "now." Otherwise content changes on every re-run and the --check idempotency test fails. Reproducibility is a baseline requirement for a generator.
A pit that eats your output: Jekyll
Here we hit a classic GitHub Pages pit. Pages runs Jekyll by default, and Jekyll, seeing a .md, auto-converts it to HTML and eats the YAML frontmatter — which is exactly OKF's most important part.
The fix is one word: put an empty .nojekyll file at the repo root. It tells Pages "don't run Jekyll," so /okf/**.md is served as raw Markdown (frontmatter included). A 0-byte file decides whether the whole knowledge pack stands.
Three entry points coexisting, complementing not replacing
We didn't use OKF to replace what existed; we let it coexist with the other "machine-facing" formats:
llms.txt (root): the AI entry point, listing tools and pointing to the OKF pack.robots.txt: an added pointer note.index.html: a rel="alternate" type="text/markdown" hint.- The existing schema.org JSON-LD stays.
OKF, llms.txt and JSON-LD each serve different readers; all three coexist.
Honestly: this is a forward-looking bet
Let's be straight — OKF won't bring you traffic today. The spec is new, adopters are few, and AI citing it isn't yet common.
So why do it? Because its cost is tiny (auto-generated, re-run to sync on new tools) and the direction is right: AI search and GEO (generative engine optimisation) are taking shape, and "letting agents read your site directly" will sooner or later be table stakes. It's a forward-looking, low-cost, no-bet-the-farm investment — and we honestly acknowledge its limited short-term ROI. Building in public means stating even "this hasn't paid off yet" clearly.
And then, this blog you're reading…
Back to the opening. LocalPapa Notes uses the exact same philosophy as OKF.
Each post is a Markdown file, and a build_blog.py generator turns it into site-consistent HTML, a listing page and an RSS feed. Adding a post means dropping in a .md and re-running — identical to OKF's "add a tool, re-run." Markdown as single source of truth, the generator does the projection, --check guarantees idempotency: once this pattern proved itself, it gets reused across the project again and again.
OKF isn't just a feature; it turned "separate content from presentation, connect them with a generator" into a team habit.
What we learned
- Don't make AI parse your HTML — proactively hand it clean knowledge. OKF/llms.txt is that proactivity.
- Whatever can be generated, never hand-craft. 38 tools, 338 links — only a generator keeps it maintainable.
- Idempotency is a generator's lifeblood. A fixed timestamp and
--check make "re-run" always safe.
- A 0-byte
.nojekyll can be the make-or-break. Understand the platform's default behaviour first.
- Label forward-looking bets honestly. Low-cost, future-facing, but no near-term return — say all three.
The same question, a new audience
The previous eleven posts asked "can this be done in the browser." This one asks a different audience: when the reader is no longer just a human but an AI agent, is our site ready to be "understood"?
Our answer: use one generator to turn the whole site's knowledge into a map an agent can walk into.
In the next dev log, we step into a whole new domain — building metaphysics/divination as 100% browser-local, honestly-labelled services (starting with Zi Wei Dou Shu). Want to follow the series? Bookmark LocalPapa Notes.