Learning guide
OKF Tutorial
Learn Open Knowledge Format step by step: from understanding the basics to generating, validating, and publishing production-ready knowledge bundles.
Step 1: Understanding OKF
Open Knowledge Format (OKF) is a lightweight way to package knowledge as Markdown files with YAML frontmatter. Each OKF file represents one concept, API endpoint, dataset, metric, or piece of documentation.
The frontmatter contains structured metadata (type, title, description, tags), while the Markdown body contains the actual knowledge content. This makes OKF both human-readable and machine-parseable.
Step 2: Validating Your First Document
The OKF Validator checks your document structure and provides an OKF Score. Start with a template, paste it into the validator, and see how it scores.
The validator shows three key metrics: Structure (frontmatter completeness), Coverage (content depth), and Connectivity (links and references). Use the feedback to improve your document.
Step 3: Generating OKF from Websites
You can automatically generate OKF documents from existing web pages. The Website to OKF Generator supports three modes: single URL, Sitemap (up to 20 pages), or URL list.
For batch generation, the tool creates a complete bundle with index.md, generation logs, validation reports, and individual concept files. You can preview the first page before processing all URLs.
Step 4: Improving OKF Score
A high OKF Score means better-structured, more discoverable knowledge. Here's how to improve each dimension:
- Structure (40 points): Add all frontmatter fields: type (10pts), title (10pts), description (10pts), id (5pts), tags (5pts).
- Coverage (30 points): Write detailed content: non-empty body (10pts), 100+ words (10pts), 300+ words (5pts), use headings (5pts).
- Connectivity (30 points): Add links: source_url (10pts), internal links (10pts), 3+ internal links (10pts).
Aim for 90+ points for production-ready documents. Use the Live Badge to monitor your deployed OKF documents continuously.
Related OKF tools and guides
FAQ
Do I need to know Markdown?
Basic Markdown knowledge helps, but OKF is simple: just add YAML frontmatter at the top of a Markdown file. The tutorial covers everything you need.
How long does it take to learn OKF?
You can create your first valid OKF document in 5-10 minutes. Understanding all features and best practices takes about 30 minutes.
Where should I start?
Start with Step 1 to understand what OKF is, then use the Validator in Step 2 to practice. Steps 3-4 show you how to generate and improve OKF documents.