# Notion Manage Content

> Manage Notion page content — insert, append, update blocks, delete blocks, override/replace content, and create new linked pages. Supports full markdown including tables.

- Skill: `theexperiencecompany/notion-manage-content` (Agent Skill)
- Install (CLI): `npx skillmds@latest add theexperiencecompany/notion-manage-content`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theexperiencecompany/notion-manage-content/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: theexperiencecompany (https://skillmd.com/u/theexperiencecompany)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/theexperiencecompany/notion-manage-content

---


# Notion: Manage Page Content

## When to Activate

- User asks to update, edit, refactor, append, or insert into an existing Notion page
- User wants to delete specific blocks or override/replace a page's content
- User references "that page", "the doc", "the notes", or an existing workspace artifact
- User wants to restructure sections, rewrite content, or add new information
- Content is large or complex enough to warrant a new dedicated page

## Core Rules

- Never assume page IDs. Discover first.
- Never write blind. Read current content before editing.
- Prefer markdown workflows for text/lists/headings/tables:
  - Read: `NOTION_FETCH_PAGE_AS_MARKDOWN`
  - Write/append: `NOTION_INSERT_MARKDOWN` (supports full markdown including tables)
- Avoid destructive edits unless the user explicitly asks (deleting blocks, overwriting large sections, moving/archiving).
- If the content to add is substantial and self-contained (e.g., a full report, meeting notes, reference doc), **consider creating a new sub-page** and linking it in the parent (see "When to Create a New Page" below).

If the user wants to change page metadata (title/properties), use `NOTION_UPDATE_PAGE`.
If the user wants to move a page, use `NOTION_MOVE_PAGE`.

---

## Workflow

### Step 1: Discover the Target

```
NOTION_FETCH_DATA(fetch_type="pages", page_size=50)
NOTION_FETCH_DATA(fetch_type="pages", query="<keywords>", page_size=50)
```

If multiple plausible pages exist, present the best 2-3 (title + parent + last edited) and ask ONE focused question.

### Step 2: Read Current Content

```
NOTION_FETCH_PAGE_AS_MARKDOWN(page_id="<uuid>")
```

Identify:
- existing structure (headings, block IDs)
- where new content should be inserted
- any tone/formatting constraints

To get block IDs for precise positioning:
```
NOTION_FETCH_BLOCK_CONTENTS(block_id="<page_id>")         # first-level children
NOTION_FETCH_ALL_BLOCK_CONTENTS(block_id="<page_id>")     # full recursive tree
```

### Step 3: Plan the Change

Write a short plan:
- what section to add/edit
- what to preserve
- whether appending, inserting after a block, updating in-place, or replacing

---

## Operations Reference

### Append / Insert Content

**General markdown content (text, headings, lists, checkboxes):**
```
NOTION_INSERT_MARKDOWN(
  parent_block_id="<page_or_block_id>",
  markdown="## Section Title\n- Item one\n- Item two\n- [ ] Task"
)
```

**Insert AFTER a specific block** (use block ID from NOTION_FETCH_BLOCK_CONTENTS):
```
NOTION_INSERT_MARKDOWN(
  parent_block_id="<page_id>",
  after="<block_id_to_insert_after>",
  markdown="New content here"
)
```

**Bulk content (multiple blocks, large inserts):**
```
NOTION_ADD_MULTIPLE_PAGE_CONTENT(
  parent_block_id="<page_id>",
  content_blocks=[
    {"content": "First paragraph", "block_property": "paragraph"},
    {"content": "## New Heading", "block_property": "heading_2"},
    {"content": "List item", "block_property": "bulleted_list_item"}
  ]
)
```

**Specialized block types:**
```
NOTION_APPEND_TEXT_BLOCKS(...)      # paragraphs, headings, lists
NOTION_APPEND_TASK_BLOCKS(...)      # to-do checkboxes, toggles, callouts
NOTION_APPEND_CODE_BLOCKS(...)      # code snippets, quotes, equations
NOTION_APPEND_MEDIA_BLOCKS(...)     # images, videos, audio, embeds, bookmarks
NOTION_APPEND_LAYOUT_BLOCKS(...)    # dividers, TOC, columns
```

---

### Tables

**Use markdown table syntax directly** — `NOTION_INSERT_MARKDOWN` automatically converts it to a proper Notion table via `NOTION_APPEND_TABLE_BLOCKS` under the hood:

```
NOTION_INSERT_MARKDOWN(
  parent_block_id="<page_id>",
  markdown="""
## Task Tracker

| Name | Status | Due |
|------|--------|-----|
| Task A | In Progress | Mar 10 |
| Task B | Done | Mar 5 |
| Task C | Blocked | Mar 15 |
"""
)
```

If you need more control (e.g., inserting a table at a specific position), use `NOTION_APPEND_TABLE_BLOCKS` directly:

```
NOTION_APPEND_TABLE_BLOCKS(
  block_id="<page_id>",
  tables=[
    {
      "table_width": 3,
      "has_column_header": true,
      "rows": [
        {"cells": [
          [{"type": "text", "text": {"content": "Name"}}],
          [{"type": "text", "text": {"content": "Status"}}],
          [{"type": "text", "text": {"content": "Due"}}]
        ]},
        {"cells": [
          [{"type": "text", "text": {"content": "Task A"}}],
          [{"type": "text", "text": {"content": "In Progress"}}],
          [{"type": "text", "text": {"content": "Mar 10"}}]
        ]}
      ]
    }
  ]
)
```

---

### Update Existing Block

To edit an existing block's text content in-place (must have block ID):

```
NOTION_UPDATE_BLOCK(
  block_id="<block_uuid>",
  content="Updated text content here"
)
```

> Limit: 2000 chars per block. Cannot change block type. Get block IDs via `NOTION_FETCH_BLOCK_CONTENTS`.

---

### Delete Blocks

To delete (archive) specific blocks:

```
NOTION_DELETE_BLOCK(block_id="<block_uuid>")
```

> This archives the block (recoverable from Trash). To delete multiple blocks, call this for each block ID. Get IDs first via `NOTION_FETCH_BLOCK_CONTENTS`.

---

### Override / Replace Page Content

To completely replace a page's content (destructive — confirm with user first):

```
NOTION_REPLACE_PAGE_CONTENT(
  page_id="<page_uuid>",
  new_content=[...],   # Array of block objects
  backup=true          # Optional: backup current content before replacing
)
```

> This deletes all existing children and inserts new ones. Always confirm with user before using. The `backup=true` flag creates a recoverable snapshot.

---

## When to Create a New Page

Create a sub-page instead of inserting inline when:
- Content is long (full report, structured document, reference article)
- Content is self-contained and reusable on its own
- User asks to "create a doc", "write a page about", or "document this"
- Inserting inline would clutter the parent page

**Workflow:**
```
# 1. Create the sub-page under the parent
NOTION_CREATE_NOTION_PAGE(
  title="Q1 Report",
  parent_id="<parent_page_uuid>"
)

# 2. Add content to the new page
NOTION_INSERT_MARKDOWN(
  parent_block_id="<new_page_id>",
  markdown="## Overview\n..."
)

# 3. Link the new page inside the parent page
# Notion auto-links child pages — confirm by mentioning the link to the user
```

After creating, always report:
```
Created: "Q1 Report"
  Parent: Team Workspace > Projects
  Sections: Overview, Results, Next Steps
  Link: [Open in Notion](<url>)
```

---

### Step 4: Verify and Summarize

Re-fetch the affected portion and summarize:
- what changed
- what stayed the same
- anything that needs user confirmation

---

## Anti-Patterns

- Creating a new page when the user wanted an edit (unless confirmed or content warrants it)
- Overwriting large content without explicit instruction
- Editing without reading current content first
- Dumping raw API output instead of summarizing
- Not providing the link to a newly created page