什么是 Notion 转 Markdown 转换器？

Notion 转 Markdown 转换器是一款以开发者为中心的工具，旨在桥接 Notion 的结构化块编辑器与基于 Markdown 的工作流。通过利用官方的 @notionhq/client，该技能允许用户在保持格式、层级和元数据的同时，提取页面和整个数据库。它是 Openclaw Skills 生态系统中任何开发者工具包的重要补充，特别适合那些管理文档或静态网站的用户。

该技能通过支持只读集成令牌和选择性页面共享来优先考虑安全性。它处理 Notion 基于块的架构的复杂性，将标注、嵌套列表和代码块等元素转换为标准 Markdown 语法，以便进行版本控制或发布。

下载入口:https://github.com/openclaw/skills/tree/main/skills/vaibhav1805/notion-to-markdown

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Notion 转 Markdown 转换器 应用场景

• 为技术文档或 README 文件导出单个 Notion 页面。
• 批量导出整个数据库，以供 Hugo、Jekyll 或 Next.js 等静态网站生成器使用。
• 自动化从 Notion 到 GitHub 或其他支持 Markdown 的平台的内容迁移。
• 以人类可读、便携的格式创建 Notion 工作区的本地备份。
• 使用 Openclaw Skills 模式将 Notion 内容集成到自动化 CI/CD 文档流水线中。

1. 用户提供 Notion API 密钥以及特定的页面 ID 或数据库 ID。
2. 该技能建立与官方 Notion API 的安全连接。
3. 它检索页面属性并递归遍历块树。
4. 每个 Notion 块（标题、段落、图像等）都映射到其对应的 Markdown 格式。
5. 如果目标是数据库，该技能将遍历所有条目并生成单独的文件。
6. 最终输出以纯净的 Markdown 字符串形式交付，或保存到指定的本地目录。

Notion 转 Markdown 转换器 配置指南

要开始使用 Openclaw Skills 集合中的这项技能，请按照以下步骤操作：

# 1. 克隆并进入脚本目录
cd scripts

# 2. 安装必要依赖
npm install

# 3. 配置环境变量
echo "NOTION_API_KEY=your_integration_token" > .env

# 4. 转换单个页面
node convert.js  > output.md

# 5. 导出数据库
node convert.js  --database ./exports

Notion 转 Markdown 转换器 数据架构与分类体系

该技能在组织提取的数据时，重点在于保留上下文和元数据：

name: notion-to-markdown
description: "Convert Notion pages and databases to markdown format using the official Notion API. Use when you need to: (1) Export a single Notion page to markdown, (2) Bulk export entire Notion databases, (3) Automate Notion content publishing, or (4) Integrate Notion content into documentation workflows. Requires Notion API token setup."
metadata:
  requiredCredentials: "NOTION_API_KEY"
  credentialsType: "Notion API token (personal integration)"
  networkAccess: "Notion API only (@notionhq/client)"
  supplyChainRisk: "Low - only talks to official Notion API, no external data sources"
  security: "Read-only access recommended. Only shares specific pages, not entire workspace."

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  > output.md

Database export:

NOTION_API_KEY=your_token node convert.js  --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  > 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 

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(/
{3,}/g, '

');  // 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