Atomic YAML frontmatter mutation — set, update, or delete keys via a
gray-matter round-trip.
Replaces the error-prone "find/replace YAML text" pattern. Parses the
frontmatter, applies the diff, re-serializes via js-yaml (so date-like
strings, multi-line values, pipe-containing strings, etc. stay correct).
Reports per-key change markers in changed_keys: "+key" for added,
"~key" for updated, "-key" for deleted. No-op writes (every value
already matches) are skipped — the response still reports the empty diff.
WRITE TOOL — only registered with --enable-write.
{ path, changed_keys, before, after, dry_run } — before
and after are the full frontmatter maps so the caller can diff.
Throws
If set is empty, vault is read-only, or target can't
be resolved.
Example
// Mark a draft as published, set a date, delete a stale key awaitfrontmatterSet(vault, { path: "Posts/Article.md", set: { status: "published", published_at: "2026-05-15", draft_notes: null// deletes the key } });
Atomic YAML frontmatter mutation — set, update, or delete keys via a gray-matter round-trip.
Replaces the error-prone "find/replace YAML text" pattern. Parses the frontmatter, applies the diff, re-serializes via js-yaml (so date-like strings, multi-line values, pipe-containing strings, etc. stay correct). Reports per-key change markers in
changed_keys:"+key"for added,"~key"for updated,"-key"for deleted. No-op writes (every value already matches) are skipped — the response still reports the empty diff. WRITE TOOL — only registered with--enable-write.