Notion Docs

Notion Documentation

Tech Stack Target / Version: Notion API current version, Markdown-to-Notion transforms, and local template scripts.

Use this skill when Notion is the system of record for specs, runbooks, project tracking, or knowledge management.

• Leverage native parallel subagent dispatch and 200k+ context windows where available.

Current MCP Reality

As of March 2026, Notion documents two supported ways to use its MCP server:

• Hosted remote MCP endpoint: https://mcp.notion.com/mcp
• Local stdio server package: @notionhq/notion-mcp-server

Hosted mode uses OAuth. Local mode uses an internal integration token. Official docs also list supported tools for searching content, reading pages, comments, users, and working with pages and databases.

Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

• Creating or updating Notion pages
• Building project trackers or engineering knowledge bases
• Organizing specs, ADRs, and onboarding docs in Notion
• Adding review comments or using database-backed workflows

Practical Workflow

1. Confirm whether the client exposes the hosted Notion MCP server or a local stdio connection. 2. Read or search existing pages before creating duplicates. 3. Use databases for tracked work and pages for long-form documents. 4. Keep properties simple: owner, status, last reviewed, tags. 5. If MCP is unavailable in the current client, fall back to local content prep using the included script and templates.

Operational Notes

• Official Notion guidance currently documents an average rate limit of 20 requests per second for integrations.
• Tool names can vary slightly by MCP host, but the supported capabilities are stable: search, fetch page content, create or update pages, create or update databases, manage comments, and read user context.

Documentation Stack Reference

Inherit the shared stack from documentation-patterns: source-of-truth discovery, audience framing, structure selection, verification, and freshness checks. Keep this skill focused on Notion conversion and workspace behavior instead of restating the full stack.

Anti-Patterns

• Writing for the author instead of the reader: It bakes in unstated context and leaves the actual audience unsure what to do next.
• Skipping concrete examples or commands: Abstract guidance is easy to approve and hard to apply correctly.
• Letting links, screenshots, or versions drift: Polished formatting does not help if the instructions are no longer true.

Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Notion Docs output identifies audience, purpose, source of truth, and freshness requirements. 2. Pass/fail: Shared documentation-stack guidance is referenced instead of duplicating another documentation skill. 3. Pass/fail: Claims, links, commands, examples, and screenshots are verified or explicitly marked unverified. 4. Pressure-test scenario: Apply the skill to a doc request with a stale command, missing owner, and conflicting audience. 5. Success metric: Zero undocumented assumptions; every reader-facing claim is sourced or scoped.

References & Resources

Documentation

• Notion Markdown Spec - Notion-flavored Markdown constraints and conversion notes
• Database Properties - Practical property patterns for docs and project trackers
• Notion MCP Quickstart - Hosted endpoint, local package, auth options, and usage notes

Scripts

• Notion Templates - Local page and database template helpers for environments without Notion MCP access

Examples

• Workspace Setup Example - Example team workspace structure using pages, databases, and review comments

<!-- PORTABILITY:START -->

Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, Codex, and Gemini CLI.

• GitHub Copilot: keep the folder in a Copilot-visible skill or plugin path, or wrap the workflow as project instructions if the host does not support portable skill folders directly.
• Claude Code: keep the folder in a local skills directory or a compatible plugin or marketplace source.
• Codex: install or sync the folder into $CODEX_HOME/skills/<skill-name> and restart Codex after major changes.
• Gemini CLI: this repository generates a project command named /skills:notion-docs from this skill. Rebuild commands with python scripts/export-gemini-skill.py notion-docs and then run /commands reload inside Gemini CLI.

<!-- PORTABILITY:END -->

<!-- MCP:START -->

MCP Availability And Fallback

Preferred MCP Server: Notion MCP

• Fallback prompt: "Use the Notion Documentation skill without MCP. Rely on the local SKILL.md, bundled references or scripts, and manual verification. Show the exact commands, evidence, and final checks you used before concluding."
• Draft content locally in Markdown or JSON, then use scripts/notion-templates.js and the Notion web UI for final publishing.
• Prefer page and database templates from this skill to avoid duplicate structures when working without MCP.

<!-- MCP:END -->

Related Skills

• documentation-authoring: Use it when the workflow also needs drafting structured technical or product documents.
• documentation-patterns: Use it when the workflow also needs reusable documentation structures and templates.
• documentation-quality: Use it when the workflow also needs documentation review standards and quality gates.
• documentation-verification: Use it when the workflow also needs final documentation validation before publishing.

Changelog

[2026-04-25] - Version 1.2 Verification Protocol Refresh

Added

• Added a Verification Protocol section with skill-specific pass/fail checks, one pressure-test scenario, and a measurable success metric.
• Added guidance to leverage native parallel subagent dispatch and 200k+ context windows where available.
• Added or referenced the shared documentation-stack approach to reduce duplicated documentation guidance.

Changed

• Updated SKILL.md frontmatter to version: "1.2" and last_updated: 2026-04-25.
• Reframed activation guidance toward symptom -> action triggers and standardized two-stage review wording where applicable.

