Obsidian Plugin

The Orimora Obsidian plugin (obsidian/) allows you to sync notes between your local Obsidian vault and an Orimora instance.

Installation

The plugin is not yet published to the Obsidian Community Plugins directory. Install manually:

cd obsidian
yarn install
yarn build

# Copy the build output to your vault. The folder name MUST be the plugin id
# (obsidian-orimora) or Obsidian will not load the plugin.
mkdir -p <vault>/.obsidian/plugins/obsidian-orimora
cp dist/manifest.json dist/main.js <vault>/.obsidian/plugins/obsidian-orimora/

Enable the plugin in Obsidian → Settings → Community Plugins.

Configuration

Setting	Description
Orimora URL	Base URL of your Orimora instance, e.g. `https://wiki.example.com`
API Key	A `kb_` prefixed API key from Settings → Developers
Default Collection	Collection to push documents into
Pull Folder	Vault-relative folder for pulled documents (default: `Orimora`)
Pull Collection	Collection to pull from (defaults to Default Collection)
Remove table of contents	Strip TOC blocks (lists of `[[#section]]` links) before pushing
Sync frontmatter as metadata block	Project non-tag frontmatter into a `## Metadaten` block on push and strip it on pull (default on)

Push

Push a single note or an entire folder to Orimora.

Command	Action
`Push active file to Orimora`	Push the currently open note
`Push folder to Orimora`	Push all `.md` files in the active folder
`Check Orimora sync state of active note`	Report whether the open note is in sync

Right-click a file or folder in the file tree for the same options.

After a successful push, the note receives Orimora frontmatter:

---
orimora_id: <document-uuid>
orimora_collection_id: <collection-uuid>
orimora_last_synced: 2025-01-01T12:00:00.000Z
orimora_revision: 12 # monotonic — used for exact drift detection
---

Tags & frontmatter

Tags (`tags:` ↔ Orimora tags)

The note’s tags: frontmatter syncs bidirectionally with the document’s Orimora tags — flat, no namespaces. tags: Funktion, Methode, Aufsichtsrat becomes three tags in Orimora.

Push: the tags: set is sent to Orimora (create-or-reuse by name). A note with no tags: key leaves its tags untouched; an empty tags: clears them.
Pull: Orimora’s tags are written back into tags: only when the set actually changed (case-insensitive), preserving your existing casing — so Aufsichtsrat is never silently rewritten and the file isn’t churned. Restricted (ACL-governed) tags are never written into the vault.

Metadata block (`## Metadaten`)

With Sync frontmatter as metadata block enabled (default), the remaining non-tag frontmatter (status, themes, custom fields, verweise_intern as links, …) is projected into a ## Metadaten table at the top of the document on push, since Orimora has no per-document metadata store. The block is regenerated idempotently on each push and stripped again on pull, so your Obsidian frontmatter stays the source of truth. Turn the setting off to keep the legacy behaviour (frontmatter dropped on push).

CLI runner

For scripted/headless pushes without the Obsidian UI, the package ships a runner:

cd obsidian
yarn sync   # pushes a vault per the configured env (see obsidian/.env.example)

Pull

Two pull modes are available:

Incremental Pull (recommended)

Fetches only documents changed since orimora_last_synced. On first run, falls back to a full ZIP snapshot.

Command: Pull changed documents from Orimora (incremental)
Ribbon: click the ↓ icon

Full ZIP Snapshot

Downloads the entire collection as a ZIP archive and overwrites all local files.

Command: Pull collection from Orimora (ZIP snapshot)

Pull selected folders

Pick specific collection folders to pull instead of the whole collection.

Command: Pull from Orimora (select folders…)

Conflict Handling

Push Conflicts

When pushing a document whose title already exists in Orimora, the plugin offers three options:

Overwrite — Update the existing document
Duplicate — Create a new document with a different title
Cancel — Abort the push for this file

Pull Conflicts (local-newer detection)

During incremental pull, the plugin checks whether a local file has been modified since the last sync. If the local file is newer than both the orimora_last_synced timestamp and the remote document’s updatedAt, the local file is skipped to avoid overwriting unsaved local work.

Skipped files are reported in the pull summary with a ⏭ indicator.

Drift indicator

The status bar shows when Orimora holds a newer revision than your local copy, compared exactly via orimora_revision (not timestamps). A passive ↓ newer hint tells you to pull before editing, avoiding accidental conflicts.

Wiki Links

[[WikiLinks]] are resolved using the orimora_id frontmatter of vault files and converted to proper hyperlinks in Orimora. On pull, Orimora document links are converted back to [[WikiLinks]].

API Requirements

The Obsidian plugin uses the Orimora REST API (all under /api/v1/, Bearer-key auth):

Endpoint	Used for
`GET /api/v1/collections`	Loading the collection list
`GET /api/v1/documents?collectionId=X&title=Y[&parentDocumentId=Z]`	Existence / conflict lookup (push)
`GET /api/v1/documents?collectionId=X&updatedSince=ISO&format=markdown`	Incremental pull (incl. `tags`)
`GET /api/v1/collections.export?id=X&format=zip`	Full ZIP pull
`POST /api/v1/documents`	Create documents (with `tags`)
`PATCH /api/v1/documents/:id`	Update documents (with `tags`)
`POST /api/attachments.upload`	Image/attachment upload (2-step)

Image upload is a two-step flow: the plugin first registers the attachment, then uploads the bytes to the returned URL, and rewrites the Markdown image link to the public URL.

API keys with read scope are sufficient for pull. Read + write scope is needed for push. The title filter makes existence checks a single bounded request (no full-collection scan).