roam_update_page_markdown
Update a Roam page's markdown using smart diff to preserve block references and minimize changes, ideal for syncing external files or AI-assisted content updates.
Instructions
Update an existing page with new markdown content using smart diff. Preserves block UIDs where possible and generates minimal changes. This is ideal for:
Syncing external markdown files to Roam
AI-assisted content updates that preserve references
Batch content modifications without losing block references
⚠️ This REPLACES the page, it does not append. Any block your markdown does not account for is deleted. Pass the complete intended page, or use roam_process_batch_actions / roam_create_outline to change only part of one. Use dry_run: true to see the actions first.
How it works:
Fetches existing page blocks
Matches new content to existing blocks by text similarity
Generates minimal create/update/move/delete operations
Preserves UIDs for matched blocks (keeping references intact)
#.rm-hide / #.rm-private subtrees are excluded from the diff and left untouched — you cannot see them, so you cannot be asked to account for them. preserved_hidden reports how many, when any.
IMPORTANT: call roam_get_guidelines for this graph once per session, and load the Roam Markdown Cheatsheet, before using this tool.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| graph | No | Target graph key from ROAM_GRAPHS config. Defaults to ROAM_DEFAULT_GRAPH. Only needed in multi-graph mode. | |
| title | Yes | Title of the page to update | |
| dry_run | No | If true, returns the planned actions without executing them. Useful for previewing changes. | |
| markdown | Yes | New GFM markdown content for the page | |
| write_key | No | Write confirmation key. Required for write operations on non-default graphs when write_key is configured. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| stats | Yes | ||
| actions | Yes | Roam batch actions applied (or planned, when dry_run) | |
| success | Yes | ||
| summary | Yes | ||
| preserved_uids | Yes | Blocks whose UIDs survived the diff, so refs to them still resolve | |
| preserved_hidden | No | Present only when non-zero: how many #.rm-hide / #.rm-private blocks were excluded from the diff and left on the page untouched |