[2026-04-24] - Version 1.1 Refresh

Changed

• Updated the SKILL frontmatter version to 1.1 for the 2026-04-24 catalog refresh.

All notable changes to this skill will be documented in this file.

[2026-04-24] - Skill Refresh

Changed

• Standardized the SKILL frontmatter with version metadata, last-updated date, tags, and a concise catalog description.
• Reformatted the portability and MCP guidance with a preferred server line, a copy-paste fallback prompt, and consistent bullet lists.
• Added a catalog-standard Anti-Patterns section and refreshed the Related Skills links at the end of the skill.
• Added a Tech Stack Target / Version note so Notion publishing guidance is tied to the current API and template workflow.

[2026-04-04] - Cross-Client Portability Refresh

Changed

• Added a standard portability note covering GitHub Copilot, Claude Code, Codex, and Gemini CLI.
• Documented the preferred MCP server surface for this skill and a local no-MCP fallback workflow.

Tested

• Validated SKILL.md frontmatter, portability sections, and Gemini export readiness with python scripts/validate-skills.py.

[2026-03-09] - Workspace Modernization

Changed

• Rewrote the skill around the current hosted and local Notion MCP connection options

Added

• references/notion-mcp-quickstart.md with the hosted endpoint, local package, and rate-limit notes

[2026-02-28] — Description Rewrite & Cross-References

Changed

• Rewrote skill description to ~200 characters with clear, specific activation keywords
• Improved keyword specificity to reduce overlap with related skills

Added

• ## Related Skills cross-reference table with 2-4 related skills and "Use When" guidance

Example: Dev Team Notion Workspace Setup

Complete walkthrough for setting up a development team workspace in Notion using MCP tools. Creates a project tracker, documentation wiki, meeting notes database, and decision log.

---

1. Create the Team Hub Page

Start with a top-level page that acts as the workspace root.

// Tool: notion-create-pages
{
  "pages": [
    {
      "properties": { "title": "Engineering Team Hub" },
      "content": "# Engineering Team Hub\n\nCentral workspace for the engineering team.\n\n---\n\n## Quick Links\n\n- **Project Tracker** — All active projects and tasks\n- **Documentation Wiki** — Technical docs and guides\n- **Meeting Notes** — Weekly syncs and retrospectives\n- **Decision Log** — Architecture and process decisions"
    }
  ]
}

Save the returned page_id — it will be the parent for all databases below.

---

2. Create the Project Tracker Database

A full-featured task/issue tracker with status, priority, assignee, sprint, and type.

// Tool: notion-create-database
{
  "parent": { "page_id": "<hub-page-id>" },
  "title": [{ "type": "text", "text": { "content": "Project Tracker" } }],
  "properties": {
    "Task": {
      "type": "title",
      "title": {}
    },
    "Status": {
      "type": "select",
      "select": {
        "options": [
          { "name": "Backlog", "color": "default" },
          { "name": "To Do", "color": "blue" },
          { "name": "In Progress", "color": "yellow" },
          { "name": "In Review", "color": "purple" },
          { "name": "Done", "color": "green" },
          { "name": "Blocked", "color": "red" }
        ]
      }
    },
    "Priority": {
      "type": "select",
      "select": {
        "options": [
          { "name": "Critical", "color": "red" },
          { "name": "High", "color": "orange" },
          { "name": "Medium", "color": "yellow" },
          { "name": "Low", "color": "green" }
        ]
      }
    },
    "Assignee": {
      "type": "people",
      "people": {}
    },
    "Sprint": {
      "type": "select",
      "select": {
        "options": [
          { "name": "Sprint 1", "color": "blue" },
          { "name": "Sprint 2", "color": "purple" },
          { "name": "Sprint 3", "color": "pink" },
          { "name": "Backlog", "color": "default" }
        ]
      }
    },
    "Type": {
      "type": "select",
      "select": {
        "options": [
          { "name": "Feature", "color": "blue" },
          { "name": "Bug", "color": "red" },
          { "name": "Tech Debt", "color": "orange" },
          { "name": "Documentation", "color": "gray" },
          { "name": "Research", "color": "purple" }
        ]
      }
    },
    "Story Points": {
      "type": "number",
      "number": { "format": "number" }
    },
    "Due Date": {
      "type": "date",
      "date": {}
    },
    "Tags": {
      "type": "multi_select",
      "multi_select": {
        "options": [
          { "name": "frontend", "color": "blue" },
          { "name": "backend", "color": "green" },
          { "name": "database", "color": "brown" },
          { "name": "infrastructure", "color": "gray" },
          { "name": "testing", "color": "yellow" }
        ]
      }
    },
    "ID": {
      "type": "unique_id",
      "unique_id": { "prefix": "ENG" }
    }
  }
}

Add Sample Tasks

After creation, use the data_source_id from the response to add pages.

