notion-formatter

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

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:

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