Address a heading, block, or frontmatter field — then read it back, or append, replace, and move content. No line numbers, no regex, no sed.
The obvious ways to edit Markdown programmatically all break on contact with real documents. Each one is handled by the engine, not by your code.
+The engine supplies every separator, so "X", "X\n", and "\nX\n" all produce the same document. One missing newline can never merge two paragraphs again.
A # Section in your content lands as a direct child of wherever it's written — the engine rebases levels, so pasted subtrees always fit their new depth.
Pass ifMatch with the document's version token. If the file changed under you, the patch throws instead of landing in the wrong place.
Two identical ### Fixed headings? The document map hands each occurrence a distinct address — a regex matches both, a path names exactly one.
Append rows as string[][] — cells are content, not source. Pipes are escaped for you and column counts are checked.
readTarget takes the same address as patch. Read at a scope, replace at that scope with the value unchanged: a guaranteed no-op.
Every address you can patch, you can also query. The bundled mdpatch CLI and the TypeScript API drive the same engine: two commands write, two retrieve.
| command | what it does | |
|---|---|---|
| mdpatch patch | write | quick flag-based form for common single edits |
| mdpatch apply | write | full instruction JSON — moves, table rows, ifMatch pipelines |
| mdpatch query | read | print a target's content: a section, a block, a frontmatter value |
| mdpatch print-map | read | show everything addressable — headings, blocks, fields, version token |
In the library, readTarget is the mirror image of patch — the same (targetType, target) address, read instead of written. Pull one section out of a note without parsing anything yourself.
An LLM agent shouldn't re-emit a 4,000-token file to add one paragraph — and with markdown-patch it can't mangle the 3,900 tokens it had no business touching. This is the engine behind Obsidian Local REST API's PATCH endpoints and MCP tools, where exactly that kind of client is the norm.
+ +Illustrative counts for a typical meeting note. Retrieval is cheap too: the agent reads the compact document map, not the whole file.
+print-map hands the model a few dozen tokens describing everything addressable — including distinct addresses for duplicate headings — plus a version token.
The model picks an address straight off the map and, if it needs context, query-reads just that section — no full-file round trips.
One small instruction lands the edit. Sent with ifMatch, a stale write throws instead of landing in the wrong place — and retrying from a fresh map is the agent's native gesture.