The @docmd/plugin-okf plugin generates an Open Knowledge Format (OKF) bundle for AI-agent consumption. OKF is a vendor-neutral, agent- and human-friendly standard for representing the metadata, context, and curated knowledge that modern AI systems need. The bundle sits next to your site (e.g. site/okf/) so agents can be pointed at it directly.

The plugin is enabled by default in 0.8.8 — no configuration is required. The bundle is generated on every docmd build.

What is OKF?

OKF is an open specification announced by Google Cloud in June 2026 that formalises the LLM-wiki pattern into a portable, interoperable format. The motivation:

OKF represents organisational knowledge as a directory of markdown files with YAML frontmatter, plus a typed manifest, an interactive graph viewer, and a machine-readable bundle summary. The three principles behind the design:

1. Minimally opinionated. OKF requires exactly one thing of every concept: a type field. Everything else (what types exist, what other fields to include, what sections the body has) is left to the producer.
2. Producer/consumer independence. A bundle hand-authored by a human can be consumed by an AI agent. A bundle generated by a metadata export pipeline can be browsed in a visualizer. A bundle synthesized by one LLM can be queried by another. The format is the contract; the tooling at each end is independently swappable.
3. Format, not platform. OKF is not tied to any specific cloud, database, model provider, or agent framework.

What you get

site/okf/
├── okf.yaml              ← typed manifest (bundle summary)
├── index.md              ← Karpathy-style catalog grouped by type
├── graph/                ← opt-in: only when `plugins.okf.graph: true`
│   ├── index.html        ← interactive force-directed viewer (open at /okf/graph/)
│   ├── graph.json        ← graph data (nodes + edges)
│   ├── graph.js          ← viewer runtime (vanilla, no CDN deps)
│   └── graph.css         ← viewer styles (theme-aware)
├── concepts/
│   └── <slug>.md         ← one markdown file per page
└── _meta/
    ├── bundle.json       ← JSON mirror of okf.yaml
    └── lint-report.txt   ← warnings produced during generation

Each concept file carries the OKF-required type field in frontmatter plus the original markdown body verbatim, so an agent can both navigate the manifest and read full pages.

Default behaviour

OKF is a core plugin in 0.8.8. The build auto-loads it and generates the bundle with sensible defaults:

• Default-locale only by default (the bundle contains pages in the default locale only; the default-locale files sit at the bundle root).
• Type inference — pages under /api/, /guides/, /reference/, /concepts/, /runbooks/, /datasets/, /metrics/, /tables/ are auto-classified; everything else falls back to concept.
• Full markdown in each concept file (the original page body is included, not just a frontmatter stub).

You do not need to add anything to docmd.config.json to get an OKF bundle. The plugin runs with empty options and uses all defaults.

Opting out

Three opt-out paths are supported:

{
  "plugins": {
    "okf": false
  }
}

{
  "plugins": {
    "okf": { "enabled": false }
  }
}

{
  "plugins": {
    "okf": { "capabilities": ["head"] }
  }
}

The last form uses the plugin trust model — the okf plugin declares capabilities: ['post-build']; if your config.plugins.okf.capabilities array does not include post-build, the plugin is loaded but its onPostBuild hook does not run. This matches every other core plugin.

Configuration

All keys are optional. Listed values are the defaults:

Example — custom output dir + custom default type

{
  "plugins": {
    "okf": {
      "outputDir": "knowledge",
      "defaultType": "doc",
      "warnOnMissingType": true
    }
  }
}

Example — multi-locale output (opt-in)

{
  "plugins": {
    "okf": { "localeStrategy": "folders" }
  }
}

site/okf/                    ← default locale (en) at bundle root
├── okf.yaml
├── index.md
├── concepts/<slug>.md
└── _meta/, graph/, ...

site/okf/ja/                 ← Japanese — nested under <locale>/
├── okf.yaml
└── concepts/<slug>.md

The default-locale files always sit at the bundle root so existing consumers don’t break. Only non-default locales get a <locale>/ subdirectory.

Per-page opt-out

Pages can opt out of the OKF bundle in two ways:

---
noindex: true   # also excludes from sitemap, llms.txt, etc.
---

---
okf: false       # only excludes from the OKF bundle
---

The first form (noindex: true) is the standard docmd opt-out that excludes a page from every downstream consumer (sitemap, search, llms.txt, OKF). The second form (okf: false) excludes only from OKF, so the page is still in the search index and the llms.txt summary but not in the OKF bundle.

Type resolution precedence

For every page the plugin picks a type with this precedence:

1. frontmatter.okf.type (nested) — explicit
2. frontmatter.<typeField> (top-level) — usually type:
3. frontmatter.okfType (legacy) — old alias
4. Path-prefix inference (e.g. /guides/foo → guide)
5. defaultType (with a warning if warnOnMissingType)

The path-prefix map covers guides/, api/, reference/, concepts/, runbooks/, datasets/, metrics/, and tables/. Any other path falls back to the defaultType (default: concept).

How agents consume the bundle

The OKF spec defines three “implementation surfaces” — the same bundle file can be consumed by any of them without translation:

• AI agent loader — point your agent at site/okf/index.md or any concept file under site/okf/concepts/. The YAML frontmatter gives the agent a typed index, the markdown body gives it the full content.
• Visualizer — open site/okf/graph/index.html in a browser (or visit /okf/graph/ on a hosted site). The force-directed graph shows the relationships between concepts based on internal markdown links. Requires plugins.okf.graph: true (off by default).
• Programmatic — read site/okf/_meta/bundle.json (or site/okf/okf.yaml) for a machine-readable manifest of every concept, with type, path, locale, version, and tags.

The bundle is also compatible with Google’s published reference implementations — see the OKF spec page for details.

When NOT to use OKF

• Public marketing sites with no AI-agent audience — the llms.txt plugin alone is sufficient. Use okf: false to disable OKF and avoid generating the bundle.
• Single-page projects — OKF shines for multi-page docs with cross-links. A one-page site has no graph to render.
• i18n with many locales — the default-locale-only default is intentional (one bundle for the primary language). If you need per-locale bundles, opt in via localeStrategy: 'folders', but the bundle size scales with locale count.

See also

• Open Knowledge Format — Google Cloud blog post — the spec announcement with full design rationale
• LLM Context Plugin — the complementary llms.txt plugin for AI-agent context
• Building AI-ready docs — broader guide on AI-agent consumption
• Structure for LLMs — how to organise content for machine consumption
• release notes 0.8.8 — context on the OKF plugin’s introduction