Obsidian Plugin

Das Orimora Obsidian Plugin (obsidian/) ermöglicht die Synchronisation zwischen deinem lokalen Obsidian-Vault und einer Orimora-Instanz.

Installation

Das Plugin ist noch nicht im Obsidian Community Plugins-Verzeichnis veröffentlicht. Manuelle Installation:

cd obsidian
yarn install
yarn build

# Build-Ausgabe in den Vault kopieren. Der Ordnername MUSS die Plugin-ID sein
# (obsidian-orimora), sonst lädt Obsidian das Plugin nicht.
mkdir -p <vault>/.obsidian/plugins/obsidian-orimora
cp dist/manifest.json dist/main.js <vault>/.obsidian/plugins/obsidian-orimora/

Aktiviere das Plugin unter Obsidian → Einstellungen → Community Plugins.

Konfiguration

Einstellung	Beschreibung
Orimora URL	Basis-URL deiner Orimora-Instanz, z.B. `https://wiki.example.com`
API Key	Ein `kb_`-API-Schlüssel aus Einstellungen → Entwickler
Standard-Sammlung	Sammlung, in die Dokumente gepusht werden
Pull-Ordner	Vault-relativer Ordner für gepullte Dokumente (Standard: `Orimora`)
Pull-Sammlung	Sammlung, aus der gepullt wird (Standard: Standard-Sammlung)
Inhaltsverzeichnis entfernen	TOC-Blöcke (Listen von `[[#abschnitt]]`-Links) vor dem Push entfernen
Frontmatter als Metadaten-Block synchronisieren	Nicht-Tag-Frontmatter beim Push in einen `## Metadaten`-Block projizieren und beim Pull strippen (Standard an)

Push

Sende eine einzelne Notiz oder einen ganzen Ordner an Orimora.

Befehl	Aktion
`Push active file to Orimora`	Aktuelle Notiz pushen
`Push folder to Orimora`	Alle `.md`-Dateien im aktiven Ordner pushen
`Check Orimora sync state of active note`	Meldet, ob die offene Notiz synchron ist

Rechtsklick auf eine Datei oder einen Ordner für die gleichen Optionen.

Nach erfolgreichem Push erhält die Notiz Orimora-Frontmatter:

---
orimora_id: <document-uuid>
orimora_collection_id: <collection-uuid>
orimora_last_synced: 2025-01-01T12:00:00.000Z
orimora_revision: 12 # monoton — für exakte Drift-Erkennung
---

Tags & Frontmatter

Tags (`tags:` ↔ Orimora-Tags)

Das tags:-Frontmatter der Notiz synchronisiert bidirektional mit den Orimora-Tags des Dokuments — flach, ohne Namespaces. tags: Funktion, Methode, Aufsichtsrat wird zu drei Tags in Orimora.

Push: Die tags:-Menge wird an Orimora gesendet (angelegt-oder-wiederverwendet per Name). Eine Notiz ohne tags:-Schlüssel lässt ihre Tags unangetastet; ein leeres tags: löscht sie.
Pull: Orimoras Tags werden ins tags: zurückgeschrieben, nur wenn sich die Menge tatsächlich geändert hat (case-insensitiv), unter Erhalt deiner Schreibweise — Aufsichtsrat wird also nie stillschweigend umgeschrieben und die Datei nicht „gechurnt”. Restricted (ACL-verwaltete) Tags werden nie in den Vault geschrieben.

Metadaten-Block (`## Metadaten`)

Mit aktivierter Option Frontmatter als Metadaten-Block synchronisieren (Standard) wird das übrige Nicht-Tag-Frontmatter (Status, Themen, eigene Felder, verweise_intern als Links, …) beim Push in eine ## Metadaten-Tabelle am Dokumentanfang projiziert, da Orimora keinen Pro-Dokument-Metadatenspeicher hat. Der Block wird bei jedem Push idempotent neu erzeugt und beim Pull wieder gestrippt, sodass dein Obsidian-Frontmatter die Quelle der Wahrheit bleibt. Schalte die Option aus, um das Altverhalten zu behalten (Frontmatter wird beim Push verworfen).

