AgentSkillsCN

formatting-notion-pages

为 Notion 页面应用丰富格式——切换按钮、引用框、标题，以及样式化文本。适用于通过 Notion MCP 服务器创建或格式化 Notion 文档时使用。

SKILL.md
--- frontmatter
name: formatting-notion-pages
description: Apply rich formatting to Notion pages - toggles, callouts, headers, and styled text. Use when creating or formatting Notion documents via the Notion MCP server.

Formatting Notion pages

Reference guide for creating and formatting Notion pages with rich block types and text styling via the Notion MCP.

When to use this skill

  • •User asks to create a Notion page with formatting
  • •User wants to format or restructure an existing Notion page
  • •User wants to convert plain text or markdown into Notion content

Contents

For detailed JSON examples of all block types, see blocks-reference.md.

Block types

Text blocks

TypeKey Properties
paragraphrich_text, color
heading_1, heading_2, heading_3rich_text, is_toggleable, color
togglerich_text, color, children
quoterich_text, color
calloutrich_text, icon, color
coderich_text, language, caption

Callout icons: { "type": "emoji", "emoji": "💡" } or { "type": "external", "external": { "url": "..." } }

Code languages: javascript, python, typescript, bash, json, html, css, sql, markdown, yaml, and 60+ more.

List blocks

TypeKey Properties
bulleted_list_itemrich_text, color, children
numbered_list_itemrich_text, color, children
to_dorich_text, checked, color

Table blocks

json
{
  "type": "table",
  "table": {
    "table_width": 3,
    "has_column_header": true,
    "has_row_header": false,
    "children": [/* table_row blocks */]
  }
}

Each table_row has cells - an array of rich_text arrays.

Layout blocks

TypeKey Properties
column_listchildren (array of column blocks)
columnchildren (any blocks)
divider(empty object)
table_of_contentscolor
breadcrumb(empty object)

Media blocks

TypeKey Properties
imagetype: "external", external.url, caption
videotype: "external", external.url, caption
pdftype: "external", external.url, caption
filetype: "external", external.url, caption, name
bookmarkurl, caption
embedurl, caption

Advanced blocks

TypeKey Properties
equationexpression (LaTeX)
synced_blocksynced_from, children
templaterich_text, children
link_to_pagetype: "page_id", page_id
child_pagetitle
child_databasetitle

Rich text formatting

Text object structure

json
{
  "type": "text",
  "text": {
    "content": "styled text",
    "link": null
  },
  "annotations": {
    "bold": false,
    "italic": false,
    "strikethrough": false,
    "underline": false,
    "code": false,
    "color": "default"
  }
}

Annotations

PropertyTypeDescription
boldbooleanBold text
italicbooleanItalic text
strikethroughbooleanStrikethrough text
underlinebooleanUnderlined text
codebooleanInline code style
colorstringText or background color

Colors

Text colors: default, gray, brown, orange, yellow, green, blue, purple, pink, red

Background colors: gray_background, brown_background, orange_background, yellow_background, green_background, blue_background, purple_background, pink_background, red_background

Links

json
{
  "type": "text",
  "text": {
    "content": "Click here",
    "link": { "url": "https://example.com" }
  }
}

Mentions

Page mention:

json
{
  "type": "mention",
  "mention": {
    "type": "page",
    "page": { "id": "page-uuid" }
  }
}

Database mention:

json
{
  "type": "mention",
  "mention": {
    "type": "database",
    "database": { "id": "database-uuid" }
  }
}

User mention:

json
{
  "type": "mention",
  "mention": {
    "type": "user",
    "user": { "id": "user-uuid" }
  }
}

Date mention:

json
{
  "type": "mention",
  "mention": {
    "type": "date",
    "date": {
      "start": "2026-01-11",
      "end": null,
      "time_zone": null
    }
  }
}

Link preview:

json
{
  "type": "mention",
  "mention": {
    "type": "link_preview",
    "link_preview": { "url": "https://example.com" }
  }
}

Inline equation

json
{
  "type": "equation",
  "equation": {
    "expression": "x^2 + y^2 = z^2"
  }
}

Mixed formatting example

Paragraph with multiple styles:

json
{
  "object": "block",
  "type": "paragraph",
  "paragraph": {
    "rich_text": [
      { "type": "text", "text": { "content": "This is " } },
      {
        "type": "text",
        "text": { "content": "bold" },
        "annotations": { "bold": true }
      },
      { "type": "text", "text": { "content": " and " } },
      {
        "type": "text",
        "text": { "content": "highlighted" },
        "annotations": { "color": "yellow_background" }
      },
      { "type": "text", "text": { "content": " text." } }
    ]
  }
}

MCP tool usage

Fetch existing page

code
mcp__notion-personal__notion-fetch
id: "page-uuid-or-url"

Create page with content

code
mcp__notion-personal__notion-create-pages

Request body:

json
{
  "parent": { "page_id": "parent-page-uuid" },
  "properties": {
    "title": [{ "text": { "content": "Page Title" } }]
  },
  "children": [
    // Block objects
  ]
}

For database parent:

json
{
  "parent": { "database_id": "database-uuid" },
  "properties": {
    "Name": {
      "title": [{ "text": { "content": "Page Title" } }]
    }
    // Other database properties
  },
  "children": []
}

Update page properties

code
mcp__notion-personal__notion-update-page

Note: To add blocks to an existing page, you need the block append endpoint which may require direct API access.

API constraints

  • •Maximum 100 blocks per request
  • •Nested blocks limited to 2 levels via API
  • •Some block types (synced blocks, databases) have additional restrictions
  • •Rich text arrays have a maximum of 100 elements
  • •Text content limited to 2000 characters per rich text object