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

• Block types - Quick reference for all block types
• Rich text formatting - Annotations, colors, links, mentions
• MCP tool usage - How to use the Notion MCP tools
• API constraints - Limits and restrictions

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

Block types

Text blocks

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

Table blocks

{
  "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

Media blocks

Advanced blocks

Rich text formatting

Text object structure

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

Annotations

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

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

Mentions

Page mention:

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

Database mention:

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

User mention:

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

Date mention:

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

Link preview:

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

Inline equation

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

Mixed formatting example

Paragraph with multiple styles:

{
  "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

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

Create page with content

mcp__notion-personal__notion-create-pages

Request body:

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

For database parent:

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

Update page properties

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