Developer Guide

Install required tools

Install these once per machine.

Verify in the terminal:

$ node --version   # must be v18 or higher
$ npm --version
$ git --version

VS Code extensions

Install via Ctrl+Shift+X:

• dbaeumer.vscode-eslint — ESLint
• esbenp.prettier-vscode — Prettier
• usernamehw.errorlens — Error Lens
• ritwickdey.liveserver — Live Server (for the docs/ HTML files)

Project structure

Symbolic link setup

Keep your repo anywhere on disk and link it into Obsidian's plugin folder. esbuild then writes main.js directly where Obsidian loads it — no copying needed.

macOS / Linux

ln -s ~/Dev/yaml-path-sync \
  ~/Documents/MyVault/.obsidian/plugins/yaml-path-sync

Windows (PowerShell as Administrator)

New-Item -ItemType SymbolicLink `
  -Path "C:\...\plugins\yaml-path-sync" `
  -Target "C:\Users\Name\Dev\yaml-path-sync"

Project setup

Do this once after cloning or creating the project.

• 1

  Open in VS Code

  terminal

  $ cd ~/Dev/yaml-path-sync
  $ code .

• 2

  Install dependencies

  terminal

  $ npm install
  added 19 packages in 885ms

  This installs esbuild, TypeScript, and the Obsidian type definitions. Run only once (or after changing package.json).

• 3

  Enable the plugin in Obsidian

  Settings → Community Plugins → disable Restricted Mode → toggle YAML Path Sync on.

  ℹ️

  If the plugin doesn't appear, restart Obsidian once after creating the symlink.

Watch mode

Start this at the beginning of every session. Leave it running in the background.

$ npm run dev
Watching for changes … (Ctrl+C to stop)

Every time you save src/main.ts, esbuild recompiles in under 100 ms and writes a new main.js automatically. Stop with Ctrl+C.

Alternatively press Ctrl+Shift+B in VS Code to run it as a background task.

Reload the plugin in Obsidian

Obsidian doesn't detect file changes automatically. After each rebuild you need to reload.

Debug

Open DevTools in Obsidian

• Windows / Linux: Ctrl + Shift + I
• macOS: Cmd + Option + I

Chrome DevTools opens — identical to what you see in a browser.

Console tab

All console.log() calls from the plugin appear here. Filter by typing YAML Path Sync in the filter box.

YAML Path Sync: loaded.
YAML Path Sync: "path" set on create → 02 Areas/C/Pointer C.md
YAML Path Sync: "path" updated → Archiv/C/Pointer C.md

Add your own debug output anywhere in src/main.ts:

console.log('content:', content);
console.log('fieldExists:', fieldExists);
console.log('settings:', this.settings);

Breakpoints (Sources tab)

Because watch mode compiles with inline source maps, DevTools shows the original TypeScript — not compiled JS.

1. Click the Sources tab in DevTools
2. Find src/main.ts in the file tree
3. Click a line number to set a breakpoint
4. Trigger the action in Obsidian (create or move a file)
5. Execution pauses — hover over any variable to inspect its value

Attach VS Code debugger (optional)

Start Obsidian with the remote debug port, then press F5 in VS Code and select "Attach to Obsidian". Breakpoints set in src/main.ts will pause execution directly inside VS Code.

Type checking

esbuild skips type checks. Run this explicitly to catch type errors before releasing:

$ npm run check
# No output = no errors ✓
src/main.ts(42,5): error TS2322: ...

Production build

$ npm run build
Build complete.

Release

• 1

  Bump the version

  Update "version" in both manifest.json and package.json to the new version, e.g. "1.3.1".

• 2

  Production build + commit

  terminal

  $ npm run build
  $ git add .
  $ git commit -m "Release v1.3.1"
  $ git push

• 3

  Tag and push — triggers the GitHub Action

  terminal

  $ git tag v1.3.1
  $ git push origin v1.3.1

  The workflow at .github/workflows/release.yml detects the v* tag, builds the plugin, and creates a GitHub release with main.js and manifest.json attached. Watch progress at GitHub → Actions.

Troubleshooting