formatting-notion-pages

Files (4)

• README.md
• SKILL.md
• blocks-reference.md
• hero.png · images/

SKILL.md (first lines)

# 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](#block-types) - Quick reference for all block types
- [Rich text formatting](#rich-text-formatting) - Annotations, colors, links, mentions
- [MCP tool usage](#mcp-tool-usage) - How to use the Notion MCP tools
- [API constraints](#api-constraints) - Limits and restrictions

For detailed JSON examples of all block types, see [blocks-reference.md](blocks-reference.md).

## Block types

### Text blocks

| Type | Key Properties |
|------|----------------|
| `paragraph` | `rich_text`, `color` |
| `heading_1`, `heading_2`, `heading_3` | `rich_text`, `is_toggleable`, `color` |
| `toggle` | `rich_text`, `color`, `children` |
| `quote` | `rich_text`, `color` |
| `callout` | `rich_text`, `icon`, `color` |
| `code` | `rich_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](blocks-reference.md#code).

### List blocks

| Type | Key Properties |
|------|----------------|
| `bulleted_list_item` | `rich_text`, `color`, `children` |
| `numbered_list_item` | `rich_text`, `color`, `children` |
| `to_do` | `rich_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

| Type | Key Properties |
|------|----------------|
| `column_list` | `children` (array of `column` blocks) |
| `column` | `children` (any blocks) |
| `divider` | (empty object) |
| `table_of_contents` | `color` |
| `breadcrumb` | (empty object) |

### Media blocks

| Type | Key Properties |
|------|----------------|
| `image` | `type: "external"`, `external.url`, `caption` |
| `video` | `type: "external"`, `external.url`, `caption` |
| `pdf` | `type: "external"`, `external.url`, `caption` |
| `file` | `type: "external"`, `external.url`, `caption`, `name` |
| `bookmark` | `url`, `caption` |
| `embed` | `url`, `caption` |

### Advanced blocks

| Type | Key Properties |
|------|----------------|
| `equation` | `expression` (LaTeX) |
| `synced_block` | `synced_from`, `children` |
| `template` | `rich_text`, `children` |
| `link_to_page` | `type: "page_id"`, `page_id` |
| `child_page` | `title` |
| `child_database` | `title` |

## 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

| Property | Type | Description |
|----------|------|-------------|
| `bold` | boolean | Bold text |

From hugobowne/show-us-your-agent-skills, MIT.

More from hugobowne/show-us-your-agent-skills