From Notion
How to export a Notion workspace to Markdown and open it in OpenKnowledge, what carries over, and where the two differ.
This guide will cover exporting your Notion workspace to markdown files so that you can access them from OpenKnowledge. OpenKnowledge and Notion differ in a few key ways, so a Notion export needs some cleanup — this guide covers what carries over and what to fix.
Install OpenKnowledge
macOS (Apple Silicon)
Download the latest version of the OpenKnowledge desktop app.
Download for macOSLinux, Windows, Intel Mac
Install the ok CLI with npm:
npm install -g @inkeep/open-knowledgeExport your workspace from Notion
- In Notion, click on your workspace in the top left and go to Settings.
- Under General, scroll down to Export.
- Set Export format to Markdown & CSV and leave all the default settings.
- Download and unzip the export folder and move it to your desired location.
Clean up the export with ok migrate notion
The ok CLI ships a cleanup command that resolves format issues with the exported content. By default, the command prints what it would change and writes nothing until you pass --apply.
# Preview what would change (writes nothing)
ok migrate notion /path/to/unzipped-export
# Apply the changes
ok migrate notion /path/to/unzipped-export --applyThe desktop app installs the CLI to $HOME/.ok/bin; a pre-checked toggle in
its first-launch dialog puts ok on your PATH. If ok isn't found, add it
from File → Set up OpenKnowledge integrations…, then open a new terminal
window. If it's still missing, add $HOME/.ok/bin to your PATH manually.
Every transform is idempotent, so re-running is safe. See the tables below for a full list of differences between the Notion export and what OpenKnowledge supports.
Options:
| Flag | Effect |
|---|---|
--apply | Write the changes (default is a dry-run preview). |
--strip-base64 | Delete inline base64 images instead of extracting them to files. |
--remove-csv | Delete each _all.csv once its table page exists (destructive). |
--only <list> / --skip <list> | Run or skip specific transforms: links, frontmatter, callouts, images, tables. |
--force | Run even if the folder isn't detected as a Notion export. |
--json | Print a machine-readable report. |
The command refuses to touch a folder that doesn't look like a Notion export unless you pass --force.
Open the export in OpenKnowledge
macOS Desktop app
Open OpenKnowledge, choose Open folder on disk, select the unzipped export folder, and proceed through the Setup screen with defaults selected.
Linux, Windows, Intel Mac
cd into the unzipped folder and run ok init && ok start.
What exports cleanly
| Notion content | In OpenKnowledge |
|---|---|
| Headings, paragraphs, bold / italic, quotes, and dividers | Render natively and are preserved in the exported markdown. |
| Bulleted, numbered, and to-do lists | Render natively, including nesting and - [ ] checkboxes. |
| Code blocks | Render with syntax highlighting. |
| Simple (inline) tables | Convert to Markdown pipe tables and render as tables. |
| Images and file attachments | Downloaded into the export folder next to each page and referenced with relative  links; images render inline. See Assets and embeds. |
Where the two differ
A number of Notion features don't survive the Markdown & CSV export, or land as plain text. Many can be fixed by the ok migrate notion <folder-path> command.
| Notion feature | Exported result | Fixed by CLI migration command |
|---|---|---|
| Databases (tables, boards, calendars, galleries, timelines) | Each database exports as a <name>_all.csv file and a folder holding one markdown file per row. Full-page databases also get a stub page. | ✅ Creates a Markdown table page for every CSV. The .csv files are not deleted unless you pass --remove-csv. |
| Database row properties | Exported as plain Key: Value lines under the page title, not YAML frontmatter. | ✅ Lifted into YAML frontmatter so they show in the Properties panel. |
| Callouts | Exported as raw <aside> HTML, so they don't pick up OpenKnowledge's callout styling. | ✅ Converted to native > [!note] callouts. |
| Links between pages | Link targets are percent-encoded, and once decoded contain spaces. | ✅ Decoded and angle-wrapped so they render and resolve. |
| Pasted or inline images | Some images export inline as un-rendered base64 data: URIs instead of files. | ✅ Extracted to image files (or dropped with --strip-base64). |
| Relations, rollups, formulas | Not represented in the Markdown & CSV export. | — |
| Toggles and toggle headings | Nested content is preserved, but the collapsible toggle wrapper is lost. | — |
| Synced blocks | Written out as ordinary content wherever they appear; the link between copies is gone. | — |
| Web bookmarks and embeds (Figma, video, PDF, etc.) | Converted to plain links. The rich preview card or inline embed is gone. Uploaded files download alongside the page. | — |
| Page icons and cover images | Not exported. | — |
| Comments, page history, and backlinks | Not included in the export. | — |
See also
- GitHub sync: keep your project synced with your team through GitHub
- Quickstart: the five-minute setup
- Core concepts: links, backlinks, and the file-system-as-database model
- Assets and embeds: how images and file references behave