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