// Tool: notion-create-pages
{
  "parent": { "data_source_id": "<tracker-data-source-id>" },
  "pages": [
    {
      "properties": {
        "Task": "Set up CI/CD pipeline",
        "Status": "To Do",
        "Priority": "High",
        "Sprint": "Sprint 1",
        "Type": "Feature",
        "Story Points": 5,
        "Tags": "infrastructure",
        "date:Due Date:start": "2025-02-20",
        "date:Due Date:is_datetime": 0
      },
      "content": "## Description\n\nConfigure GitHub Actions for automated testing and deployment.\n\n## Acceptance Criteria\n\n- [ ] Tests run on every PR\n- [ ] Auto-deploy to staging on merge to develop\n- [ ] Auto-deploy to production on merge to main"
    },
    {
      "properties": {
        "Task": "Implement user authentication",
        "Status": "In Progress",
        "Priority": "Critical",
        "Sprint": "Sprint 1",
        "Type": "Feature",
        "Story Points": 8,
        "Tags": "backend, frontend",
        "date:Due Date:start": "2025-02-18",
        "date:Due Date:is_datetime": 0
      },
      "content": "## Description\n\nJWT-based login and registration flow.\n\n## Tasks\n\n- [x] Design auth API endpoints\n- [x] Implement backend routes\n- [ ] Build login/signup UI\n- [ ] Add token refresh logic\n- [ ] Write integration tests"
    },
    {
      "properties": {
        "Task": "Fix mobile navigation overflow",
        "Status": "To Do",
        "Priority": "Medium",
        "Sprint": "Sprint 1",
        "Type": "Bug",
        "Story Points": 2,
        "Tags": "frontend"
      },
      "content": "## Bug Report\n\nNavigation menu overflows on screens narrower than 375px.\n\n## Steps to Reproduce\n\n1. Open app on iPhone SE\n2. Tap hamburger menu\n3. Observe horizontal scroll\n\n## Expected\n\nMenu fits within viewport width."
    }
  ]
}

---

3. Create the Documentation Wiki

A page-based wiki for technical documentation.

// Tool: notion-create-pages
{
  "parent": { "page_id": "<hub-page-id>" },
  "pages": [
    {
      "properties": { "title": "Documentation Wiki" },
      "content": "# Documentation Wiki\n\n> ℹ️ Central technical documentation for the engineering team.\n\n---\n\n## Sections\n\n- **Architecture** — System design and component diagrams\n- **API Reference** — REST endpoint documentation\n- **Getting Started** — Onboarding and local setup\n- **Deployment** — CI/CD and release procedures\n- **Coding Standards** — Style guides and conventions"
    }
  ]
}

Add Wiki Sub-Pages

Use the wiki page ID as the parent.

// Tool: notion-create-pages
{
  "parent": { "page_id": "<wiki-page-id>" },
  "pages": [
    {
      "properties": { "title": "Architecture Overview" },
      "content": "# Architecture Overview\n\n## System Diagram\n\n| Layer | Technology | Description |\n|-------|-----------|-------------|\n| Frontend | React 19 + Vite | SPA with Tailwind CSS |\n| API | Next.js 15 | App Router REST endpoints |\n| Database | MongoDB Atlas | Document store |\n| Auth | JWT + bcrypt | Token-based authentication |\n| Hosting | Azure | Static Web Apps + App Service |\n\n---\n\n## Data Flow\n\n1. Client sends HTTP request\n2. Next.js API route handles request\n3. Mongoose model queries MongoDB\n4. Response returns through the chain\n\n---\n\n## Key Design Decisions\n\n▶ Why MongoDB over PostgreSQL?\n\tFlexible schema suits our rapidly evolving data model.\n\tNested document structure maps naturally to our domain.\n\n▶ Why Next.js for API?\n\tUnified deployment, built-in API routes, and server components for future SSR."
    },
    {
      "properties": { "title": "Getting Started" },
      "content": "# Getting Started\n\n## Prerequisites\n\n- Node.js 18+\n- pnpm (recommended) or npm\n- Git\n- MongoDB Atlas account (or local MongoDB)\n\n## Setup\n\n```bash\ngit clone https://github.com/team/project.git\ncd project\npnpm install\ncp .env.example .env.local\npnpm dev\n```\n\n## Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `MONGODB_URI` | Atlas connection string | `mongodb+srv://...` |\n| `JWT_SECRET` | Token signing key | `your-secret-key` |\n| `NEXT_PUBLIC_API_URL` | API base URL | `http://localhost:3000` |\n\n---\n\n## Verification\n\nAfter starting the dev server:\n\n- [ ] App loads at http://localhost:5173\n- [ ] API responds at http://localhost:3000/api\n- [ ] Database connection succeeds (check terminal logs)"
    },
    {
      "properties": { "title": "Coding Standards" },
      "content": "# Coding Standards\n\n## Language & Framework\n\n- **JavaScript/TypeScript** with ES2022+ features\n- **React 19** functional components only\n- **Tailwind CSS** for styling (no CSS modules)\n\n## Naming Conventions\n\n| Item | Convention | Example |\n|------|-----------|----------|\n| Components | PascalCase | `UserProfile.jsx` |\n| Hooks | camelCase, `use` prefix | `useAuth.js` |\n| Utilities | camelCase | `formatDate.js` |\n| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES` |\n| API routes | kebab-case | `/api/user-profile` |\n\n## Git Workflow\n\n- Branch from `develop`\n- PRs require 1 approval\n- Squash merge to `develop`\n- Conventional commits required"
    }
  ]
}

