Notion to Markdown Converter

Convert Notion pages and databases to clean, readable markdown using the official Notion API.

⚠️ Security & Credentials

Required Credentials:

• NOTION_API_KEY - Your personal Notion integration token (required)

Security Best Practices:

1. Create a dedicated integration - Go to notion.so/my-integrations and create an integration for this tool only
2. Use read-only permissions - Grant the integration "Reader" access, not "Editor"
3. Share selectively - Only share specific pages/databases with the integration, not your entire workspace
4. Protect your token - Never commit .env files containing NOTION_API_KEY to version control
5. Use temporary tokens - Consider creating a rotation policy for tokens or using temporary tokens
6. Code inspection - This tool only uses the official @notionhq/client library and communicates exclusively with Notion's API. No data is sent elsewhere.

Network Access:

• Only connects to: https://api.notion.com (official Notion API)
• No external APIs or data sources
• No telemetry or logging sent elsewhere

Requirements

• Node.js: 14.0.0 or higher
• npm: 6.0.0 or higher
• Notion API Token: Required (get from notion.so/my-integrations)

Check your Node version:

node --version  # Should be v14.0.0 or higher
npm --version

Quick Start

1. Get Your Notion API Key

See Notion API Setup for complete instructions:

• Create an integration at notion.so/my-integrations
• Copy your API token (notioneq_...)
• Share your Notion pages with the integration
• Set environment variable: export NOTION_API_KEY="your_token"

2. Install Dependencies

cd scripts
npm install

3. Convert Pages

Single page:

NOTION_API_KEY=your_token node convert.js <page-id> > output.md

Database export:

NOTION_API_KEY=your_token node convert.js <database-id> --database ./exports

Usage Patterns

Convert Single Notion Page

Extract a page and output to a file:

node scripts/convert.js a1b2c3d4e5f6g7h8 > my-page.md

The converter automatically:

• Fetches the page from Notion
• Converts all blocks to markdown
• Preserves formatting (bold, italic, links, etc.)
• Outputs to stdout or file

Bulk Export Database

Convert all pages in a Notion database:

node scripts/convert.js a1b2c3d4e5f6g7h8 --database ./notion-export

Creates individual markdown files for each page:

notion-export/
├── page-one.md
├── page-two.md
└── page-three.md

Extract Page Metadata

The converter preserves page properties:

const result = await convertPageToMarkdown(pageId);
console.log(result.title);      // Page title from Notion
console.log(result.markdown);   // Converted markdown content
console.log(result.pageId);     // Original page ID

What Gets Converted

Supported Block Types

✅ Text, headings, and paragraphs ✅ Bold, italic, underline, strikethrough, code inline ✅ Links (internal and external) ✅ Lists (ordered and unordered) ✅ Code blocks with syntax highlighting ✅ Tables ✅ Quotes and callouts ✅ Images (as markdown image syntax) ✅ Dividers and separators ✅ Database properties as frontmatter

Formatting Preserved

• Heading hierarchy (H1, H2, H3, etc.)
• List nesting
• Code block languages
• Link URLs and text
• Emphasis and styling

Not Preserved

• Notion databases (converted as tables where possible)
• Some advanced formatting (superscript, subscript)
• Canvas blocks
• Embedded web content (converted to links)

Environment Setup

Setting the API Key

Option 1: Using .env file (Recommended)

Create a .env file in the scripts directory:

# scripts/.env
NOTION_API_KEY=ntn_your_api_key_here

Then run the converter normally:

node convert.js <page-id> > output.md

The script automatically loads environment variables from .env via the dotenv package.

Option 2: Export environment variable

Permanently set in your shell:

# ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish
export NOTION_API_KEY="notioneq_..."

Option 3: Set for a single command

NOTION_API_KEY=your_token node convert.js <page-id>

Security Note: Add .env to .gitignore to prevent accidentally committing your API key:

echo ".env" >> .gitignore

Finding IDs

Page ID from URL

Notion URL format:

https://www.notion.so/Workspace-Name/Page-Title-abc123def456?v=xyz
                                                    ↑ Page ID

Copy the ID part (without hyphens in the URL).

Database ID

Same as page URL - find the ID in the database's URL.

Troubleshooting

"NOTION_API_KEY is not set"

Make sure the environment variable is exported:

export NOTION_API_KEY="notioneq_..."
echo $NOTION_API_KEY  # Verify it's set

"Page not found or not accessible"

• Verify the page ID is correct
• Check that you've shared the page with your Notion integration
• Ensure the integration has access to that workspace

"Invalid page ID format"

• Notion page IDs are 32-character alphanumeric strings
• Remove hyphens from the URL
• Example valid ID: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Markdown output is incomplete

• The API might have rate-limited your request
• Try again after a moment
• For bulk exports, add delays: sleep 0.5 between conversions

Advanced Usage

Custom Output Processing

Modify scripts/convert.js to process markdown before saving:

let markdown = result.markdown;
// Add custom processing
markdown = markdown.replace(/\n{3,}/g, '\n\n');  // Clean up spacing
fs.writeFileSync('output.md', markdown);

Batch Processing

Convert multiple pages in a loop:

for pageId in page1 page2 page3; do
  node convert.js $pageId > "$pageId.md"
done

Integration with Other Tools

The markdown output is plain text and compatible with:

• Static site generators (Hugo, Jekyll, Next.js)
• Documentation platforms (Docusaurus, Doclify)
• Version control (git, GitHub)
• Publishing tools (WordPress, Medium)

API Reference

For advanced usage, see the notion-to-md documentation and Notion API reference.

Security Notes

• Keep your NOTION_API_KEY secret
• Don't commit API keys to version control
• Use .gitignore for .env files
• Rotate tokens if compromised
• Share Notion pages with integration only as needed

See Also

• Notion API Setup Guide - Complete setup instructions
• notion-to-md GitHub - Source library
• Notion API Docs - Official API documentation