Migrate Existing Documentation¶

Convert an existing documentation folder into a validated OKF bundle.

1. Scaffold the bundle structure¶

okf-schema init my-docs

2. Move markdown files into namespaced folders¶

OKF-Schema requires concepts to live in subdirectories. Reorganize:

# Before
my-docs/
  README.md
  setup.md
  api.md

# After
my-docs/bundle/
  guides/
    setup.md
  reference/
    api.md

3. Add frontmatter to each concept¶

Every .md file needs YAML frontmatter with at least a type field:

---
type: guide
title: Setup Guide
description: How to install and configure the project.
tags: [setup, installation]
---

# Setup Guide

...existing content...

Use a script to bulk-add frontmatter:

for f in my-docs/bundle/**/*.md; do
  if ! grep -q "^---" "$f"; then
    echo -e "---\ntype: concept\n---\n\n$(cat "$f")" > "$f"
  fi
done

4. Write schemas for your types¶

Create _schema/guide.schema.yaml, _schema/reference.schema.yaml, etc. See Write a Custom Schema for details.

5. Validate and iterate¶

okf-schema validate --path my-docs/bundle

Fix errors, add missing fields, and repeat until the bundle is conformant.

6. Generate index files¶

okf-schema index --path my-docs/bundle

This creates index.md files in every directory, giving you a navigable table of contents.