---

4. Create the Meeting Notes Database

A database to store recurring meeting notes with date, type, and attendees.

// Tool: notion-create-database
{
  "parent": { "page_id": "<hub-page-id>" },
  "title": [{ "type": "text", "text": { "content": "Meeting Notes" } }],
  "properties": {
    "Meeting": {
      "type": "title",
      "title": {}
    },
    "Date": {
      "type": "date",
      "date": {}
    },
    "Type": {
      "type": "select",
      "select": {
        "options": [
          { "name": "Weekly Sync", "color": "blue" },
          { "name": "Sprint Planning", "color": "purple" },
          { "name": "Sprint Review", "color": "green" },
          { "name": "Retrospective", "color": "orange" },
          { "name": "Ad Hoc", "color": "default" },
          { "name": "1-on-1", "color": "pink" }
        ]
      }
    },
    "Attendees": {
      "type": "people",
      "people": {}
    },
    "Action Items": {
      "type": "number",
      "number": { "format": "number" }
    }
  }
}

Add a Sample Meeting Entry

// Tool: notion-create-pages
{
  "parent": { "data_source_id": "<meetings-data-source-id>" },
  "pages": [
    {
      "properties": {
        "Meeting": "Sprint 1 Planning",
        "date:Date:start": "2025-02-10",
        "date:Date:is_datetime": 0,
        "Type": "Sprint Planning",
        "Action Items": 4
      },
      "content": "## Agenda\n\n1. Review backlog priorities\n2. Assign sprint tasks\n3. Estimate story points\n4. Identify risks and blockers\n\n---\n\n## Discussion\n\n> 📝 Key decisions from planning session\n\n- Agreed to prioritize authentication and CI/CD\n- Deferred analytics dashboard to Sprint 2\n- Mobile bug fix fits within sprint capacity\n\n---\n\n## Action Items\n\n- [ ] Create sprint board view — **Owner:** PM\n- [ ] Set up staging environment — **Owner:** DevOps\n- [ ] Draft auth API spec — **Owner:** Backend Lead\n- [ ] Share design mockups — **Owner:** Designer"
    }
  ]
}

---

5. Create the Decision Log Database

Track architectural and process decisions with context.

// Tool: notion-create-database
{
  "parent": { "page_id": "<hub-page-id>" },
  "title": [{ "type": "text", "text": { "content": "Decision Log" } }],
  "properties": {
    "Decision": {
      "type": "title",
      "title": {}
    },
    "Status": {
      "type": "select",
      "select": {
        "options": [
          { "name": "Proposed", "color": "yellow" },
          { "name": "Accepted", "color": "green" },
          { "name": "Superseded", "color": "gray" },
          { "name": "Rejected", "color": "red" }
        ]
      }
    },
    "Category": {
      "type": "select",
      "select": {
        "options": [
          { "name": "Architecture", "color": "blue" },
          { "name": "Technology", "color": "purple" },
          { "name": "Process", "color": "orange" },
          { "name": "Security", "color": "red" },
          { "name": "Infrastructure", "color": "gray" }
        ]
      }
    },
    "Date Decided": {
      "type": "date",
      "date": {}
    },
    "Decided By": {
      "type": "people",
      "people": {}
    },
    "ID": {
      "type": "unique_id",
      "unique_id": { "prefix": "ADR" }
    }
  }
}

Add Sample Decisions

