--- tags: help, obsidian, sync order: 100 description: keeping notes in an Obsidian vault and topics on d2 in step --- # Help: Obsidian sync The **Diesel Sync** plugin keeps notes in your Obsidian vault and topics in your d2 projects in step. Edit a topic in Obsidian, sync, and it's saved on d2; change it on d2 and the next sync brings it back. d2's wiki links (`[[name]]`) read the same in both. ## Install - In Obsidian, install the **BRAT** community plugin, then **BRAT → Add beta plugin** with `razie/obsidian-diesel-sync` ([the repo](https://github.com/razie/obsidian-diesel-sync)). - Enable **Diesel Sync** under Community plugins. Updates: **BRAT → Check for updates**. ## Set up - **Give the plugin its own token, not your password.** On the project's **Settings → AI permissions → AI tokens** page (`/ai/tokens`), New token: a name (*Diesel Sync*), **Kind: Tool** — a token for a program, which works directly under its own name and mints nothing — a **Role** (`user`) and a **level** (`member` to read and write, `mod` for more), and **untick *Its changes to topics are drafts*** so a sync saves the topic itself. Put it on the project's line: `d2spec = d2t_…`. Every sync then reads as *you via diesel-sync*, so the history says which device and which program wrote a line, and your password is nowhere in the plugin's settings. - **d2 projects**: one project per line, e.g. `d2spec`. Each gets a folder under the **Root folder** (`Diesel/d2spec`), and the first **Sync all** pulls its topics into it. - **User (email)** and **Password**: your d2 login, the fallback for a project with no token on its line. It works as it always did, and a token is the better choice: it can't log you in anywhere, you can revoke it from the tokens page without changing your password, and what it writes is recorded as the plugin's rather than as you in person. - **Leave *Its changes to topics are drafts* ticked** and the plugin proposes instead of saving: a sync's push becomes a draft on your **Drafts** page and the topic stays as it was, so the next pull brings the old text back over your note. Fine for a vault you only read from; not what you want for editing. On the free plan a token's writes are always drafts, so there use your login for editing. - **Sync d1 reactors**: turn it off if you only use d2. ## Where notes go - `Diesel///.md`: e.g. `Diesel/d2spec/Topic/Roadmap.md` is the topic `Roadmap`, `Diesel/d2spec/Spec/Spec.md` is `Spec:Spec`. - **Folder mappings** link any other folder to a project and category: `Notes/Ideas | d2spec.Topic`. - A new note in a project's folder becomes a new topic on the next sync. **Push current note** links any note to a topic you name. - Shared pages (this Help, the base skills) aren't synced: they belong to d2, not to your project. ## Syncing - **Sync all mapped notes** (command, or the ribbon icon): every linked note both ways, plus topics new on d2 (**Pull new topics**). **Auto-sync every N minutes** runs it on a timer. - **Sync current note**, **Pull topic by wpath…**, **Pull topics by tag…**, **Open current note on the reactor**. - A sync always writes the published topic. Drafts waiting on d2 aren't pulled or merged. - **Sync only local edits**: with Obsidian Sync across devices, each device pushes only what was typed on it. ## Conflicts When both sides changed, the plugin merges them. Edits in different places combine cleanly; edits to the same lines are marked in the note between `vvvvvvv obsidian` and `^^^^^^^ end`, with d2's copy saved next to it as `.diesel-conflict.md`. Fix the marked blocks and sync again: a note with markers left is never pushed. **Keep local (force push)** or **Take reactor copy (force pull)** settles it in one go. ## Deletes A topic deleted on d2 sends its note to Obsidian's trash on the next sync, unless you edited the note since: then it's kept and reported. If most of a project's notes look deleted at once (a wrong URL or login), nothing is deleted. Turn it off with **Delete notes whose topic was deleted**. A note you delete in Obsidian is never deleted on d2 and isn't pulled back. ## When something goes wrong - The plugin keeps its own log: every call to d2 with its status, and every error. Passwords and tokens are never in it. - **Upload log to d2** (command) sends it to the **Log project**'s detailed log, so an admin or agent can read what happened. **Upload the log when a sync has errors** does it by itself, at most every 10 minutes. - **Device name** says which device the lines came from. ## FAQ - **I get "HTTP 401".** Check the project's token, or the user and password. After one refusal the plugin stops calling that project until the next sync, so it doesn't lock your login. A token that was revoked, or that has expired, answers 401 too: make a new one and put it on the project's line — a tool token mints nothing and renews nothing, so there is no second credential to chase. - **My edits keep coming back as the old text.** The token's changes are drafts: the push went to your Drafts page and the topic never changed, so the next pull overwrites the note. Make a new token with *Its changes to topics are drafts* unticked — that setting is fixed once a token exists, and only its role can be changed later — or publish what is waiting on `/drafts`. - **A note says "left alone (d1 sync is off)".** It's linked to an old dieselapps reactor. Turn **Sync d1 reactors** back on, or move the note out of the folder. - **Can I sync another project's topics?** Only projects you list, with a login or token that can read them.