From 2a871b2ae3ac9a35cd4a226146ae339f8ab55f31 Mon Sep 17 00:00:00 2001 From: serafin-garcia Date: Thu, 25 Jun 2026 16:01:19 -0700 Subject: [PATCH] docs(open-knowledge): add "Supporting the Open Knowledge Format" workflow guide (#2141) * docs(open-knowledge): add Supporting the Open Knowledge Format workflow guide Add a docs-site workflow guide for the `okf` starter pack: what `ok seed --pack okf` scaffolds (concepts/references/notes folders with per-folder templates, plus reserved index.md/log.md), and how it produces a knowledge base conformant with Google's Open Knowledge Format without enforcing anything. Registered in the Workflows section meta.json. * docs(open-knowledge): tighten template note, drop ok-init bullet --------- GitOrigin-RevId: 9c90c56364c4d994d1e490ccf9b0de4948af89a5 --- docs/content/workflows/meta.json | 2 +- .../supporting-open-knowledge-format.mdx | 47 +++++++++++++++++++ 2 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 docs/content/workflows/supporting-open-knowledge-format.mdx diff --git a/docs/content/workflows/meta.json b/docs/content/workflows/meta.json index 7a8fe1e35..385a15e64 100644 --- a/docs/content/workflows/meta.json +++ b/docs/content/workflows/meta.json @@ -1,5 +1,5 @@ { "title": "Workflows", "icon": "LuWorkflow", - "pages": ["karpathy-llm-wiki", "entity-vault"] + "pages": ["karpathy-llm-wiki", "entity-vault", "supporting-open-knowledge-format"] } diff --git a/docs/content/workflows/supporting-open-knowledge-format.mdx b/docs/content/workflows/supporting-open-knowledge-format.mdx new file mode 100644 index 000000000..745da5863 --- /dev/null +++ b/docs/content/workflows/supporting-open-knowledge-format.mdx @@ -0,0 +1,47 @@ +--- +title: Supporting the Open Knowledge Format +description: Scaffold a knowledge base that is conformant with Google's Open Knowledge Format (OKF) from the first commit — without enforcing anything. +--- +Open Knowledge ships a starter pack named **`okf`** that scaffolds a knowledge base **conformant with Google's [Open Knowledge Format (OKF)](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) from the first commit** — without enforcing anything. You get a portable, OKF-ready bundle out of the box, and you stay free to author however you like. + + + **OKF here means Google's Open Knowledge _Format_** — a vendor-neutral file-format spec (a directory of markdown files with YAML frontmatter), announced by Google Cloud in June 2026. Read the [OKF v0.1 spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md). + + +## What the pack seeds + +Run it with `ok seed --pack okf`. It scaffolds: + +| Path | Purpose | Template | +|---|---|---| +| `concepts/` | Durable ideas and definitions | `concept` | +| `references/` | External sources and citations | `reference` | +| `notes/` | Working notes and observations | `note` | +| `welcome.md` | A real typed concept, so a strict OKF consumer has something to accept | — (seeded file) | +| `index.md` | Reserved OKF navigation hub | — (reserved) | +| `log.md` | Reserved OKF change history | — (reserved) | + +Each of the three content folders (`concepts/`, `references/`, `notes/`) ships its **own template**, so new docs start with the right `type` and section skeleton already in place — you never hand-set the frontmatter. The conventions also ship as a project-local skill (`open-knowledge-pack-okf`) installed alongside the seed, so your agent learns the pack's discipline without a hand-written `CLAUDE.md`. + +## Conformance is pre-populated, not enforced + +This is the key design decision. OKF asks exactly one thing of every **non-reserved** document: a **non-empty `type`** in its frontmatter. Reserved `index.md` / `log.md` stay frontmatter-free, and links are standard markdown. + +The pack bakes those habits into the seeded content and documents them — but it changes nothing about how Open Knowledge itself behaves: + +- Open Knowledge's native frontmatter schema stays **open-shaped**. +- Nothing is **linted** for OKF conformance. + +So three habits are all it takes to keep the KB handable to a strict OKF consumer as it grows: + +1. Every non-reserved doc carries a non-empty `type`. +2. `index.md` / `log.md` stay lowercase and frontmatter-free. +3. Links use standard markdown (`[text](./path.md)`). + +Open Knowledge also accepts `[[wiki-link]]` shorthand as a native superset, and the OKF export normalizes it to standard links — but seeded content uses standard links so the bundle is conformant as-is. + +## Further reading + +- **[Open Knowledge Format spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)** — the canonical OKF v0.1 specification (Google Cloud). +- **[`STARTER_PACKS` registry](https://github.com/inkeep/open-knowledge/blob/main/packages/server/src/seed/starter.ts)** — canonical source for the `okf` pack content. +- **[Karpathy's LLM wiki workflow](./karpathy-llm-wiki.mdx)** and **[Entity vault workflow](./entity-vault.mdx)** — other starter-pack-driven workflows in Open Knowledge.