Using with Obsidian

How to open an existing Obsidian vault in OpenKnowledge, which markdown syntax carries over, and where the two differ.

OpenKnowledge and Obsidian are both editors over a folder of plain markdown — the files are the database. So there is nothing to import or convert: point OpenKnowledge at your existing vault and your notes, links, tags, and frontmatter come across as they are.

OpenKnowledge works directly on your markdown files — it never moves, renames, or rewrites them just for opening a vault. It keeps its own state in a .ok/ directory and ignores Obsidian's .obsidian/ folder, so your Obsidian setup stays exactly where it is.

Open your vault

MacOS Desktop app

Open OpenKnowledge, choose Open folder on disk, and select your existing vault folder, then proceed through the Setup screen. OpenKnowledge uses the folder in place — it doesn't copy or move your notes.

Linux, Windows, Intel Mac

Install the ok CLI, cd into your vault, and run ok init && ok start --open.

What carries over

Most of what you write in Obsidian renders and round-trips in OpenKnowledge unchanged. Existing syntax is preserved byte-for-byte when a file is saved, so opening a vault is non-destructive.

Obsidian syntax	Example	In OpenKnowledge
Wiki links	`[[Page]]`, `[[Page\|alias]]`, `[[Page#Heading]]`	Resolved to the target doc; feed backlinks and the graph. Preserved as written.
Markdown links	`[text](./page.md)`	Fully supported and the recommended form for new links. Wiki links keep working as a superset.
YAML frontmatter	`---` block at the top	Open-shape — any keys. `aliases`, `tags`, `cssclasses`, dates, and lists are preserved. Edit them in the Properties panel.
Tags	`#tag`, or `tags:` in frontmatter	Both forms are indexed and searchable.
Callouts	`> [!note]`, `> [!warning]`, foldable `> [!tip]-`	Rendered with icons. 15 types including Obsidian's set (`success`, `question`, `failure`, `bug`, `example`, `quote`, …); aliases like `summary` / `tldr` fold to `abstract`.
Highlights	`==highlighted==`	Rendered as a highlight mark.
Comments	`%%hidden note%%`	Hidden in the editor, kept in the file. (`<!-- -->` works too.)
Math	$inline$ , `$$block$$`	Rendered as LaTeX math.
Mermaid	```mermaid fenced blocks	Rendered as diagrams.
Footnotes	`[^1]` with `[^1]: …`	Supported, including named footnotes.
Asset embeds	`![[image.png]]`, `![[file.pdf#page=3]]`	Images and PDFs render inline. See Assets and embeds.

Where the two differ

A handful of Obsidian features are not supported, or behave differently. None of them corrupt your files — the syntax is preserved on disk; it just isn't interpreted the same way.

Feature	What happens in OpenKnowledge
Note transclusion — `![[Some Note]]` to embed another note's content	Renders as a working link to the note rather than inlining its content — the target is one click away, just not pulled in. Only file assets (images, PDFs) embed inline; documents do not transclude.
Block references — `^block-id` and `[[Page#^block-id]]`	Not recognized. Heading links (`[[Page#Heading]]`) resolve, but a `#^block-id` fragment won't point at a block.
The `.obsidian/` folder	Ignored. OpenKnowledge does not read Obsidian's theme, hotkeys, plugin config, or vault preferences. Configure OpenKnowledge in `.ok/config.yml` instead.
Community plugins	Don't run. OpenKnowledge is a separate app, not an Obsidian plugin host. Many features people reach for plugins for in Obsidian — callouts, tags, math, Mermaid, embeds — are built in here, but plugin-specific syntax (for example Dataview queries) is left as plain text.
Canvas (`.canvas`) and Bases (`.base`)	Open in a read-only text view rather than as interactive canvases or bases. They're still indexed and linkable from your notes.

OpenKnowledge's defaults match Obsidian's defaults — wiki links and attachments stored alongside your notes — so a standard vault works as-is. There's no migration step today; if you have a vault with heavily non-default settings, let us know.

Agent skills, built in

Getting an AI agent to work well inside an Obsidian vault usually means adding an agent-skills layer on top — a set of SKILL.md instructions that teach the agent your conventions and how to read and write the vault. OpenKnowledge builds that layer in, so there's nothing to bolt on:

A project skill is installed for you. ok init (or the desktop setup) drops in a project-local skill that teaches your agent OpenKnowledge's tools and conventions — no hand-written CLAUDE.md to maintain.
Agents get first-class tools, not just file access. The MCP server gives any MCP-capable agent — Claude Code, Cursor, Codex, OpenCode — typed read / write / search / links tools over the same files, so edits are consistent, attributed, and keep your link graph healthy.