// Tool: notion-create-pages
{
  "parent": { "data_source_id": "<decisions-data-source-id>" },
  "pages": [
    {
      "properties": {
        "Decision": "Use MongoDB Atlas for primary datastore",
        "Status": "Accepted",
        "Category": "Technology",
        "date:Date Decided:start": "2025-01-15",
        "date:Date Decided:is_datetime": 0
      },
      "content": "## Context\n\nWe need a database for our full-stack application. The data model is evolving rapidly with nested structures.\n\n## Options Considered\n\n| Option | Pros | Cons |\n|--------|------|------|\n| MongoDB Atlas | Flexible schema, native JSON, managed service | No joins, eventual consistency |\n| PostgreSQL | ACID, mature, relational | Rigid schema during rapid iteration |\n| DynamoDB | Serverless, auto-scaling | Vendor lock-in, complex query patterns |\n\n## Decision\n\nAdopt MongoDB Atlas as the primary datastore.\n\n## Rationale\n\n- Schema flexibility matches our evolving data model\n- Mongoose ODM provides good validation layer\n- Atlas free tier sufficient for development\n- Team has prior MongoDB experience\n\n## Consequences\n\n- Must design aggregation pipelines for complex queries\n- Need to handle schema migrations manually\n- Will use Mongoose for schema validation at the application layer"
    },
    {
      "properties": {
        "Decision": "Adopt conventional commits for all repositories",
        "Status": "Accepted",
        "Category": "Process",
        "date:Date Decided:start": "2025-01-20",
        "date:Date Decided:is_datetime": 0
      },
      "content": "## Context\n\nCommit messages are inconsistent across the team, making changelogs and release notes difficult to generate.\n\n## Decision\n\nAll repositories must use [Conventional Commits](https://www.conventionalcommits.org/) specification.\n\n## Format\n\n```\ntype(scope): description\n\n[optional body]\n[optional footer]\n```\n\n## Types\n\n- `feat` — new feature\n- `fix` — bug fix\n- `docs` — documentation changes\n- `refactor` — code restructuring\n- `test` — adding/updating tests\n- `chore` — maintenance tasks\n\n## Enforcement\n\n- commitlint checks in CI\n- Husky pre-commit hooks locally\n- PR titles must follow the convention"
    }
  ]
}

---

Complete Setup Summary

After executing all the above MCP calls, the workspace structure looks like:

Engineering Team Hub
├── Project Tracker (database)
│   ├── ENG-1: Set up CI/CD pipeline
│   ├── ENG-2: Implement user authentication
│   └── ENG-3: Fix mobile navigation overflow
├── Documentation Wiki (page)
│   ├── Architecture Overview
│   ├── Getting Started
│   └── Coding Standards
├── Meeting Notes (database)
│   └── Sprint 1 Planning
└── Decision Log (database)
    ├── ADR-1: Use MongoDB Atlas for primary datastore
    └── ADR-2: Adopt conventional commits for all repositories

Tool Call Sequence

Total: 3 database creations + 6 page creation calls = 9 MCP tool invocations.

Tips

• Fetch after creating databases to get the data_source_id (from <data-source url="collection://..."> tags) needed for adding pages.
• Use `notion-search` to find existing pages/databases before creating duplicates.
• Batch page creation — the create-pages tool accepts up to 100 pages per call.
• Properties named `id` or `url` must use the userDefined: prefix (e.g., "userDefined:URL").
• Date properties use expanded format: "date:Due Date:start", "date:Due Date:end", "date:Due Date:is_datetime".
• Checkbox values use "__YES__" and "__NO__" strings, not booleans.

Notion Database Property Types

Complete reference for all Notion database property types, their configuration, use cases, and API format when working with Notion MCP tools.

---

Title

The primary identifier for every database page. Every database has exactly one title property.

• Description: Rich text field that serves as the page name. Always required.
• Configuration: Cannot be deleted. Can be renamed.
• Use Cases: Page names, task titles, item labels, document names.
• API Format:

  { "Task Name": "Implement login flow" }

• Schema Definition:

  { "Task Name": { "type": "title", "title": {} } }

---

Rich Text

Multi-line text field supporting inline formatting.

• Description: Free-form text with bold, italic, links, mentions, and other inline styles.
• Configuration: No additional config needed.
• Use Cases: Descriptions, notes, comments, summaries.
• API Format:

  { "Description": "A detailed description with **bold** text" }

• Schema Definition:

  { "Description": { "type": "rich_text", "rich_text": {} } }

---

Number

Numeric values with optional formatting.

• Description: Stores integers or decimals. Supports format options for display.
• Configuration: Optional format — "number", "number_with_commas", "percent", "dollar", "euro", "pound", "yen", "ruble", "rupee", "won", "yuan", etc.
• Use Cases: Priority scores, story points, prices, percentages, quantities.
• API Format:

  { "Priority": 5 }
  { "Price": 29.99 }

Must be a JavaScript number, not a string.

• Schema Definition:

  { "Story Points": { "type": "number", "number": { "format": "number" } } }

---

Select

Single-choice dropdown with predefined options.

• Description: Allows selecting exactly one value from a list of options. Each option has a name and optional color.
• Configuration: Define options with name and optional color.
• Use Cases: Status, priority level, category, type, environment.
• API Format:

  { "Status": "In Progress" }

• Schema Definition:

  {
    "Priority": {
      "type": "select",
      "select": {
        "options": [
          { "name": "Critical", "color": "red" },
          { "name": "High", "color": "orange" },
          { "name": "Medium", "color": "yellow" },
          { "name": "Low", "color": "green" }
        ]
      }
    }
  }

• Available Colors: default, gray, brown, orange, yellow, green, blue, purple, pink, red.

---

Multi-Select

Multiple-choice tags from predefined options.

• Description: Allows selecting one or more values from a list. Renders as colored tags.
• Configuration: Same option structure as Select.
• Use Cases: Tags, labels, skills, categories, components affected.
• API Format:

  { "Tags": "frontend, bug, urgent" }

