@docmd/plugin-okf

@docmd/plugin-okf

Generates an Open Knowledge Format (OKF) bundle at build time so your documentation is consumable by AI agents — Gemini, Claude, GPT, Cursor, and any tool that speaks the vendor-neutral OKF spec.

OKF represents organisational knowledge as a directory of markdown files with YAML frontmatter, plus a typed manifest (okf.yaml), an interactive graph viewer, and a machine-readable bundle summary. The bundle sits next to your site (e.g. site/okf/) so agents can be pointed at it directly.

// docmd.config.json

{
  "plugins": {
    "okf": {
      // config options, okf is enabled by default
    }
  }
}

Part of the docmd documentation engine.

Output structure

site/okf/                          # Always emitted
├── okf.yaml                       # Typed manifest (bundle summary)
├── index.md                       # Karpathy-style catalog grouped by type
├── concepts/
│   └── <slug>.md                 # One markdown file per page
└── _meta/
    ├── bundle.json                # JSON mirror of okf.yaml
    └── lint-report.txt            # Warnings produced during generation

# Emitted only when `plugins.okf.graph: true`
├── graph/                         # Interactive viewer (open /okf/graph/)
│   ├── index.html                 # Force-directed graph viewer
│   ├── graph.json                 # Graph data (nodes + edges)
│   ├── graph.js                   # Viewer runtime (vanilla, no CDN deps)
│   └── graph.css                  # Viewer styles (theme-aware)

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.

Options

Option	Type	Default	Description
outputDir	string	'okf'	Bundle directory, relative to the site output.
bundleName	string	slugified config.title	Name used inside okf.yaml and the graph viewer title.
defaultType	string	'concept'	Type assigned to pages with no explicit type.
typeField	string	'type'	Frontmatter field name for OKF type.
warnOnMissingType	boolean	true	Emit a TUI warning for pages that fell back to defaultType.
includeFullMarkdown	boolean	true	Copy raw .md body into each concept file.
graph	boolean	false	Emit a graph/ subdirectory containing index.html + graph.js + graph.css + graph.json. Opt-in since 0.8.8 — the OKF spec does not require a viewer, and shipping extra files by default adds noise to a clean bundle. The viewer is reachable at /okf/graph/ without a custom filename, and fetches graph.json from the same directory at runtime, so file:// also works.
localeStrategy	'default-only' | 'folders' | 'mixed' | 'latest-only'	'default-only'	Single-locale by default (the bundle contains only pages in the default locale). Set to 'folders' to nest concepts by locale id when i18n is enabled, or 'mixed' / 'latest-only' for the other strategies.
versionStrategy	'folders' | 'mixed' | 'latest-only'	'latest-only'	Nest concepts by version id when versioning is enabled.
excludePatterns	string[]	[]	Additional glob patterns to skip on top of frontmatter.noindex / frontmatter.okf === false.

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
---

Type resolution precedence

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

1. frontmatter.okf.type (nested)
2. frontmatter.type (top-level)
3. frontmatter.okfType (legacy)
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/.

Documentation

See docs.docmd.io for full usage and API reference.

License

MIT