CLI-Runner

Für skriptbare/Headless-Pushes ohne die Obsidian-UI bringt das Paket einen Runner mit:

cd obsidian
yarn sync   # pusht einen Vault gemäß konfigurierter Env (siehe obsidian/.env.example)

Pull

Zwei Pull-Modi stehen zur Verfügung:

Inkrementeller Pull (empfohlen)

Holt nur Dokumente, die seit orimora_last_synced geändert wurden. Beim ersten Lauf wird automatisch auf einen vollständigen ZIP-Snapshot zurückgefallen.

Befehl: Pull changed documents from Orimora (incremental)
Ribbon: Klick auf das ↓-Symbol

Vollständiger ZIP-Snapshot

Lädt die gesamte Sammlung als ZIP-Archiv und überschreibt alle lokalen Dateien.

Befehl: Pull collection from Orimora (ZIP snapshot)

Ausgewählte Ordner pullen

Statt der ganzen Sammlung gezielt einzelne Collection-Ordner pullen.

Befehl: Pull from Orimora (select folders…)

Konfliktbehandlung

Push-Konflikte

Wenn ein Dokument mit gleichem Titel bereits in Orimora existiert, bietet das Plugin drei Optionen:

Überschreiben — Bestehendes Dokument aktualisieren
Duplizieren — Neues Dokument mit anderem Titel erstellen
Abbrechen — Push für diese Datei abbrechen

Pull-Konflikte (Lokal-neuer-Erkennung)

Beim inkrementellen Pull prüft das Plugin, ob eine lokale Datei seit dem letzten Sync bearbeitet wurde. Wenn die lokale Datei neuer ist als sowohl der orimora_last_synced-Zeitstempel als auch das Remote-updatedAt, wird die lokale Datei übersprungen, um lokale Änderungen nicht zu überschreiben.

Übersprungene Dateien werden in der Pull-Zusammenfassung mit einem ⏭-Indikator angezeigt.

Drift-Indikator

Die Statusleiste zeigt an, wenn Orimora eine neuere Revision als deine lokale Kopie hält — exakt verglichen über orimora_revision (nicht über Zeitstempel). Ein passiver ↓ neuer-Hinweis sagt dir, vor dem Bearbeiten zu pullen, und vermeidet versehentliche Konflikte.

Wiki-Links

[[WikiLinks]] werden anhand des orimora_id-Frontmatters der Vault-Dateien aufgelöst und in korrekte Hyperlinks in Orimora umgewandelt. Beim Pull werden Orimora-Dokumentlinks zurück in [[WikiLinks]] konvertiert.

API-Anforderungen

Das Obsidian Plugin nutzt die Orimora REST API (alles unter /api/v1/, Bearer-Key-Auth):

Endpunkt	Verwendung
`GET /api/v1/collections`	Sammlungsliste laden
`GET /api/v1/documents?collectionId=X&title=Y[&parentDocumentId=Z]`	Existenz-/Konfliktprüfung (Push)
`GET /api/v1/documents?collectionId=X&updatedSince=ISO&format=markdown`	Inkrementeller Pull (inkl. `tags`)
`GET /api/v1/collections.export?id=X&format=zip`	Vollständiger ZIP-Pull
`POST /api/v1/documents`	Dokumente anlegen (mit `tags`)
`PATCH /api/v1/documents/:id`	Dokumente aktualisieren (mit `tags`)
`POST /api/attachments.upload`	Bild-/Anhang-Upload (zweistufig)

Der Bild-Upload ist zweistufig: Das Plugin registriert zuerst den Anhang, lädt dann die Bytes zur zurückgegebenen URL hoch und schreibt den Markdown-Bildlink auf die öffentliche URL um.

API-Keys mit Lesen-Berechtigung reichen für Pull. Lesen + Schreiben wird für Push benötigt. Der title-Filter macht Existenzprüfungen zu einer einzigen begrenzten Anfrage (kein Full-Collection-Scan).