Comma-separated string of option names.

• Schema Definition:

  {
    "Tags": {
      "type": "multi_select",
      "multi_select": {
        "options": [
          { "name": "frontend", "color": "blue" },
          { "name": "backend", "color": "green" },
          { "name": "bug", "color": "red" },
          { "name": "feature", "color": "purple" }
        ]
      }
    }
  }

---

Date

Date or date-range values with optional time component.

• Description: Stores a start date and optional end date. Can include time and timezone.
• Configuration: No additional config. Supports date-only or datetime.
• Use Cases: Due dates, sprint dates, event dates, deadlines, date ranges.
• API Format (expanded):

  {
    "date:Due Date:start": "2024-12-25",
    "date:Due Date:end": "2025-01-15",
    "date:Due Date:is_datetime": 0
  }

• start — ISO 8601 date string (required).
• end — ISO 8601 date string (optional, for ranges).
• is_datetime — 0 for date-only, 1 for datetime.
• Schema Definition:

  { "Due Date": { "type": "date", "date": {} } }

---

People

References to Notion workspace users.

• Description: Links one or more workspace members to a page.
• Configuration: No additional config.
• Use Cases: Assignee, reviewer, owner, participants.
• API Format:

  { "Assignee": "user-uuid-here" }

• Schema Definition:

  { "Assignee": { "type": "people", "people": {} } }

---

Files & Media

File attachments and media uploads.

• Description: Stores file references (uploaded or external URLs).
• Configuration: No additional config.
• Use Cases: Attachments, screenshots, design files, documents.
• API Format: Typically managed via Notion UI or API file objects.
• Schema Definition:

  { "Attachments": { "type": "files", "files": {} } }

---

Checkbox

Boolean true/false toggle.

• Description: Simple checked/unchecked state.
• Configuration: No additional config.
• Use Cases: Completion flags, feature toggles, approval status.
• API Format:

  { "Is Complete": "__YES__" }
  { "Is Complete": "__NO__" }

Use "__YES__" for checked, "__NO__" for unchecked.

• Schema Definition:

  { "Is Complete": { "type": "checkbox", "checkbox": {} } }

---

URL

Stores a single URL.

• Description: Validated URL field displayed as a clickable link.
• Configuration: No additional config.
• Use Cases: Repository links, documentation links, external references.
• API Format:

  { "userDefined:URL": "https://github.com/org/repo" }

Properties named url (case-insensitive) must use the userDefined: prefix.

• Schema Definition:

  { "Repository": { "type": "url", "url": {} } }

---

Email

Stores an email address.

• Description: Validated email field.
• Configuration: No additional config.
• Use Cases: Contact email, support email, notification address.
• API Format:

  { "Contact Email": "team@example.com" }

• Schema Definition:

  { "Contact Email": { "type": "email", "email": {} } }

---

Phone Number

Stores a phone number string.

• Description: Phone number field (no strict validation format).
• Configuration: No additional config.
• Use Cases: Contact numbers, support lines.
• API Format:

  { "Phone": "+1-555-0123" }

• Schema Definition:

  { "Phone": { "type": "phone_number", "phone_number": {} } }

---

Formula

Computed value derived from other properties.

• Description: Evaluates an expression using other property values. Read-only.
• Configuration: Requires an expression string using Notion's formula syntax.
• Use Cases: Calculated fields, conditional labels, derived metrics, concatenations.
• API Format: Read-only — cannot be set directly.
• Schema Definition:

  {
    "Days Until Due": {
      "type": "formula",
      "formula": {
        "expression": "dateBetween(prop(\"Due Date\"), now(), \"days\")"
      }
    }
  }

---

Relation

Links pages between two databases.

• Description: Creates a relationship between pages in different (or the same) databases.
• Configuration: Requires data_source_id of the target database's data source. Supports single_property (one-way) or dual_property (two-way).
• Use Cases: Task → Project linking, Epic → Story, Document → Author.
• API Format: Pass related page IDs.
• Schema Definition (one-way):

  {
    "Project": {
      "type": "relation",
      "relation": {
        "data_source_id": "target-data-source-uuid",
        "type": "single_property",
        "single_property": {}
      }
    }
  }

• Schema Definition (two-way):

  {
    "Tasks": {
      "type": "relation",
      "relation": {
        "data_source_id": "target-data-source-uuid",
        "type": "dual_property",
        "dual_property": {
          "synced_property_name": "Related Project"
        }
      }
    }
  }

---

Rollup

Aggregates values from a related database via a relation property.

• Description: Computes aggregated values (count, sum, average, etc.) from pages linked through a relation.
• Configuration: Requires a relation property name/ID and a target property to roll up, plus an aggregation function.
• Use Cases: Total story points in a sprint, count of tasks per project, percent complete.
• API Format: Read-only — cannot be set directly.
• Schema Definition:

  {
    "Total Points": {
      "type": "rollup",
      "rollup": {
        "relation_property_name": "Tasks",
        "rollup_property_name": "Story Points",
        "function": "sum"
      }
    }
  }

