Notion Mastery

Notion Mastery

Create, design, and automate in Notion using MCP tools and the REST API. Build professional-looking pages with proper visual design patterns.

Page Design Principles

For complete design patterns and page templates, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/page-design-patterns.md.

Making Pages Look Professional

Notion pages look best when they follow these principles:

• Lead with a callout — Use a callout block at the top with an emoji icon and brief description. Sets the tone and provides immediate context.
• Use toggle headings — ## Heading {toggle="true"} keeps pages scannable. Users expand sections they care about.
• Columns for side-by-side content — Two or three columns using <columns> for dashboards, comparison views, or separating related content.
• Non-obtrusive TOC — Place <table_of_contents/> inside a toggle or callout, not at the very top. Or place it in a column beside content.
• Callouts for emphasis — Color-coded callouts for tips, warnings, notes, prerequisites. Use sparingly.
• Dividers between sections — --- creates visual breathing room between major sections.
• Alternating block types — Mix headings, text, callouts, tables, and images. Avoid walls of text.
• Consistent color scheme — Pick 2-3 colors and use them throughout. Blue for info, yellow for warnings, green for success.

Layout Patterns

Hero pattern — Callout with icon + brief intro, then divider, then content:

::: callout {icon="🚀" color="blue_bg"}
**Project Dashboard** — Track progress, milestones, and blockers at a glance.
:::
---

Two-column dashboard — Key metrics on left, action items on right:

<columns>
  <column>
    ## 📊 Metrics {toggle="true"}
      Content...
  </column>
  <column>
    ## ✅ Actions {toggle="true"}
      Content...
  </column>
</columns>

Toggle sections — Clean, expandable page:

## 📋 Overview {toggle="true"}
  Content here...
## 🎯 Goals {toggle="true"}
  Content here...
## 📝 Notes {toggle="true"}
  Content here...

Notion-Flavored Markdown

For the complete block catalog and syntax, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/notion-markdown-spec.md and ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/block-catalog.md.

Notion uses a custom Markdown dialect for page content. Key syntax:

Block Colors

Any block accepts {color="Color"} at the end of its first line:

• Text colors: gray, brown, orange, yellow, green, blue, purple, pink, red
• Background colors: gray_bg, brown_bg, orange_bg, yellow_bg, green_bg, blue_bg, purple_bg, pink_bg, red_bg

Key Block Types

• Callout: ::: callout {icon="💡" color="yellow_bg"}\nContent\n:::
• Columns: <columns><column>Left</column><column>Right</column></columns>
• Toggle: <details><summary>Label</summary>\n\tContent\n</details>
• Toggle heading: ## Heading {toggle="true"}
• Table: <table header-row="true"><tr><td>A</td><td>B</td></tr></table>
• Table of contents: <table_of_contents/>
• Synced block: <synced_block>\n\tContent\n</synced_block>
• Code block: ```language\nCode\n```
• Equation: $$\nLaTeX\n$$
• Image: ![Caption](URL)
• Divider: ---
• Meeting notes: <meeting-notes>\n\tTitle\n\t<notes>\n\t\tContent\n\t</notes>\n</meeting-notes>

Rich Text Formatting

• Bold: **text**, Italic: *text*, Strikethrough: ~~text~~
• Underline: <span underline="true">text</span>
• Color: <span color="blue">text</span> or <span color="red_bg">text</span>
• Inline code: `code`, Inline math: $equation$
• Link: [text](url), Mention: <mention-page url="...">Title</mention-page>

Databases

For complete database reference, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/database-mastery.md.

Core Concepts

• Properties — Columns defining data schema: Title, Text, Number, Select, Multi-select, Date, Person, Files, Checkbox, URL, Email, Phone, Formula, Relation, Rollup, Created time, Last edited time, Created by, Last edited by, Status, AI autofill
• Views — Different ways to visualize the same data: Table, Board, Calendar, Timeline, Gallery, List
• Filters — Narrow visible rows by property conditions
• Sorts — Order rows by property values
• Templates — Pre-built page content for new database entries
• Relations — Link entries across databases (one-to-many, many-to-many)
• Rollups — Aggregate related data (count, sum, average, date range, etc.)
• Linked databases — Show a filtered view of another database on any page

Database via MCP

Use notion-create-database to create databases. Use notion-fetch to read schema. Use notion-update-data-source to modify schema.

Notion Formulas

For the complete formula reference, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/formula-language.md.

Notion formulas use a functional syntax (not VB.NET, not Excel):

// Days until deadline
dateBetween(prop("Due Date"), now(), "days")

// Status emoji
if(prop("Status") == "Done", "✅",
  if(prop("Status") == "In Progress", "🔄", "⏳"))

// Progress percentage
round(prop("Completed Tasks") / prop("Total Tasks") * 100)

Key Formula Functions

• Logic: if(), and(), or(), not(), empty()
• Math: add(), subtract(), multiply(), divide(), mod(), pow(), round(), ceil(), floor(), abs(), min(), max()
• Text: concat(), join(), slice(), length(), contains(), replace(), replaceAll(), test(), upper(), lower(), repeat(), padStart(), padEnd(), trim()
• Date: now(), today(), dateAdd(), dateSubtract(), dateBetween(), formatDate(), minute(), hour(), day(), date(), month(), year()
• Lists: at(), first(), last(), slice(), concat(), sort(), reverse(), map(), filter(), every(), some(), find(), findIndex(), flat(), length(), includes()

AI Features

For complete AI feature reference, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/ai-features.md.

• AI Autofill property — Database property that uses AI to fill values based on page content
• AI blocks — Inline AI-generated content within pages
• Meeting notes — <meeting-notes> blocks with AI summaries and transcripts
• AI search — Semantic search across workspace and connected sources via MCP search tool

MCP Tools

For detailed MCP usage patterns, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/mcp-tools-guide.md.

Available Notion MCP tools:

• notion-search — Search pages, databases, users across workspace
• notion-fetch — Read full page content, database schema, data source details
• notion-create-pages — Create one or more pages with content and properties
• notion-update-page — Update properties, replace/insert content, apply templates, verify pages
• notion-move-pages — Move pages or databases to new parents
• notion-duplicate-page — Duplicate existing pages
• notion-create-database — Create new databases with schema
• notion-update-data-source — Modify database schema and properties
• notion-create-comment — Add comments to pages or specific blocks
• notion-get-comments — Read comments and discussions
• notion-get-teams — List teamspaces
• notion-get-users — List workspace members

MCP Workflow Pattern

1. Search to find existing content: notion-search
2. Fetch to read full details: notion-fetch
3. Create or update to make changes: notion-create-pages or notion-update-page
4. Verify the result by fetching again

REST API

For API endpoints and patterns, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/api-reference.md.

The Notion API (api.notion.com) is useful when MCP tools don't cover a scenario:

• Bulk operations — Creating hundreds of pages in batches
• Webhooks — Listening for changes
• Programmatic database queries — Complex filtering with the API's filter object
• Block-level manipulation — Appending, moving, and deleting individual blocks
• User management — Bot user info, workspace member details

Authentication: Bearer token (integration token or OAuth). Base URL: https://api.notion.com/v1/.

Troubleshooting

For common errors and diagnostic steps, read ${CLAUDE_PLUGIN_ROOT}/skills/notion-mastery/references/troubleshooting.md.

Covers MCP tool errors (page not found, rate limits, invalid content), page design issues (toggle content not nesting, callouts not rendering), database problems (formula errors, relation issues), API-specific issues, and performance diagnostics.

Reference Files

Example Files