Document Section Editing

Structured markdown operations: read, edit, and manage document sections by heading instead of line numbers or string matching.

Overview

Seven features built on a shared heading-parsing foundation:

Recommended Workflow

edit_section

Purpose: Whole-section operations on markdown files — replace content, insert new sections, or remove existing ones. Addresses sections by heading, not line numbers.

Parameters:

Actions:

• replace — Replaces the section body. Pass body only — the heading is preserved automatically. If your content includes a heading line, smart detection kicks in and replaces the heading too.
• insert_before — Inserts content as a new section before the target.
• insert_after — Inserts content as a new section after the target.
• remove — Deletes the entire section (heading + body).

Example — replace a section’s body:

{
  "path": "docs/ROADMAP.md",
  "heading": "## What's Next",
  "action": "replace",
  "content": "- Feature A\n- Feature B\n- Feature C\n"
}

Example — insert a new section after an existing one:

{
  "path": "docs/ROADMAP.md",
  "heading": "## What's Built",
  "action": "insert_after",
  "content": "## What's In Progress\n\n- Working on X\n- Prototyping Y\n"
}

Example — remove a section:

{
  "path": "docs/ROADMAP.md",
  "heading": "## Deprecated",
  "action": "remove"
}

read_file — Heading Navigation

Single heading: heading=

Read one section by heading. Returns the section content with line range and breadcrumb (parent headings).

{
  "path": "docs/ROADMAP.md",
  "heading": "## What's Next"
}

Multiple headings: headings=[]

Read multiple sections in a single call. More efficient than separate calls.

{
  "path": "docs/ROADMAP.md",
  "headings": ["## What's Built", "## What's Next"]
}

Complete mode: mode="complete"

Returns the entire file inline (bypasses the output buffer) with a delivery receipt showing section count and checkbox progress. Scoped to files in plans/ directories only.

{
  "path": "plans/implementation-plan.md",
  "mode": "complete"
}

When to use: Only when you truly need the full plan. For targeted reads, prefer the heading map (read_file(path)) followed by headings=[].

edit_file — Heading-Scoped Editing

Scoped matching: heading=

Restricts old_string matching to the lines within a specific section. Prevents accidental matches in other parts of the file.

{
  "path": "docs/ROADMAP.md",
  "heading": "## What's Next",
  "old_string": "Feature A",
  "new_string": "Feature A ✅"
}

Batch mode: edits=[]

Multiple edits applied atomically in a single write. Each edit can optionally have its own heading scope.

{
  "path": "docs/plan.md",
  "edits": [
    {
      "old_string": "- [ ] Step 1",
      "new_string": "- [x] Step 1",
      "heading": "## Task A"
    },
    {
      "old_string": "- [ ] Step 2",
      "new_string": "- [x] Step 2",
      "heading": "## Task B"
    }
  ]
}

Fuzzy Heading Matching

All heading parameters (heading= on read_file, edit_file, edit_section) use a 4-tier matching strategy:

1. Exact match — ## Auth matches ## Auth
2. Format-stripped — ## \Auth`matches## Auth` (backticks, bold, italic stripped)
3. Prefix match — ## Auth matches ## Authentication & Authorization
4. Substring match — Auth matches ## Authentication & Authorization

Headings inside fenced code blocks are ignored.

Section Coverage Tracking

The server tracks which markdown sections you’ve read during a session. This powers two hints:

• On reads: When you read part of a file, the response includes an unread list showing sections you haven’t seen yet.
• On writes: When you edit a file with unread sections, a warning appears so you can verify your edit doesn’t conflict with unseen content.

Coverage resets when the file is modified on disk (mtime-based invalidation).

Choosing the Right Tool