• Available Functions: count, count_values, empty, not_empty, unique, show_unique, percent_empty, percent_not_empty, sum, average, median, min, max, range, earliest_date, latest_date, date_range, checked, unchecked, percent_checked, percent_unchecked, show_original.

---

Created Time

Auto-populated timestamp of when the page was created.

• Description: Read-only timestamp. Automatically set on page creation.
• Configuration: No additional config.
• Use Cases: Audit trail, sorting by creation date, filtering recent items.
• API Format: Read-only.
• Schema Definition:

  { "Created": { "type": "created_time", "created_time": {} } }

---

Created By

Auto-populated reference to the user who created the page.

• Description: Read-only user reference. Automatically set on creation.
• Configuration: No additional config.
• Use Cases: Audit trail, filtering by creator.
• API Format: Read-only.
• Schema Definition:

  { "Created By": { "type": "created_by", "created_by": {} } }

---

Last Edited Time

Auto-populated timestamp of the most recent edit.

• Description: Read-only timestamp. Updates automatically on any page modification.
• Configuration: No additional config.
• Use Cases: Sorting by recent activity, staleness detection.
• API Format: Read-only.
• Schema Definition:

  { "Updated": { "type": "last_edited_time", "last_edited_time": {} } }

---

Last Edited By

Auto-populated reference to the last user who edited the page.

• Description: Read-only user reference. Updates on any edit.
• Configuration: No additional config.
• Use Cases: Audit trail, recent editor tracking.
• API Format: Read-only.
• Schema Definition:

  { "Last Editor": { "type": "last_edited_by", "last_edited_by": {} } }

---

Status

Built-in status property with grouped options (To-do, In progress, Complete).

• Description: Special select-like property with three status groups. Options are categorized into groups automatically.
• Configuration: No additional config at creation. Configure status options and groups in Notion UI.
• Use Cases: Task/issue status, workflow stage, approval state.
• API Format:

  { "Status": "In Progress" }

• Schema Definition:

  { "Status": { "type": "status", "status": {} } }

---

Unique ID

Auto-incremented identifier with optional prefix.

• Description: Auto-generated sequential ID. Read-only. Supports a string prefix.
• Configuration: Optional prefix string (e.g., "TASK" produces TASK-1, TASK-2, etc.).
• Use Cases: Issue numbers, ticket IDs, sequential identifiers.
• API Format: Read-only.
• Schema Definition:

  {
    "ID": {
      "type": "unique_id",
      "unique_id": { "prefix": "TASK" }
    }
  }

• Notes: Maximum one unique_id property per database.

---

Quick Reference Table

Notion-Flavored Markdown Specification

Reference for the enhanced Markdown format used by Notion MCP tools (create-pages, update-page, fetch). Notion Markdown extends standard Markdown with additional block types, inline formatting, and structural elements.

---

Block Elements

Headings

Notion supports three heading levels. Headings can include color attributes.

# Heading 1
## Heading 2
### Heading 3

# Colored Heading {color="blue"}
## Another Heading {color="red"}

