# From Obsidian (https://openknowledge.ai/docs/migrate/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](https://openknowledge.ai/docs/reference/core-concepts#the-file-system-is-the-database). This means that you can point OpenKnowledge at your existing vault and your notes, links, tags, and frontmatter work out of the box. > **Info** > > 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. To back out, `ok deinit` removes everything OpenKnowledge added to the vault and leaves your markdown untouched. ## Open your vault ### Desktop app (macOS, Windows, Linux) 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. ### Web app (any platform, including Intel Macs) Install the [ok CLI](https://openknowledge.ai/docs/reference/cli), `cd` into your vault, and run `ok init && ok start`. > **Info** > > Want to know exactly what these commands write to your machine — in your vault, your home directory, and your editors' configs? See [What OpenKnowledge writes to your system](https://openknowledge.ai/docs/reference/what-open-knowledge-writes). ## 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. Inside a table cell, escape the alias separator (see below). | | Markdown links | `[text](./page.md)` | Fully supported and the [recommended form](https://openknowledge.ai/docs/reference/core-concepts#links-and-backlinks) 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](https://openknowledge.ai/docs/features/editor#properties). | | 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%%` | Shown dimmed in the editor (Obsidian live-preview style), hidden in published output and cross-app paste, kept byte-for-byte 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](https://openknowledge.ai/docs/features/assets-and-embeds). | Inside a table cell, an aliased wiki link or embed has to escape its separator as `\|`, because a bare `|` ends the cell: the cell form is `[[Page\|alias]]`, or `![[image.png\|alt]]` for embeds. Each literal `|` inside the alias carries its own backslash too, so an alias like `Some | Alias` is written `[[Page\|Some \| Alias]]` in a cell, or `![[image.png\|Some \| Alias]]` as an embed. The escaped form resolves identically to the unescaped one, and the escape you author stays in the file. A target that is only whitespace or only the escape (`[[ ]]`, `[[\|alias]]`) is not a link. Byte-for-byte preservation has narrow exceptions, none of them reached by authoring the escape — see [Tables](https://openknowledge.ai/docs/features/editor#tables) for what they are. ## 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`](https://openknowledge.ai/docs/reference/configuration) 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. | > **Info** > > 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](https://github.com/inkeep/open-knowledge/issues). ## 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](https://openknowledge.ai/docs/reference/mcp) gives any MCP-capable agent — Claude Code, Cursor, Codex, OpenCode, OpenClaw — typed `exec` (read) / `write` / `search` / `links` tools over the same files, so edits are consistent, attributed, and keep your link graph healthy. ## See also - [Quickstart](https://openknowledge.ai/docs/get-started/quickstart): the five-minute setup - [Core concepts](https://openknowledge.ai/docs/reference/core-concepts): links, backlinks, and the file-system-as-database model - [Editor](https://openknowledge.ai/docs/features/editor): WYSIWYG, source mode, and the graph, backlinks, and properties panels - [Timeline and recovery](https://openknowledge.ai/docs/features/timeline-and-recovery): version history and point-in-time rollback - [Ignore patterns](https://openknowledge.ai/docs/features/ignore-patterns): keep folders out of the editor, search, and agents - [Assets and embeds](https://openknowledge.ai/docs/features/assets-and-embeds): how images and file references behave - [GitHub sync](https://openknowledge.ai/docs/features/github-sync): keep your project synced with your team through GitHub