notion-core-workflow-b

name	notion-core-workflow-b
description	Work with Notion blocks, rich text, comments, and page content. Use when you need to read a page's block tree, append formatted content (headings, lists, callouts, code), edit or delete blocks, build rich text with annotations, or manage page and block comments through the Notion API. Trigger with phrases like "notion blocks", "notion page content", "notion rich text", "notion comments", "notion append blocks".
allowed-tools	Read, Write, Bash(npm:*)
version	1.38.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","productivity","notion"]
compatibility	Designed for Claude Code

Notion Core Workflow B — Blocks, Content & Comments

Overview

Secondary workflow for content operations: reading block trees, appending content, building rich text with annotations, and managing comments. SKILL.md keeps the flow at a high level; every full implementation lives in references/implementation.md.

Prerequisites

• Completed notion-install-auth setup
• A Notion page shared with your integration
• Familiarity with notion-core-workflow-a (databases/pages)

Authentication

All calls use the @notionhq/client SDK authenticated with an integration token read from process.env.NOTION_TOKEN. The token is provisioned by the notion-install-auth skill (internal integration secret) — do not hard-code it. The page or block being edited must be explicitly shared with that integration, or calls return object_not_found.

Instructions

The workflow has six steps. The client is created once and reused:

import { Client } from '@notionhq/client';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

1. Retrieve block children — page through notion.blocks.children.list with a start_cursor loop (100 blocks/page) until has_more is false.
2. Read blocks recursively — walk each block, and when has_children is true recurse to build a nested tree; blockToText flattens a block's rich_text to a plain string.
3. Append content blocks — one notion.blocks.children.append call adds headings, formatted paragraphs, bulleted/numbered lists, to-dos, code, callouts, quotes, dividers, and toggles.
4. Rich text annotations — each rich-text span carries annotations (bold, italic, strikethrough, underline, , ); spans can be plain text, links, user/page/date mentions, or LaTeX equations.