SlipItIn/.github/skills/okf-open-knowledge-format/references/conversion.md

Converting Sources to OKF

Guides for transforming existing knowledge into conformant OKF bundles.

---

From Notion Export

Notion exports as markdown with properties in YAML-like format.

Steps

1. Export from Notion as Markdown & CSV
2. Clean filenames — remove UUID suffixes (Page Name abc123def.md → page-name.md)
3. Map properties to frontmatter:

Notion Property	OKF Field
Type (select)	type (required)
Name	title
Tags (multi-select)	tags
Last Edited	timestamp
URL	resource

4. Convert links — Notion uses [Page Name](Page%20Name%20abc123def.md). Convert to clean relative paths: [Page Name](./page-name.md)
5. Remove Notion artifacts — empty toggle blocks, breadcrumb headers, cover image references
6. Add missing type field — if Notion had no "Type" property, ask the user what type to assign

Edge cases

• Notion databases: each row becomes a concept. Database title becomes the directory name.
• Nested pages: respect the hierarchy. Child pages go in subdirectories.
• Inline databases: flatten into a list in the parent concept's body.
• Notion formulas/rollups: drop them — they don't translate to static markdown.

---

From Obsidian Vault

Obsidian vaults are already close to OKF. Main differences: wikilinks and potentially missing type field.

Steps

1. Convert wikilinks to standard links:

   • [[Note Name]] → [Note Name](./note-name.md)
   • [[Note Name|Display Text]] → [Display Text](./note-name.md)
   • [[Note Name#Heading]] → [Note Name](./note-name.md#heading)

2. Ensure type field exists in every frontmatter block. Common mappings:

Obsidian pattern	Suggested OKF type
Daily notes	Log
MOC / index note	Convert to index.md (reserved file)
Permanent notes	Reference
Literature notes	Reference
Project notes	Playbook or domain-specific

3. Convert tags:

   • Inline #tag → move to frontmatter tags: [tag]
   • Nested #parent/child → flatten to tags: [parent, child] or keep as parent/child

4. Handle embeds:

   • ![[Note]] — convert to a regular link or inline the content
   • ![[image.png]] — keep as standard markdown image ![](./image.png)

5. Remove Obsidian-specific syntax:

   • %%comments%% → remove
   • > [!callout] → convert to blockquote or heading
   • Dataview queries → remove (dynamic, not portable)

What to keep as-is

• Standard markdown formatting (headings, lists, tables, code blocks)
• Existing YAML frontmatter (just add type if missing)
• Standard markdown links (already OKF-compatible)
• Mermaid diagrams (standard markdown fenced blocks)

---

From CSV / Spreadsheet

Each row becomes one concept document.

Steps

1. Identify column mapping:

Column role	Maps to
Primary identifier / name	Filename (slugified)
Category / kind	type field
Short description	description field
Tags / labels	tags field
URL / link	resource field
Last modified date	timestamp field
All other columns	Body content (as table or sections)

2. Generate one .md per row:

---
type: {category_column}
title: {name_column}
description: {description_column}
tags: [{tag1}, {tag2}]
timestamp: {date_column}T00:00:00Z
---

# {name_column}

| Field | Value |
|-------|-------|
| Column3 | {value} |
| Column4 | {value} |

3. Generate index.md from the full list:

# {Sheet Name}

- [{row1_name}](./{row1_slug}.md) - {row1_description}
- [{row2_name}](./{row2_slug}.md) - {row2_description}

4. Generate log.md with creation entry:

# Update Log

## {today_iso8601}
- **Creation**: Generated {N} concepts from spreadsheet import.

Edge cases

• Empty cells: omit the field entirely (don't write empty strings)
• Multi-value cells (comma-separated): parse into YAML list for tags
• Very long text cells: put in body as a section, not in frontmatter
• Duplicate names: append a disambiguator (e.g., widget-v1.md, widget-v2.md)