Heading 4–6 (####, #####, ######) are not supported — they render as bold text or are ignored.

Paragraphs

Plain text separated by blank lines. Inline formatting applies within paragraphs.

This is a paragraph with **bold** and *italic* text.

This is another paragraph.

Bullet Lists

Standard unordered lists using -, *, or +. Nesting via indentation (tab or 2–4 spaces).

- Item one
- Item two
  - Nested item
  - Another nested item
    - Deeply nested
- Item three

Numbered Lists

Ordered lists using 1., 2., etc. Nesting supported.

1. First step
2. Second step
   1. Sub-step A
   2. Sub-step B
3. Third step

To-Do Lists

Checkbox items using - [ ] (unchecked) and - [x] (checked).

- [ ] Unchecked task
- [x] Completed task
- [ ] Another pending task

Code Blocks

Fenced code blocks with optional language identifier.

````markdown

const greeting = "Hello, Notion!";
console.log(greeting);

def greet(name):
    return f"Hello, {name}!"

Plain code block (no language)

````

Callouts

Callout blocks use the > prefix followed by an emoji icon. Content follows on subsequent indented lines.

> 💡 This is a tip callout
> Additional content inside the callout

> ⚠️ Warning callout
> Be careful with this operation

> ℹ️ Info callout with **bold** text inside

Common callout icons: 💡 (tip), ⚠️ (warning), ℹ️ (info), 🔥 (important), 📝 (note), ✅ (success), ❌ (error).

Toggle Blocks

Collapsible content using the ▶ character followed by the summary, with indented body content.

▶ Click to expand
	Hidden content inside the toggle
	More hidden content

▶ Another toggle
	- Nested list inside toggle
	- Second item

The toggle body must be indented with a tab character.

Tables

Standard Markdown table syntax. Header row required.

| Column A | Column B | Column C |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Alignment syntax is supported:

| Left     | Center   | Right    |
|:---------|:--------:|---------:|
| aligned  | aligned  | aligned  |

Dividers

Horizontal rules using ---, ***, or ___.

---

Block Quotes

Standard blockquote syntax. Without an emoji prefix, renders as a Notion quote block (not a callout).

> This is a block quote.
> It can span multiple lines.

Bookmarks

Link bookmarks display as rich link previews.

[bookmark](https://example.com)

Or as a standalone URL on its own line, which Notion may auto-convert to a bookmark.

Embeds

Embedded content from supported services (YouTube, Figma, Google Maps, etc.).

[embed](https://www.youtube.com/watch?v=dQw4w9WgXcQ)
[embed](https://www.figma.com/file/abc123)

Images

Standard Markdown image syntax.

![Alt text](https://example.com/image.png)

---

Inline Formatting

Bold

**bold text**
__also bold__

Italic

*italic text*
_also italic_

Strikethrough

~~strikethrough text~~

Inline Code

`inline code`

Links

[Link text](https://example.com)
[Link with title](https://example.com "Title")

Mentions

Reference Notion pages, databases, users, or dates inline.

@[Page Title](page-id-here)

User mentions and date mentions are typically inserted via API properties, not raw Markdown.

Colors and Backgrounds

Apply inline colors using annotation syntax:

**bold red text**{color="red"}
*italic blue*{color="blue"}
Text with background{bg="yellow"}

Available colors: default, gray, brown, orange, yellow, green, blue, purple, pink, red. Background colors use the same names with _background suffix or bg attribute.

---

Page and Database Reference Tags

Notion Markdown uses special HTML-like tags to reference child pages and databases.

Page References

<page url="https://notion.so/workspace/Page-Title-abc123">Page Title</page>

When updating page content, preserving <page> tags prevents accidental deletion of child pages.

Database References

<database url="https://notion.so/workspace/DB-Title-abc123">Database Title</database>

Data Source Tags

Returned by the fetch tool to identify collections within databases:

<data-source url="collection://f336d0bc-b841-465b-8045-024475c079dd">Source Name</data-source>

Use the UUID from collection:// URLs as data_source_id in MCP tool calls.

---

Database-Specific Markdown

When creating pages inside a database, properties are passed as a JSON map — not as Markdown content. The Markdown content field is for the page body only.

Property Value Formats

Properties named id or url (case-insensitive) must be prefixed with userDefined:.

---

Limitations vs Standard Markdown

---

Common Formatting Patterns

Section with Callout and Toggle

# Project Overview

> 📝 This document outlines the project scope and timeline.

## Architecture

▶ System Components
	- Frontend: React + Vite
	- Backend: Next.js API Routes
	- Database: MongoDB Atlas

---

## Tasks

- [x] Set up repository
- [x] Configure CI/CD
- [ ] Implement authentication
- [ ] Deploy to staging

Table with Inline Formatting

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/api/users` | **GET** | List all users |
| `/api/users/:id` | **GET** | Get user by ID |
| `/api/users` | **POST** | Create user |
| `/api/users/:id` | **DELETE** | *Admin only* — Delete user |

Rich Page with Multiple Block Types

# Sprint 12 Retrospective

**Date:** 2025-01-20
**Facilitator:** Alex

---

## What Went Well

> ✅ Highlights from this sprint

1. Shipped the new dashboard
2. Reduced API response time by 40%
3. Zero critical bugs in production

## What Could Improve

- [ ] Better test coverage for edge cases
- [ ] Earlier design reviews
- [ ] More async communication

## Action Items

| Action | Owner | Due |
|--------|-------|-----|
| Add integration tests | Sarah | Jan 27 |
| Schedule design syncs | Mike | Jan 22 |

▶ Discussion Notes
	Detailed notes from the retrospective discussion go here.
	These are collapsed by default.

Notion MCP Quickstart

This reference captures the current public setup patterns documented by Notion as of March 2026.

Connection Options

Hosted Remote Server

• Endpoint: https://mcp.notion.com/mcp
• Auth: OAuth
• Best for clients that support remote MCP servers directly

Local Stdio Server

• Package: @notionhq/notion-mcp-server
• Auth: Notion integration token
• Best for local tooling and clients that only support stdio MCP servers

Supported Capability Areas

Notion's public MCP docs describe support for:

• Search and retrieval
• Pages
• Databases
• Comments
• Users
• Agent actions and templates

The exact exposed tool names depend on the MCP host, so inspect the connected server in your client before assuming names.

Operational Guidance

• Prefer search before page creation to avoid duplicates.
• Use databases for structured work tracking.
• Use standalone pages for long-form documents and specs.
• Keep database schemas small and stable.

Rate Limits

Notion currently documents an average limit of 20 requests per second for integrations.

Fallback Pattern

If Notion MCP is unavailable:

1. Draft the document locally. 2. Use scripts/notion-templates.js to standardize structure. 3. Paste or import into Notion manually when access is restored.