Zum Inhalt

🗒️ How-To: Einen Obsidian-Vault importieren

Wer seine Notizen eine Weile in Obsidian sammelt, besitzt bereits genau das Material, für das der KnowledgeBase Builder gemacht ist: verknüpfte Notizen mit einer Struktur, die man nur schwer sieht. Ein kostenloses Import-Skript verwandelt einen kompletten Vault in eine KnowledgeBase-Builder-Datenbank — jede Notiz wird zu einem Element, jeder [[Wikilink]] zu einer sichtbaren Verbindung, die Ordnerstruktur zu Kategorien.

Das Skript schreibt direkt in die SQLite-Datei (.kdb). Es wird weder ein laufender Server noch die Weboberfläche benötigt, und das Ergebnis lässt sich mit der Desktop-, der Mobil- und der Web-Version gleichermaßen öffnen.

1. Was woraus wird

Das Skript kopiert nicht einfach Text. Es liest den Vault so, wie Obsidian ihn versteht, und übersetzt jedes Konstrukt in sein Gegenstück im Diagramm:

Obsidian KnowledgeBase Builder
Markdown-Datei Element, der Notiztext als HTML-Anhang
Ordner Element der Kategorie Folder, dazu eine contains-Verbindung
Übergeordneter Ordner Kategorie des Elements
#tag und Frontmatter tags: Tags
[[Wikilink]] links to-Verbindung, dazu ein klickbarer Link im Notiztext, der das Ziel als neuen Root des Diagramms lädt
![[Einbettung]] embeds-Verbindung; ![[Notiz#Überschrift]] und ![[Notiz#^Block]] werden inline aufgelöst, bis zu drei Ebenen tief
feld:: [[ziel]] (Dataview) Verbindung, beschriftet mit dem Feldnamen
Frontmatter title:, erste # Überschrift, erster Alias Name des Elements
Frontmatter aliases: Zusätzliche Namen, für die Auflösung von Links
Frontmatter description: / summary:, sonst der erste Absatz Beschreibung des Elements
Erste externe URL in der Notiz DirectLinkURL des Elements
Bilder im Text In die Notiz eingebettet; das erste wird zusätzlich zum Element-Symbol
```mermaid-Block Als SVG gerendert und eingebettet, sofern mermaid-cli verfügbar ist, sonst bleibt der Quellcode stehen
$Formel$ / $$Formel$$ MathML, vom Browser selbst gerendert
==Hervorhebung==, ~~durchgestrichen~~, > [!callout] In HTML umgesetzt; %%Kommentare%% entfallen

Ein Emoji am Anfang eines Notiznamens wandert in eine eigene Zelle der Knotenbeschriftung und wird dadurch größer dargestellt als der Text daneben — dieselbe Struktur, die die Anwendung auch selbst erzeugt.

2. Das Skript beschaffen

Der Importer gehört zum kostenlosen Adapter-Repository und wird von GitHub geladen. Hol ihn immer von dort, denn dort liegt die aktuelle Fassung:

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

Das Verzeichnis enthält drei Dateien: das Skript obsidian_to_kbb.py, seine README und empty.kdb — die leere Vorlagendatenbank, die der Importer kopiert, wenn die Zieldatei noch nicht existiert. Das Repository steht unter der MIT-Lizenz.

Vorausgesetzt wird Python 3.6 oder neuer. Für einen einfachen Import genügt die Standardbibliothek. Vier optionale Pakete verbessern das Ergebnis und werden automatisch genutzt, sobald sie installiert sind:

pip install markdown pyyaml pillow latex2mathml
Paket Ohne das Paket
markdown Es greift ein sparsamer eingebauter Konverter, der nur die häufigen Fälle abdeckt
pyyaml Frontmatter liest ein minimaler Ersatz-Parser (schlüssel: wert und --Listen)
pillow Bilder werden in Originalgröße eingebettet statt verkleinert
latex2mathml LaTeX-Formeln bleiben Quellcode

Mermaid-Diagramme brauchen zusätzlich mermaid-cli. Fehlt es, bleibt der Codeblock einfach Quellcode, und es wird nichts heruntergeladen. Die Option --install-mermaid holt es vorübergehend über npx; das setzt Node.js voraus und beim ersten Mal einige hundert Megabyte für den mitgelieferten Browser.

3. Der erste Import

Rufe das Skript in dem Verzeichnis auf, in dem es liegt, und zeige ihm deinen Vault:

python obsidian_to_kbb.py --vault ~/Obsidian/MeinVault --db meinvault.kdb

meinvault.kdb entsteht beim ersten Lauf aus empty.kdb. Die Option --template brauchst du nur, wenn du das Skript aus einem anderen Verzeichnis aufrufst oder eine andere Vorlage verwenden willst.

Anschließend öffnest du die Datei in der Anwendung: Wissensdatenbank → Öffnen, in der Web-Version lädst du sie dort hoch. Alles aus dem Kapitel Wissensdatenbank gilt für die importierte Datenbank genauso wie für eine von Hand aufgebaute.

Bevor du eine bestehende Wissensdatenbank überschreibst: Lege eine Kopie der .kdb-Datei an. Der Importer schreibt direkt in die Datenbank, und für einen Massenimport gibt es kein schrittweises Rückgängigmachen.

4. Wie das Diagramm danach aussieht

Beim ersten Lauf formatiert das Skript das Diagramm gleich mit, damit du nicht vor einem unsortierten Knotenhaufen sitzt: radiales Mindmap-Layout, Einfärbung nach Kategorie, das Farbschema Spectral, ein Kreuzstich-Hintergrund und transparente Elemente. Wenn du lieber selbst formatierst oder in ein bereits gestaltetes Diagramm nachimportierst, nimm --no-format-diagram. Alles aus Diagramm formatieren lässt sich danach wie gewohnt anwenden.

Zwei Details lohnen sich, wenn du anfängst herumzuklicken:

  • Die Wikilinks in einer Notiz sind kein toter Text. Ein Klick lädt das verlinkte Element als neuen Root des Diagramms. Der Importer schreibt sie als Verweise der Form itemid://<ID>, die das Notizpanel innerhalb der Datenbank auflöst, statt ein Browserfenster zu öffnen. Alles Weitere zu diesem Panel steht unter Notizen zum Element.
  • Aus Ordnern wurden Elemente und Kategorien. Du kannst die Vault-Struktur also im Diagramm ablaufen und zugleich unter Elemente in Kategorie danach filtern.

5. Die Datenbank aktuell halten

Der Import ist keine Einbahnstraße. Arbeite in Obsidian weiter und lass das Skript danach erneut laufen:

python obsidian_to_kbb.py --vault ~/Obsidian/MeinVault --db meinvault.kdb --prune

Das Skript legt in der Datenbank eine Tabelle ObsidianSync an und merkt sich je Datei eine Prüfsumme des Inhalts, sodass nur geänderte Notizen neu geschrieben werden. Notizen, die eine geänderte Notiz einbetten, werden ebenfalls neu geschrieben, damit ihre eingebundenen Textstellen stimmig bleiben. --force schreibt alles neu, --prune entfernt zusätzlich die Elemente, deren Markdown-Datei es nicht mehr gibt — ohne diese Option bleiben gelöschte Notizen in der Datenbank stehen.

Elemente und Verbindungen werden über stabile URIs wiedergefunden, die aus dem Quellobjekt abgeleitet sind:

obsidian:note:<Pfad>              Element einer Notiz
obsidian:folder:<Pfad>            Element eines Ordners
obsidian:rel:<von>|<nach>|<Art>   Verbindung

Das ist der Grund, warum deine Handarbeit nicht verloren geht. Positionen, Farben und alle übrigen Elementeigenschaften rührt ein erneuter Import nicht an; aktualisiert werden nur Name, Beschreibung, URL und der Notiztext. Ein von Hand angeordnetes und eingefärbtes Diagramm übersteht beliebig viele Läufe.

6. Große Vaults und Index-Seiten

Vaults wie der Obsidian Hub enthalten Übersichtsnotizen, die auf hunderte andere Notizen verweisen. Würde man all diese Links zu Verbindungen machen, verschwände die eigentliche Struktur des Vaults unter einem Knäuel. Das Skript erkennt solche Notizen deshalb — viele Links, wenig Text — und lässt ihre Links weg.

Der Schwellenwert passt sich dem Vault an: Er liegt bei mindestens dem Vierfachen der mittleren Linkzahl pro Notiz. Drei Optionen steuern ihn, falls die automatische Entscheidung nicht zu deinem Vault passt:

Option Bedeutung
--index-page-links N Ab wie vielen Links eine Notiz als Index-Seite gilt
--index-page-words N Bis zu wie vielen Wörtern eine Notiz als Index-Seite gilt
--keep-index-page-links Schaltet die Erkennung ab; jeder Link wird zur Verbindung

7. Die nützlichsten Optionen

--help listet alle auf; das hier sind die, die man kennen sollte:

Option Bedeutung
--template DATEI Leere Datenbank, die kopiert wird, wenn --db noch nicht existiert (Vorgabe empty.kdb im aktuellen Verzeichnis)
--category folder\|fixed\|none Woher die Kategorie eines Elements stammt (Vorgabe: der Ordnername)
--category-name NAME Kategorie für --category fixed und für Notizen im Wurzelordner
--no-folder-nodes Kein Element je Ordner anlegen
--root-name NAME Name des obersten Ordnerelements (Vorgabe Vault)
--no-images Bilder vollständig weglassen
--no-mermaid, --install-mermaid, --mermaid-cli PFAD Steuern die Mermaid-Darstellung
--link-relation, --embed-relation, --folder-relation Beschriftungen der erzeugten Verbindungen
--no-dataview-relations feld:: [[ziel]] wie einen gewöhnlichen Wikilink behandeln
--pipe-as-relation-label Den Text hinter dem \| von [[ziel\|text]] als Verbindungsbeschriftung nutzen
--no-format-diagram Die Formatierung des Diagramms unangetastet lassen
--prune Elemente entfernen, deren Markdown-Datei es nicht mehr gibt
--force Jede Notiz neu schreiben, auch die unveränderten
--keep-undo Die Undo-Trigger während des Imports aktiv lassen (langsamer, größere Datei)

8. Gut zu wissen

  • Datenbankversion. Eine ältere Datenbank wird bei Bedarf auf Version 4 gehoben — die Tag-Tabellen und ihre Undo-Trigger werden angelegt, falls sie fehlen.
  • Rückgängig. Während des Imports werden die Undo-Trigger entfernt und danach wiederhergestellt, das Undo-Protokoll wird geleert. Ein Massenimport ist nicht dafür gedacht, Schritt für Schritt zurückgenommen zu werden. --keep-undo verhindert das, auf Kosten von Tempo und Dateigröße.
  • Dateigröße. Eine Aktualisierung lässt alte Blobs zurück. Wissensdatenbank → Datenbankgröße reduzieren entfernt sie in der Anwendung.
  • Sicherung. Lege vor dem ersten Lauf gegen eine bestehende Wissensdatenbank eine Kopie an.