JokeBakery Sync

Two-way sync between JokeBakery and an Obsidian vault. Your sprints, jokes, lists and gigs become Markdown files you can read and edit in Obsidian; edits flow back to JokeBakery on the next sync.

What you get in the vault

<folder>/
  Sprints/
    2026-06-06.md        # one "10 in 10" sprint per file, named by its date
  Jokes/
    whats-the-deal-with-airline-food.md
  Lists/
    dentist.md           # one reusable list per file
  Gigs/
    2026-07-14-the-comedy-cellar.md   # one performance, with how it went
  Conflicts/             # auto-created only when a sync conflict happens

• Sprints → Sprints/YYYY-MM-DD.md. A numbered list of joke lines. If you do two sprints in one day the second is …-2.md; identity is the bw-id in the file's frontmatter, not the filename, so renaming is safe.
• Jokes → Jokes/<slug>.md. Editable prose under ## Setup, ## Development, ## Punchline, plus ## Notes and ## Scratchpad. Structured fields (stage, status, families, theme, angle) are Obsidian properties; rhythm/IEN markup rides in an opaque bw-meta property. The joke's JokeBakery tags are its Obsidian tags, so they show in the tag pane and in search. They are read-only here: a space in a name becomes a hyphen (big-joke) because Obsidian will not index a tag with a space, and tagging happens in JokeBakery.
• Lists → Lists/<slug>.md. A user-owned, reusable list: its items are a plain bullet list in the body; edit them here. A list can be attached to many jokes (attach/detach in JokeBakery).
• Gigs → Gigs/<date>-<venue>.md. The set as you performed it, plus how it went. See below.

A joke's ## Lists section is now a read-only list of the labels attached to that joke — open the matching note in Lists/ to edit a list's contents. ## Alternative punchlines and ## Setup versions are likewise read-only — manage those in JokeBakery.

Gigs

A gig note is where you write up a set after you've done it. Each one carries the lineup you performed, with a link through to every joke's own note, so the gig is a way back into the material rather than a dead record.

You can edit: venue, bill position, who you followed, the vibe, the crowd, actual minutes, seconds to the first applause break, the recording URL and whether you've reviewed it; the ## What went well, ## What went badly, ## Notes and ## Routine notes sections; and per joke in the lineup, its rating (1-5), laugh types and note.

You can't edit here: the date, the set it came from, the running order, which jokes were in it, or the ## Next time actions. Those belong to the gig itself — change them in JokeBakery. A gig is also created in JokeBakery, at the moment you log a set: a gig note you write by hand in Gigs/ has nothing to attach to and is skipped (the plugin tells you so).

Laugh types are the ones from the app: Applause break, Rolling, Recognition, Titter, Groan, Gasp, Cheer, Silence. Write them as a comma-separated list. If you type something that isn't a laugh type, or a rating outside 1-5, that one value is left unchanged and the sync report says why — the rest of your edits still go through.

Setup

1. In JokeBakery, go to Settings → Obsidian sync and create an access token. Copy it (you only see it once).
2. Install this plugin (see below), enable it, open its settings, and fill in:
   • Server URL — your JokeBakery address, e.g. https://jokebakery.com
   • Access token — the token you just created
   • Vault folder — defaults to JokeBakery
3. Click Test connection, then Sync now. Auto-sync (on startup + on a timer) is on by default.

Creating items from Obsidian

• New sprint: add a note in <folder>/Sprints named after its date (2026-06-10.md) and write one joke per line (numbered or not).
• New joke: add a note in <folder>/Jokes. Use ## Setup / ## Punchline headings, or just write freeform — freeform text lands in the joke's scratchpad.
• New list: add a note in <folder>/Lists. The note title (or label property) is the list name; write one item per bullet line.

On the next sync these are created in JokeBakery and get their bw-id written back into the file.

Conflicts

Sync is last-writer-wins by modified time. If the same item changed on both sides between syncs, nothing is lost: the losing version is written to <folder>/Conflicts/… for you to merge by hand.

Deletions

Deletions sync both ways:

