30分钟从Markdown到Notion的完整迁移指南

【免费下载链接】md2notion项目地址: https://gitcode.com/gh_mirrors/md/md2notion

面对日益增长的知识管理需求，许多用户发现自己在不同工具间频繁切换，导致信息分散、效率低下。md2notion工具正是为解决这一痛点而生，它能够将结构化的Markdown文档无缝迁移到功能强大的Notion平台。

准备工作与环境配置

在开始迁移之前，需要完成基本的准备工作。首先确保你的系统已经安装了Python 3.6或更高版本，这是运行md2notion的前提条件。

安装依赖包

通过pip命令快速安装md2notion：

pip install md2notion

这个命令会自动安装所有必要的依赖项，包括mistletoe、notion和requests等核心库。

获取Notion访问凭证

要使用md2notion，你需要获取Notion的token_v2认证令牌。这个令牌是连接你的Notion账户与转换工具的关键凭证。

实际操作流程详解

命令行快速转换

对于简单的单文件转换，可以使用命令行工具快速完成：

python -m md2notion [你的token_v2] [目标页面URL] [Markdown文件路径]

这个命令会将指定的Markdown文件内容作为新页面添加到目标Notion页面下。

批量文件处理

如果你有多个Markdown文件需要转换，可以使用通配符模式：

python -m md2notion [token_v2] [page-url] "docs/*.md"

高级配置选项详解

md2notion提供了丰富的配置选项，满足不同用户的需求。

内容管理策略

追加模式：使用--append参数将Markdown内容添加到现有页面末尾
清理模式：使用--clear-previous参数在上传前删除同名的现有页面
图片处理：使用--html-img参数上传HTML标签中的图片

自定义图片路径解析

在某些情况下，Markdown文件中的图片路径可能需要特殊处理。md2notion允许你自定义图片路径解析函数：

def convertImagePath(imagePath, mdFilePath): return Path(mdFilePath).parent / Path(mdFilePath).stem / Path(imagePath)

编程接口深度集成

除了命令行工具，md2notion还提供了完整的Python API，方便开发者集成到自己的应用中。

基本使用模式

from notion.client import NotionClient from notion.block import PageBlock from md2notion.upload import upload client = NotionClient(token_v2="<token_v2>") page = client.get_block("https://www.notion.so/myorg/Test-c0d20a71c0944985ae96e661ccc99821") with open("TestMarkdown.md", "r", encoding="utf-8") as mdFile: newPage = page.children.add_new(PageBlock, title="TestMarkdown Upload") upload(mdFile, newPage)

高级处理流程

对于需要精细控制转换过程的场景，可以分别使用convert和uploadBlock函数：

from md2notion.upload import convert, uploadBlock rendered = convert(mdFile) # 在这里处理转换后的块描述符 for blockDescriptor in rendered: uploadBlock(blockDescriptor, page, mdFile.name)