notion-formatter

majiayu000's avatarfrom majiayu000

Format markdown content for Notion import with proper syntax for toggles, code blocks, and tables. Use when formatting responses for Notion, creating Notion-compatible documentation, or preparing markdown for Notion paste/import.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026
[Files and Documents]

When & Why to Use This Skill

This Claude skill specializes in optimizing Markdown content for seamless integration into Notion's unique block-based editor. It ensures that headers, lists, toggles, and tables are formatted with the precise syntax required for a perfect paste or import, significantly reducing the need for manual reformatting after moving content into Notion workspaces.

Use Cases

  • Case 1: Converting AI-generated research reports or meeting summaries into Notion-ready pages with collapsible toggle sections for improved navigation.
  • Case 2: Migrating existing technical documentation and README files from GitHub or local environments to Notion while preserving code block syntax and table structures.
  • Case 3: Preparing structured SOPs and team wikis by applying Notion-specific formatting rules and identifying elements that require manual adjustment, such as complex equations.
  • Case 4: Streamlining content workflows by validating Markdown syntax against Notion's import limitations before finalizing documentation.
namenotion-formatter
descriptionFormat markdown content for Notion import with proper syntax for toggles, code blocks, and tables. Use when formatting responses for Notion, creating Notion-compatible documentation, or preparing markdown for Notion paste/import.

Notion Formatter

Quick Start

Notion is a block-based editor, not a pure markdown system. It supports standard markdown for basic formatting (headers, lists, bold, italic, inline code), but many features require Notion-specific syntax or manual creation. This skill helps you format markdown optimally for Notion import by applying the right syntax, annotating manual steps, and warning about limitations.

Core Workflow

1. Identify Your Content Type

  • Claude response: Formatting text I just generated for Notion
  • Documentation: Converting existing .md files to Notion format
  • Mixed content: Markdown with images, code, tables

2. Apply Standard Markdown (What Works Everywhere)

Use standard markdown for these features—they'll convert automatically when pasted into Notion:

**bold** _italic_ `inline code` ~strikethrough~

# Heading 1

## Heading 2

### Heading 3

- Bullet point
- Another point
  - Nested bullet

1. Numbered item
2. Second item

[] Checkbox item

3. Use Notion-Specific Syntax

Key distinction: Use > for toggles (collapsible sections), " for blockquotes. See REFERENCE.md for detailed syntax and examples of all features.

Quick syntax:

> Toggle heading
> Hidden content here

" Blockquote text

code here
Column 1 Column 2
Data 1 Data 2

alt

4. Annotate Manual Steps

Mark features that need manual creation in Notion with annotations:

  • Equations: Use [NOTION: Recreate equation manually]
  • Other unsupported features: Use [NOTION: Feature name here]

5. Verify Output

Before sending to Notion, check:

  • Standard markdown is correct (headers, lists, formatting)
  • Toggle syntax uses > followed by space (greater-than space)
  • Blockquotes use " followed by space (quote space)
  • Code blocks have language labels
  • Images use full URLs, not local paths
  • Tables use pipe syntax
  • Manual step annotations are clear

Examples

Example 1: Formatting a Response

If I generate a response with code and a table, format it with language-labeled code blocks and pipe-syntax tables.

Code block example:

# Example code
def process_data(items):
    return [x * 2 for x in items]

Table example:

Input Output
1 2
5 10

Example 2: Converting Documentation

For multi-section documents, use toggles to create collapsible sections with > Section Title and content indented underneath.

Best Practices

  • Keep it simple: Avoid deeply nested structures
  • Test tables first: If a table is complex, consider creating it manually in Notion
  • Image URLs: Always verify images are accessible online
  • Break large docs: Paste in chunks if a document fails to import entirely
  • Manual polish: Always review in Notion after paste—fix extra line breaks and language detection

For detailed syntax, gotchas, and troubleshooting, see REFERENCE.md