Version 2 of 5 · · Current version

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).
  • Enable Diesel Sync under Community plugins. Updates: BRAT → Check for updates.

Set up

  • User (email) and Password: your d2 login. They are kept in the plugin's settings on that device only.
  • 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.
  • A line can carry a project's AI token instead (d2spec = d2t_…, from the project's Tokens page). A token's writes become drafts, so for editing, your login is the better choice.
  • Sync d1 reactors: turn it off if you only use d2.

Where notes go

  • Diesel/<project>/<Category>/<name>.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 <name>.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 user and password, or the project's token. After one refusal the plugin stops calling that project until the next sync, so it doesn't lock your login.
  • 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.