• Delete a joke, sprint, list or gig in JokeBakery → its file is removed from the vault on the next pull (it goes to your trash, following Obsidian's "Deleted files" setting, so it's recoverable).
• Delete a synced file in Obsidian → the item is removed in JokeBakery on the next push. (JokeBakery keeps it as a soft-deleted tombstone, so it's recoverable in the database if needed.)

As a safety net, if 20 or more deletions are queued at once (e.g. the sync folder itself was deleted), they are held back: auto-syncs skip them and a manual Sync now asks for confirmation before deleting anything server-side.

Caveat: Obsidian-side deletions are detected while the plugin is running. Delete items as individual files — deleting a synced file you no longer want is the reliable signal. If a synced file goes missing without a delete event (e.g. it was removed outside Obsidian), the next pull treats the server as authoritative and restores it.

Limitations

• Rhythm/IEN word-index markup and alternative punchlines are pull-only — edit them in JokeBakery, not Obsidian. If you delete lines from a slot in Obsidian, stale IEN voice tags past the new line count are dropped on push; reordering lines can still leave tags on the wrong line (fix in JokeBakery).
• Tags are pull-only. A joke note's tags property mirrors its JokeBakery tags on every sync, including when only the tag changed (a rename, an attach or a detach rewrites the untouched notes it is on). Editing the property in Obsidian does nothing on the next push; the app is where tags change.
• Routines, sets and breakdowns don't sync. This is deliberate, not a gap waiting to be filled. The vault is for the writing — the material itself and the record of performing it. Assembling routines into sets is performance-building work that wants the app's structured UI (and the desktop client), and flattening it into Markdown would produce files that are tedious to edit and easy to corrupt. If that changes, they need the same treatment gigs got: an explicit read-only/editable split per field, and client-side validation of anything the server constrains.
• A joke's status can be set from the vault, but only to one of the values JokeBakery uses (tested, working, hit, needsrewrite, retired). Anything else is ignored rather than sent.

Installing

With BRAT (recommended)

The easiest way to add this to Obsidian today:

1. Install the BRAT community plugin (Beta Reviewer's Auto-update Tool) and enable it.
2. BRAT → Add Beta plugin → paste this repo: https://github.com/jimhooker/jokebakery-obsidian
3. BRAT installs the latest release. In Obsidian go to Settings → Community plugins and enable JokeBakery Sync, then configure it (see Setup).

BRAT keeps the plugin updated as new releases are published here.

Manual

1. Download main.js, manifest.json and styles.css from the latest release, or build them yourself with npm install && npm run build.
2. Copy them into <your-vault>/.obsidian/plugins/jokebakery-sync/.
3. In Obsidian: Settings → Community plugins, enable JokeBakery Sync.

Migrating from a pre-0.4.0 (BakerWriter-era) install

0.4.0 changed the plugin id from bakerwriter-sync to jokebakery-sync, so Obsidian treats it as a new plugin. To keep your settings and sync state:

1. Install 0.4.0 or later (BRAT or manual) but don't enable it yet.
2. Copy <vault>/.obsidian/plugins/bakerwriter-sync/data.json into <vault>/.obsidian/plugins/jokebakery-sync/.
3. Enable JokeBakery Sync, then uninstall the old BakerWriter Sync.

Skipping step 2 also works — re-enter your token and folder and run a sync; files are matched by their bw-id, so nothing duplicates.

Develop

npm run dev runs esbuild in watch mode. Symlink this folder into your vault's .obsidian/plugins/ to iterate live.

npm test runs two vitest suites: tests/serialize.test.ts (Markdown ⇄ DTO round-trips) and tests/sync.test.ts, which drives the real SyncEngine against an in-memory vault and a fake server. Run both after touching src/serialize.ts or src/sync.ts. The sync suite is the one that guards the rules about what may be pushed — above all that a frontmatter key a note doesn't carry is never sent as an empty value, because the server would apply that as "clear this field".

npm run build typechecks (src and tests) then bundles.

Where the source lives

This is the release repo: the one BRAT watches and the one releases are tagged from (a tag named after the version, with no v prefix, builds main.js and attaches it with manifest.json and styles.css to a GitHub Release). The plugin is developed and tested inside the JokeBakery app repo and mirrored here, so a change lands in the app repo first and arrives here with the release that ships it. Issues are welcome here either way.

Privacy and network use

This plugin is a companion to the hosted JokeBakery service and talks only to https://jokebakery.com (the Server URL setting exists for development builds). On each sync it sends the contents of notes inside the configured sync folder (your jokes, sprints, lists and crashes) together with your access token, and pulls your items back. No other part of your vault is read or transmitted, and there are no analytics or third-party services. Your access token is stored in the plugin's data.json inside your vault — treat it as a secret; you can revoke it any time in JokeBakery under Settings → Obsidian sync.

Using the plugin requires a JokeBakery account (currently invite-only).

How it works

The plugin talks to JokeBakery's /api/sync REST API with a Bearer token. Each sync runs push (send new/edited vault files) then pull (write changed server items into the vault). All Markdown ⇄ JSON translation happens here in the plugin; the server only ever speaks JSON. See src/serialize.ts for the file format and src/sync.ts for the sync algorithm.