78 lines
3.2 KiB
Markdown
78 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
<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:
|
|
|
|
```yaml
|
|
---
|
|
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.
|