How to Convert Existing Documentation to OKF Format

Conversion Overview

The Open Knowledge Format is designed to be easy to adopt — if you already have markdown documentation, you're most of the way there. OKF bundles are just markdown files with YAML frontmatter, organized into a standard directory structure. This guide covers four methods for converting existing documentation into OKF format, from fully automated to completely manual.

Method 1: Automated Conversion with OKFy

OKFy is the most popular automated conversion tool for the OKF ecosystem. It takes any directory of markdown files and transforms them into a properly structured OKF bundle.

Installation & Usage

# Install OKFy
npm install -g okfy
# or
pip install okfy

# Convert a docs directory to an OKF bundle
okfy convert ./my-docs/ ./my-okf-bundle/

# Output: my-okf-bundle/
# ├── index.md       (auto-generated with frontmatter)
# ├── SPEC.md        (describes bundle structure)
# └── concepts/      (your docs, reorganized)
#     ├── getting-started.md
#     ├── api-reference.md
#     └── ...

What OKFy Does

• Scans your directory for markdown files
• Generates index.md with YAML frontmatter (name, description, okf_version)
• Creates SPEC.md describing the bundle contents
• Organizes files into concepts/ directory
• Adds frontmatter to each concept file (title, description, type)
• Generates a bundle.json manifest for machine readability

Method 2: Convert Obsidian Vaults with okf-loom

If you maintain an Obsidian vault, okf-loom converts it into an OKF bundle while preserving your wiki links, tags, and frontmatter. This is the fastest way to make your personal knowledge base available to AI agents.

Usage

# Convert an Obsidian vault to OKF
okf-loom convert ./my-vault/ ./my-okf-bundle/

# Options:
# --preserve-tags     Keep Obsidian tags as OKF tags
# --flatten-links     Convert wiki links [[link]] to OKF cross-references
# --add-frontmatter   Generate YAML frontmatter for all notes

okf-loom handles Obsidian-specific features like [[wiki links]], #tags, and nested folder structures, mapping them to OKF's concept-based architecture.

Method 3: Manual Conversion

For small documentation sets or when you want full control, manual conversion is straightforward:

my-okf-bundle/
├── index.md
├── SPEC.md
└── concepts/
    └── ...your markdown files here

---
name: My Knowledge Bundle
description: A curated collection of domain knowledge
version: 1.0.0
okf_version: "0.1"
tags: [my-domain, knowledge-base]
---

---
title: Getting Started
type: guide
tags: [tutorial, beginner]
---

Content of your documentation page...

Method 4: Agent-Assisted Conversion

AI coding agents can help automate the conversion process. Here's how to use them:

Using Claude Code or Cursor

Simply point your agent at a directory of documentation and ask it to convert to OKF format. Most coding agents understand the OKF specification and can generate valid bundles:

# Example prompt for Claude Code:
"Convert the documentation in ./docs/ into an OKF bundle at ./okf-bundle/.
Create index.md with proper frontmatter, organize files into concepts/,
and add YAML frontmatter to each concept file."

Using Gemini OKF Builder

The Gemini OKF Builder is specifically designed to create OKF-compatible bundles using AI. It can analyze existing content structures and generate well-organized OKF bundles automatically.

Using Git2OKF for Git-Based Repos

For repositories with extensive documentation, git2okf analyzes your git history and documentation files to create an OKF bundle that captures the evolution of your knowledge base.

Best Practices

• Start small: Convert your most important documentation first. You can always add more bundles later.
• Use consistent naming: Use kebab-case for concept file names (e.g., api-reference.md).
• Add YAML frontmatter: Every concept file should have at minimum a title and type field.
• Cross-link related content: Use OKF references to connect related concepts within your bundle.
• Validate after conversion: Always run the conformance checker after conversion to catch structural issues.
• Add the okf topic: Tag your GitHub repository with okf so BundleDex can discover it.
• Version your bundle: Update the version field in index.md when you make significant changes.

Frequently Asked Questions