Replace in Note
vault_replace_in_noteFind and replace exact, case-sensitive text within a markdown note's body, preserving frontmatter properties. Replace the first match or all occurrences, or delete text with an empty replacement.
Instructions
Find and replace text in a markdown note's body. Matches exact text (case-sensitive). Properties are preserved; YAML formatting may be normalized to block style on first edit. Operates on the body only — properties must be edited via vault_update_properties or vault_write_note's properties parameter.
Example: vault_replace_in_note({ path: "Projects/plan.md", old_text: "TODO: write summary", new_text: "Summary complete." })
When to use: Targeted text changes within a single location — fixing typos, updating values, renaming terms, or removing a short line (new_text=""). Replaces text in place; does not move content across sections. To delete a large multi-line block, prefer vault_delete_span (short anchors instead of full old_text). To replace a large block by anchors instead of reproducing the full old_text, use vault_replace_span. To relocate content between headings, vault_patch_note to add at the target first, then remove from source (new_text="") — add-before-delete, so a failure duplicates the block instead of losing it.
Parameters:
old_text is matched in the body only — frontmatter properties are never searched. Include enough surrounding context to ensure uniqueness when the target text appears in multiple places.
old_text + new_text together determine the operation: a non-empty new_text is an edit; an empty new_text ("") is a deletion. No regex — exact text only.
replace_all_occurrences (default false) replaces only the first match — a safety default when old_text appears in multiple places. Set true for deliberate bulk renames or term replacements.
Errors:
"note not found" — path does not exist; check vault_list_notes for valid paths
"text not found" — old_text does not appear in the note body; verify exact text with vault_read_note
"oldText cannot be empty" — old_text must be at least one character
"absolute path blocked" — the path starts at the filesystem root; use a vault-relative path
"hidden path blocked" — the path targets a hidden (dot-prefixed) file or folder like ".obsidian/"; hidden paths are not editable, matching Obsidian
"concurrent write in progress" — another write to this note is in flight; re-read the note and retry
"new_text contains a control character" — new_text includes a non-printable control byte; remove it before writing
Obsidian syntax: new_text is Obsidian Flavored Markdown (no escaping applied). Watch for: #word = tag, [[ = wikilink, %% = comment block in replacement text.
Returns: Confirmation message with replacement count (number of occurrences replaced).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative path to the note, including the ".md" extension (e.g. "Projects/plan.md") | |
| new_text | Yes | Replacement text. Empty string ("") deletes the matched text. | |
| old_text | Yes | Exact text to find (case-sensitive). Matches in the body only — text inside frontmatter properties is not searched. | |
| replace_all_occurrences | No | Replace all occurrences (default: false — replaces first occurrence only) |