The @docmd/plugin-okf plugin builds an Open Knowledge Format (OKF) knowledge bundle during static compilation. OKF is an open, vendor-neutral specification for structuring documentation metadata, concept graphs, and domain context for AI agents and LLM tool chains.

The plugin is enabled by default. OKF bundles are placed in site/okf/ during every site compilation.

Architectural Overview

OKF formalises knowledge architecture into a portable directory structure containing YAML manifests, Markdown concept files, and visual force-directed graph assets.

Design Principles

1. Minimal Structural Requirements: Every concept entry requires only a type field.
2. Producer/Consumer Independence: Human-authored Markdown files compile into standard schemas queryable by arbitrary LLM frameworks.
3. Vendor Neutrality: Independent of specific cloud providers, model hosts, or vector database engines.

Generated Output Assets

Compilation produces the following directory tree:

site/okf/
├── okf.yaml              ← Manifest summary file
├── index.md              ← Concept catalog grouped by type
├── graph/                ← Interactive graph assets (when graph: true)
│   ├── index.html        ← Force-directed graph visualiser
│   ├── graph.json        ← Graph nodes and edges
│   ├── graph.js          ← Standalone graph runtime
│   └── graph.css         ← Theme-aware styling
├── concepts/
│   └── <slug>.md         ← Individual concept Markdown files
└── _meta/
    ├── bundle.json       ← JSON mirror of okf.yaml
    └── lint-report.txt   ← Build linting reports

Default Build Behaviour

The OKF plugin is loaded automatically during compilation:

• Default-Locale Scope: Emits concepts for the primary language at the bundle root.
• Automatic Type Inference: Classifies paths under /api/, /guides/, /reference/, /concepts/, /runbooks/, /datasets/, /metrics/, and /tables/ into typed concepts.
• Verbatim Markdown: Copies page content and frontmatter into concept files.

Opting Out

Disable OKF bundle generation in docmd.config.json:

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

Alternatively, set enabled: false:

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

Configuration Options

Configure OKF bundle parameters in docmd.config.json:

Global Configuration Example

{
  "plugins": {
    "okf": {
      "outputDir": "knowledge",
      "defaultType": "concept",
      "graph": true
    }
  }
}

Multi-Locale Folder Strategy

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

Output directory structure:

site/okf/                    ← Default locale (root)
├── okf.yaml
├── index.md
└── concepts/

site/okf/de/                 ← German locale (nested)
├── okf.yaml
└── concepts/

Excluding Pages from OKF

Exclude specific pages using frontmatter flags:

---
title: "Internal Operations Note"
okf: false # Excludes page exclusively from OKF bundles
---

To exclude a page globally across sitemaps, search, LLM files, and OKF, set noindex: true.

Concept Type Resolution

The plugin determines concept types using top-down precedence:

1. frontmatter.okf.type — Nested explicit declaration.
2. frontmatter.type — Top-level explicit declaration.
3. frontmatter.okfType — Legacy alias.
4. Path-prefix inference: Automatic mapping for /guides/, /api/, /reference/, /concepts/, etc.
5. defaultType fallback ('concept').