Files
dragonroll/frontend/app/content/docs/03-integrations/04-obsidian.md
Gitea OpenCode Agent 788f69efd3
All checks were successful
Test / test (push) Successful in 2s
Fix issue #79: Implement documentation
2026-10-15 19:07:09 +00:00

3.2 KiB

Obsidian

The Dragonroll Sync plugin moves campaign notes between a Dragonroll campaign and an Obsidian vault: import the campaign so you can read and write it with your own notes, and push the note you are working on back to the campaign.

It is an explicit, you-ask-for-it workflow. Nothing happens in the background, and the plugin never deletes a note.

Installing

Copy main.js and manifest.json into your vault:

<vault>/.obsidian/plugins/dragonroll-sync/

Then enable Dragonroll Sync under Settings → Community plugins. It is plain JavaScript, so there is nothing to build, and it runs on desktop and mobile alike.

Connecting

Under Settings → Community plugins → Dragonroll Sync:

  1. Set the Dragonroll API URL — https://dragonroll.aranroig.com/api by default, or your own server, such as http://localhost:5000/api.
  2. Sign in with your Dragonroll username or email and your password. The password is used once to sign in and is not saved; what the plugin keeps is the session token, in this vault, and it expires after 48 hours like any other Dragonroll session.
  3. Pick the campaign. Every import and push works against that campaign.

Commands

Both are in Obsidian's command palette:

Command What it does
Import or refresh campaign notes Brings every note of the campaign into Dragonroll/<Campaign>/, folders and nesting included, and updates the ones already there. Imported notes keep their place in the campaign's folder tree.
Push active note to Dragonroll Sends the note you are in to the campaign: a new root note if it is not linked yet, or an update of the note it is linked to.

How a note knows where it belongs

An imported note carries three properties in its frontmatter:

---
dragonrollId: 665f1c…
dragonrollCampaign: 665f0a…
dragonrollTitle: The Salt Gull
---

They are what ties the file to its note in the campaign: they survive renames, and they are stripped from the markdown the plugin sends back, so they never show up in Dragonroll. Pushing a brand new local note adds them too, which is how the next push updates the same note instead of creating a copy.

Renaming the note's title in Dragonroll renames the imported file on the next import; renaming the file in Obsidian renames the note in Dragonroll on the next push.

Your edits are not overwritten

The plugin remembers how a note looked the last time it was imported or pushed, and uses that as the baseline:

Since the last sync What the import does
Only the campaign's copy changed The local file is updated
Only your local file changed Your file is kept as it is, and reported for you to look at
Both changed Your file is kept as it is, and reported for you to look at
Neither changed Nothing is touched

So a note you were rewriting in Obsidian is never quietly replaced: the plugin leaves it alone and tells you it is waiting. Pushing is the deliberate direction — it writes the active note's current title and content into Dragonroll.

A note that is linked to a different campaign cannot be pushed while another campaign is selected: switch the campaign in the plugin settings first.