update_section
Update a Notion page section by heading name: replace content from the heading to the next section boundary with markdown, keeping other sections intact.
Instructions
DESTRUCTIVE, no rollback: this tool deletes blocks in the section, then writes new blocks. If the write fails mid-call, the section is left partially or fully emptied; for most sections the heading anchor is deleted, so a retry can fail with "heading not found." For irreplaceable sections, duplicate_page the target first so you have a restore point.
Update a section of a page by heading name. Finds the heading, replaces everything from that heading to the next section boundary. For H1 headings, the section extends to the next heading of any level. For H2/H3 headings, it extends to the next heading of the same or higher level. Include the heading itself in the markdown. If the section starts at the first block, the replacement markdown must start with the same heading type so following sections stay in place. With preserve_heading:true, the existing heading block ID, text, type, comments, and toggleable state are preserved, but the section body blocks and existing toggleable-heading children are still destructively replaced; replacement markdown is treated as body-only, and a leading matching heading is stripped for compatibility. More efficient than replace_content for editing one section of a large page. Page mentions: @Title. Returns { deleted, appended }, plus deleted_blocks for the deleted top-level blocks when present and block_map for the top-level appended blocks when present. A dry run instead returns { success: true, dry_run: true, operation, page_id, heading, target_block_id, target_block_type, preserve_heading, deleted, appended, would_delete_block_ids, append_parent_id }, plus append_after_block_id when the append is anchored to a preceding block, and would_update with would_update_block_id when the heading block itself is rewritten.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | Preview validation and planned effect without mutating Notion. Default false. | |
| heading | Yes | Heading text to find (case-insensitive) | |
| page_id | Yes | Page ID | |
| markdown | Yes | Replacement markdown including the heading | |
| preserve_heading | No | Preserve the existing heading block and replace only the section body. Default false. | |
| return_block_map | No | Include block_map in the response. Default true. Set false to skip the per-block id list when you do not plan to edit individual blocks. | |
| collapse_soft_wraps | No | Collapse single line breaks to spaces per CommonMark before writing. Default false (single line breaks are kept as they are today). Recommended when uploading hard-wrapped prose files (e.g. repo markdown wrapped at 78 columns). Do not use when re-uploading content read from Notion, or intentional line breaks will be lost. Blank lines and code blocks are unaffected. Note: replace_content renders an in-paragraph line break as a separate paragraph regardless of this option. |