Obsidian Plugin

import { Aside } from ‘@astrojs/starlight/components’;

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 to your Obsidian vault plugins folder
cp manifest.json main.js <vault>/.obsidian/plugins/orimora-sync/

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)

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

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
---

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)

Use incremental pull for daily use. Use the full ZIP snapshot when setting up a new vault or after bulk changes in Orimora.

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.

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:

Endpoint	Used for
GET /api/v1/collections	Loading collection list
GET /api/v1/documents?collectionId=X&updatedSince=ISO&format=markdown	Incremental pull
GET /api/collections.export?id=X&format=zip	Full ZIP pull
POST /api/documents.create	Push new documents
POST /api/documents.update	Push updates

API keys with read scope are sufficient for pull. Read + write scope is needed for push.