Skip to content

🗒️ How-To: Import an Obsidian vault

If you have been collecting notes in Obsidian for a while, you already own exactly the kind of material the KnowledgeBase Builder was built for: linked notes with a structure that is difficult to see. A free import script turns a complete vault into a KnowledgeBase Builder database — every note becomes an item, every [[wikilink]] becomes a visible relation, and the folder structure becomes categories.

The importer writes directly into the SQLite file (.kdb). No running server and no web interface are needed, and the result can be opened with the desktop, mobile and web versions alike.

1. What becomes what

The script does not just copy text. It reads the vault the way Obsidian understands it and translates each construct into its counterpart in the diagram:

Obsidian KnowledgeBase Builder
Markdown file Item, with the note text as an HTML attachment
Folder Item of the category Folder, plus a contains relation
Parent folder Category of the item
#tag and frontmatter tags: Tags
[[wikilink]] links to relation, plus a clickable link inside the note that loads the target as the new root of the diagram
![[embed]] embeds relation; ![[note#heading]] and ![[note#^block]] are resolved inline, up to three levels deep
field:: [[target]] (Dataview) Relation labelled with the field name
frontmatter title:, first # heading, first alias Name of the item
frontmatter aliases: Additional names, used to resolve links
frontmatter description: / summary:, otherwise the first paragraph Description of the item
First external URL in the note DirectLinkURL of the item
Images in the text Embedded into the note; the first one additionally becomes the item icon
```mermaid block Rendered to SVG and embedded when mermaid-cli is available, otherwise left as source code
$formula$ / $$formula$$ MathML, rendered by the browser itself
==highlight==, ~~strikethrough~~, > [!callout] Converted to HTML; %%comments%% are dropped

An emoji at the start of a note name is moved into its own cell of the node label, so it is displayed larger than the text beside it — the same structure the application produces itself.

2. Getting the script

The importer is part of the free adapter repository and is downloaded from GitHub. Always take it from there, as that is where the current version lives:

https://github.com/inforapid/knowledgebase-builder-adapter/tree/main/obsidian

The directory contains three files: the script obsidian_to_kbb.py, its README, and empty.kdb — the empty template database the importer copies when the target file does not exist yet. The repository is published under the MIT licence.

Python 3.6 or newer is required. The standard library alone is enough for a basic import. Four optional packages improve the result and are used automatically as soon as they are installed:

pip install markdown pyyaml pillow latex2mathml
Package Without it
markdown A frugal built-in converter is used, which covers only the common cases
pyyaml Frontmatter is read by a minimal fallback parser (key: value and - lists)
pillow Images are embedded at their original size instead of being scaled down
latex2mathml LaTeX formulas stay source code

Mermaid diagrams additionally need mermaid-cli. Without it the code block simply stays source code and nothing is downloaded. The option --install-mermaid fetches it temporarily through npx; that needs Node.js and, the first time, a few hundred megabytes for the headless browser it brings along.

3. The first import

Run the script from the directory it lives in and point it at your vault:

python obsidian_to_kbb.py --vault ~/Obsidian/MyVault --db myvault.kdb

myvault.kdb is created from empty.kdb on the first run. The --template option is only needed when you call the script from another directory or want to use a different template.

Then open the file in the application: Knowledge Base → Open, or upload it there in the web version. Everything you find in the Knowledge Base chapter applies to the imported database exactly as it does to one you built by hand.

Before you overwrite an existing knowledge base: make a copy of the .kdb file. The importer writes into the database directly, and there is no step-by-step undo for a bulk import.

4. What the diagram looks like afterwards

On the first run the script also formats the diagram, so you are not faced with an unsorted heap of nodes: radial mindmap layout, colouring by category, the Spectral colour scheme, a cross-stitch background and transparent items. If you would rather do the formatting yourself, or if you are re-importing into a diagram you have already styled, use --no-format-diagram. Everything in Format Diagram can be applied afterwards as usual.

Two details are worth knowing when you start clicking around:

  • The wikilinks inside a note are not dead text. A click loads the linked item as the new root of the diagram. The importer writes them as links of the form itemid://<ID>, which the notes panel resolves inside the database instead of opening a browser window. Everything else about that panel is in Notes on Item.
  • Folders became items and categories. You can therefore navigate the vault structure in the diagram and at the same time filter by it in Items in Category.

5. Keeping the database up to date

The import is not a one-way street. Carry on working in Obsidian and run the script again afterwards:

python obsidian_to_kbb.py --vault ~/Obsidian/MyVault --db myvault.kdb --prune

The script creates a table ObsidianSync in the database and remembers a content hash per file, so only changed notes are rewritten. Notes that embed a changed note are rewritten as well, so their inline transclusions stay in sync. --force rewrites everything, --prune additionally removes the items whose Markdown file no longer exists — without it, deleted notes stay in the database.

Items and relations are found again through stable URIs derived from the source object:

obsidian:note:<path>              item of a note
obsidian:folder:<path>            item of a folder
obsidian:rel:<from>|<to>|<kind>   relation

This is the reason your manual work is not lost. Positions, colours and all other item properties are never touched by a re-import; only name, description, URL and the note text are updated. A diagram you have arranged and coloured by hand survives any number of runs.

6. Large vaults and index pages

Vaults such as the Obsidian Hub contain map-of-content notes that link to hundreds of other notes. Turning all of those links into relations would bury the actual structure of the vault under a hairball, so the script detects such notes — many links, little text — and leaves their links out.

The threshold adapts to the vault: it is at least four times the median number of links per note. Three options control it, should the automatic decision not match your vault:

Option Meaning
--index-page-links N From how many links a note counts as an index page
--index-page-words N Up to how many words a note counts as an index page
--keep-index-page-links Switches the detection off; every link becomes a relation

7. The most useful options

--help lists them all; these are the ones worth knowing:

Option Meaning
--template FILE Empty database, copied when --db does not exist yet (default empty.kdb in the current directory)
--category folder\|fixed\|none Where the category of an item comes from (default: the folder name)
--category-name NAME Category for --category fixed and for notes in the root folder
--no-folder-nodes Do not create an item per folder
--root-name NAME Name of the topmost folder item (default Vault)
--no-images Leave images out entirely
--no-mermaid, --install-mermaid, --mermaid-cli PATH Control the Mermaid rendering
--link-relation, --embed-relation, --folder-relation Labels of the generated relations
--no-dataview-relations Treat field:: [[target]] like an ordinary wikilink
--pipe-as-relation-label Use the text behind the \| of [[target\|text]] as the relation label
--no-format-diagram Leave the formatting of the diagram as it is
--prune Remove items whose Markdown file no longer exists
--force Rewrite every note, including unchanged ones
--keep-undo Leave the undo triggers active during the import (slower, larger file)

8. Good to know

  • Database version. An older database is upgraded to version 4 if needed — the tag tables and their undo triggers are created when they are missing.
  • Undo. During the import the undo triggers are dropped and restored afterwards, and the undo log is cleared. A bulk import is not meant to be undone step by step. --keep-undo prevents this, at the cost of speed and file size.
  • File size. An update leaves old blobs behind. Knowledge Base → Reduce Database Size removes them in the application.
  • Backup. Make a copy of the database before the first run against an existing knowledge base.