BYOK Sync

Sync writing from your Bring Your Own Keyboard (BYOK) device into your Obsidian vault.

When you run a sync with the BYOK connected in disk mode, the plugin finds the device and copies each project's documents into a folder in your vault. Each project becomes a subfolder, and each document becomes a note.

BYOK device                              Your vault
Projects/Foo/Bar.txt     ──▶             BYOK/Foo/Bar.md

Usage

1. Install and enable BYOK Sync.
2. Connect your BYOK to your computer and put it in disk mode.
3. Run BYOK Sync: Sync now from the command palette, or select Sync now in the plugin's settings.
4. A notice shows how many notes were created or updated in the target folder (BYOK by default).

The plugin only syncs when you ask it to. It doesn't watch for the device or sync on startup.

Settings

Setting	Description
Target folder	Vault folder that projects are synced into. Defaults to BYOK.
Sync all projects	Turn off to pick which projects to sync. The list shows the projects found on your device.
Convert indentation	The BYOK saves each tab as 5 spaces. When on, leading spaces are converted to match your editor's indentation settings (Settings → Editor → Indent using tabs and Tab indent size).
Note extension	Save documents as Markdown notes (.md) or plain text (.txt).
Mount path override	Full path to the mounted device, if automatic detection doesn't find it.

How syncing works

Sync is one-way, from the device to your vault. The plugin never writes to the device.

• New documents on the device are created as notes.
• If a document changed on the device and you haven't edited its note, the note is updated.
• If you edited the note in Obsidian and the document didn't change on the device, your edits are kept.
• If both changed, your note is kept and the device version is saved next to it as Name (BYOK <date time>).md.
• Deleting a document on the device doesn't delete its note.

Device detection

The plugin looks for a mounted volume that contains a Projects folder and a Sync/library.json file, which is how the BYOK lays out its storage. It checks these locations:

• macOS: /Volumes/*
• Linux: /media/<user>/*, /run/media/<user>/*, and /mnt/*
• Windows: drive letters D: through Z:

If your device is mounted somewhere else, set Mount path override.

Disclosures

• Accesses files outside your vault. To find and sync your device, this plugin lists mounted volumes in the locations above and reads files from the BYOK's Projects folder. It only reads from the device and never modifies it. This is required because the BYOK appears as a separate USB drive, outside your vault.
• No network use. The plugin doesn't make any network requests or collect any data.

Requirements

Desktop only (macOS, Windows, Linux). The plugin uses Node.js file system APIs, which aren't available on mobile.

Development

make install    # install dependencies
npm run dev     # watch and rebuild main.js
make build      # type-check and build for production
make lint
make deploy VAULT="/path/to/vault"   # build and install into a vault

Releasing

Write the release notes in a Markdown file, then run:

make release VERSION=1.0.1 NOTES=notes.md

This checks that main is clean and in sync with origin/main. It then sets the version in manifest.json, versions.json, and package.json, lints and builds, commits, and pushes main along with an annotated 1.0.1 tag containing the notes. Pushing the tag runs the release workflow, which builds the plugin and publishes the GitHub release with main.js and manifest.json attached. If you leave out NOTES, the release notes are just "Release 1.0.1".

Don't create releases by hand on GitHub. If one already exists for the tag, the workflow attaches the files to it, but it doesn't update its notes.

License

MIT