okf-notebooks

Notebook format (OKF)

What a notebook looks like on disk

okf-notebooks stores notes in the Open Knowledge Format (OKF, okf.md, MIT): a directory of Markdown files with YAML frontmatter. The server writes OKF version 0.2. This page describes what a notebook looks like on disk. For the authoritative format definition see the OKF specification.

Layout 

<root>/                         one git repository
├── notebooks/
│   └── <slug>/                 one notebook = one OKF bundle
│       ├── index.md            manifest: okf_version, title, list of notes (generated by the server)
│       ├── log.md              append-only log of actions
│       ├── .okf/
│       │   ├── notebook.yaml   name, description, scope, preset, types, status
│       │   ├── okf-base.yaml   base vocabulary
│       │   └── templates/      per-type templates
│       ├── decisions/          one subdirectory per type
│       │   └── use-argocd.md   a note (concept): id /decisions/use-argocd
│       └── terms/
├── _proposed/                  notebooks waiting for a human decision
├── _archive/                   archived notebooks
├── .auth/tokens.json           token hashes (SHA-256)
├── .index/fts.sqlite           full-text index (rebuildable)
└── .comments/threads.sqlite    comment threads (back it up)

A note 

---
type: Decision
title: Use ArgoCD for deployments
description: Why the platform team deploys through ArgoCD.
tags: [adr, deploy]
sources: [https://argo-cd.readthedocs.io/]
status: draft
generated:
  by: claude-code/1.2.3
  at: '2026-11-10T14:39:13Z'
---
# Decision

Body in Markdown, at least 20 characters.
  • type, generated, status and verified are set by the server or a human, never by an agent.
  • status is draft, stable or deprecated; everything an agent writes starts as draft.
  • A note’s id is its path inside the notebook without the extension: /decisions/use-argocd.

Because the notebooks are plain files, you can read them with any editor, review them with git diff, and roll back with git revert. Edits made outside the server can be audited with okf-notebooks validate. Rules and fields: notes and verification, types: presets.