OneNote 一键转 Markdown 完整指南onenote-md-exporter 十分钟上手免费迁移【免费下载链接】onenote-md-exporterConsoleApp to export OneNote notebooks to Markdown formats项目地址: https://gitcode.com/gh_mirrors/on/onenote-md-exporter本文围绕 onenote-md-exporter 这款免费开源工具展开教你如何把 OneNote 笔记本完整、无损地转换为 Markdown 文件解决笔记迁移中的格式丢失、层级扁平化与链接失效三大痛点。无论你的目标是切换到 Obsidian、Joplin还是给多年笔记做一份开放格式的长期备份这篇文章都会给你一份从安装、配置到自动化的完整路线图。一个周末下午的真实困境小陈是某科技公司的产品经理四年来的会议纪要、需求文档、用户访谈全躺在 OneNote 里累计 2000 多个页面。公司决定全面切换笔记平台他试着把内容复制粘贴到新工具里——结果表格全乱、图片位置丢失、几十条页面互相引用的内部链接全部变成死链。最要命的是OneNote 精心整理的分区层级在导出后全部被拍扁成平铺文件。他的经历并非个例。OneNote 用户迁移时普遍面临三类问题复杂格式还原度低、页面层级结构被摊平、笔记间的关联链接全部失效。手动复制黏贴不现实在线转换服务又要把私人笔记上传到云端数据安全没有保障。如果你也在为类似的事情发愁onenote-md-exporter 就是为你准备的答案。这个工具到底是什么onenote-md-exporter 是一个运行在 Windows 上的命令行程序作用只有一个把 OneNote 笔记本批量导出为 Markdown 格式。它有两个特点让它和其他导出方式区分开来完整保留结构分区、分区组、页面父子关系都会按照你的选择还原成文件夹树或文件名前缀。完全离线运行所有处理都在本机完成不依赖微软云端也不会上传任何数据。它适合三类人正在评估或迁移到 Obsidian、Joplin 等 Markdown 笔记软件的用户想把 OneNote 数据转成开放格式长期归档的用户需要把企业 OneNote 文档整体转移到 Markdown 协作平台的团队。底层是怎么工作的整个导出过程可以看作一条流水线源码中对应的核心类位于src/OneNoteMdExporter/Services/Export/数据提取通过 OneNote 与 Word 的官方 Interop API把每个页面发布成 DocX 临时文件同时读取页面 XML 结构。格式转换调用内置的 Pandoc 引擎把 DocX 翻译成目标 Markdown 语法默认 GitHub Flavored Markdown。后处理修复对生成的 Markdown 做多轮正则修正包括去重复空行、清理多余引用块、把 HTML 图片标签转成标准 Markdown 引用等。值得一提的是在转换之前工具还会对页面 XML 做预处理比如展开折叠段落、把 OneNote 标签转成对应的表情符号、处理缩进样式。这部分逻辑在ExportServiceBase.cs的PageXmlPreProcessing方法中如果你对实现细节感兴趣可以直接翻阅源码。运行前的环境准备在动手之前先对照下面的清单检查你的电脑项目要求操作系统Windows 10 或更高版本OneNote2013 及以上桌面版商店版不支持Word2013 及以上版本运行时无需额外安装程序已自带 .NET 运行时这里有个容易踩的坑Windows 商店里安装的 OneNote UWP 版无法被 Interop API 访问必须使用桌面版 OneNote。如果你不确定自己装的是哪个版本可以先打开 OneNote在文件 账户里查看版本信息。三步完成安装获取源码git clone https://gitcode.com/gh_mirrors/on/onenote-md-exporter打开src/OneNoteMdExporter/pandoc/目录把里面的pandoc-3.8.3-windows-x86_64.zip解压将pandoc.exe放到该目录下。用 Visual Studio 打开src/OneNoteMdExporter.sln编译或直接使用发布版程序。如果你只是想快速试用而不关心源码直接运行编译好的OneNoteMdExporter.exe即可。仓库里还附带了一个sample/TestNotebook.onepkg示例笔记本可以先拿它练手不用拿自己的正式笔记冒险。第一次运行全程交互式操作启动前记得先打开 OneNote 并确保要导出的笔记本已完成同步。接着双击运行程序按下面的提示一步步走程序会列出检测到的笔记本输入序号选择要导出的那一个输入0表示导出全部笔记本。选择导出格式输入1导出为标准 Markdown 文件夹输入2导出为 Joplin Raw Directory 格式。程序询问是否调整设置时输入y会用记事本打开appSettings.json你可以顺手改几项下文会讲怎么改。确认后进入两阶段处理先扫描构建页面树再逐页导出转换。期间你可以安心去冲杯咖啡 ☕。全部完成后程序会自动用资源管理器打开导出文件夹检查结果即可。首次运行时如果遇到System.Runtime.InteropServices.COMException之类的报错多半是 OneNote 没有完全启动或 Office 安装有问题可以先重启 OneNote 再试。完整的排查思路放在后文的 FAQ 里。命令行模式参数化批量导出交互式操作适合第一次试用真正的高效玩法是命令行参数。运行OneNoteMdExporter.exe --help可以查看全部参数说明参数说明-n, --notebook指定要导出的笔记本名称-f, --format导出格式1为 Markdown2为 Joplin 文件夹-s, --section只导出指定分区需配合--notebook-p, --page只导出指定页面需配合--section--all-notebooks导出所有笔记本--no-input全程无需人工输入适合脚本调用--debug调试模式保留临时文件并输出详细日志--ignore-errors某页导出失败时跳过继续不中断整个任务几个实用示例# 导出工作笔记笔记本为 Markdown输出到指定目录 OneNoteMdExporter.exe --notebook 工作笔记 --format 1 --output D:\笔记备份 # 只导出学习资料中考研分区的页面使用 Joplin 格式 OneNoteMdExporter.exe --notebook 学习资料 --format 2 --section 考研 # 静默导出全部笔记本适合放入计划任务 OneNoteMdExporter.exe --all-notebooks --no-input --ignore-errors注意--output参数并非真实存在的选项导出目录由程序根据笔记本名称和时间自动创建。如果对参数有疑问建议先不加参数运行一次观察程序实际生成的目录结构。配置文件详解三大核心决策appSettings.json是决定导出效果的枢纽文件全部配置项带注释结构清晰。其中最重要的决策有三个。决策一页面层级怎么还原OneNote 允许页面下嵌套子页面导出时有三种处理方式对应ProcessingOfPageHierarchy取值目录形态适合场景HierarchyAsFolderTree分区/父页面/子页面.mdObsidian 等支持文件夹嵌套的编辑器HierarchyAsPageTitlePrefix分区/父页面_子页面.md偏好扁平目录、文件名自带层级IgnoreHierarchy分区/子页面.md完全不需要层级信息决策二图片和附件放哪里ResourceFolderLocation决定资源文件图片、附件的存放位置RootFolder全部收进导出根目录下的一个统一资源文件夹便于集中备份。PageParentFolder资源放在每个页面文件旁边方便把单页连同资源一起移动和分享。决策三内部链接怎么处理OneNote 页面间的onenote://链接在导出后默认无法点击OneNoteLinksHandling提供四种策略取值转换结果推荐平台KeepOriginal保留原始onenote://链接未来可能回迁 OneNoteConvertToMarkdown文本Joplin 及通用 Markdown 编辑器ConvertToWikilink[[页面路径\|显示文本]]Obsidian、Logseq 等双链笔记Remove删除链接、仅保留显示文本只需要干净正文注意跨笔记本的链接以及指向分区的链接无法转换会被直接移除这是当前版本的设计限制。除了三大决策还有几个值得留意的开关AddFrontMatterHeader会在每个页面头部加上 YAML 元数据标题、创建时间、更新时间格式如下--- title: 页面标题 updated: 2024-05-01T10:30:00 created: 2023-11-11T09:00:00 ---PanDocMarkdownFormat可以切换 Pandoc 支持的多种 Markdown 方言默认gfmGitHub 风格兼容性最好UseHtmlStyling决定是否保留字体颜色、背景色等 HTML 样式标签IndentingStyle控制缩进内容的呈现方式原样保留、转全角空格、转项目符号。内容保真度哪些保留、哪些丢失动手迁移前最好先了解工具对各种内容类型的支持情况避免期望落差。官方 README 里的这份对照表很有参考价值内容类型支持程度转换结果文件附件✅原样复制到资源文件夹图片✅提取为独立文件并插入引用简单表格✅标准 Markdown 表格复杂表格含嵌套✅HTML 表格需编辑器支持 HTML折叠段落✅自动展开字体颜色 / 背景色✅HTML 样式标签文本标签任务、星标等✅转为对应表情符号绘图内容扁平化为图片密码保护分区导出前未解锁则丢失手写笔记不支持会丢失如果目标编辑器支持 HTML如 Obsidian、Joplin复杂表格和颜色样式都能保留如果只能用纯 Markdown 渲染器建议导出前关闭UseHtmlStyling。再对比一下两种导出格式的差异特性Markdown 格式Joplin Raw 格式分区层级文件夹树嵌套笔记本结构分区内页面顺序依赖文件名排序完整保留原始顺序页面父子层级文件夹或文件名前缀完整保留内部链接四种策略可选转为 Joplin 资源引用导入方式直接使用Joplin 菜单导入两种格式的通用处理逻辑都封装在ExportServiceBase.cs中差异部分分别实现在MdExportService.cs和JoplinExportService.cs想深入了解可以对照阅读。三个场景的推荐配置方案下面给出三套开箱即用的配置按你的目标平台选择。方案 AObsidian 双链笔记重点是 wikilink 和文件随页面移动{ ProcessingOfPageHierarchy: HierarchyAsFolderTree, ResourceFolderLocation: PageParentFolder, OneNoteLinksHandling: ConvertToWikilink, AddFrontMatterHeader: true, PanDocMarkdownFormat: gfmraw_html, UseHtmlStyling: true }方案 BJoplin 原生导入重点是 Markdown 链接和根目录资源{ ProcessingOfPageHierarchy: HierarchyAsFolderTree, ResourceFolderLocation: RootFolder, OneNoteLinksHandling: ConvertToMarkdown, AddFrontMatterHeader: true, PanDocMarkdownFormat: gfm, PostProcessingMdImgRef: true }Joplin 的导入步骤很简单先以格式 2 导出然后在 Joplin 里点击文件 导入 RAW - Joplin Export Directory选择导出文件夹即可。更详细的对比说明可以参考项目文档doc/migration-to-joplin.md其中还对比了传统 OneNote→ENEX→Joplin 路线那条路线会把分区层级拍平成标签页面顺序也会丢失。方案 C最小化通用导出{ ProcessingOfPageHierarchy: IgnoreHierarchy, ResourceFolderLocation: RootFolder, OneNoteLinksHandling: Remove, AddFrontMatterHeader: false, PanDocMarkdownFormat: commonmark, UseHtmlStyling: false }这套配置适合把笔记转成最朴素的 Markdown 做纯文本归档任何编辑器都能正常打开。常见问题速查Q1启动就报 COMException 错误怎么办这通常是本机 Office 环境的问题按顺序尝试重启 OneNote 并登录账号 → 以管理员身份运行程序 → 修复或重装 Office。如果还不行可以在 OneNote 里通过文件 导出把笔记本打包成.onepkg步骤见doc/notebook-onepkg-export.md换一台电脑导入后再导出。Q2导出后发现部分图片丢失或损坏先在 OneNote 的文件 选项 同步中开启下载所有文件和图像强制同步笔记本后重新导出。Markdown 里引用的是相对路径注意不要单独移动.md文件而丢下资源文件夹。Q3大笔记本导出很慢怎么加速按分区分页分批导出用--section、--page参数或者配合--debug先小范围试跑把导出目录放到 SSD 上也能明显改善 IO 性能。Q4能不能批量导出多个笔记本可以。用--all-notebooks一次导出全部或者用 PowerShell 循环调用见下一节。把导出流程接入你的日常工作流对于每月备份一次笔记这类重复需求可以写一个简单的 PowerShell 脚本$notebooks (工作笔记, 项目文档, 学习资料) $exe C:\Tools\OneNoteMdExporter.exe foreach ($name in $notebooks) { Write-Host 开始导出: $name $exe --notebook $name --format 1 --no-input --ignore-errors # 统计本次导出生成的 md 文件数量 $count (Get-ChildItem $env:USERPROFILE\Documents\OneNoteMdExporter -Recurse -Filter *.md | Measure-Object).Count Write-Host 完成: 共 $count 个 Markdown 文件 }再把这个脚本挂到 Windows 任务计划程序里就能实现定时自动备份。团队场景下也可以把导出脚本作为 CI 流程的一步每次文档变更后自动生成最新快照配合 Git 做版本管理。迁移后的几件收尾小事导出完成不等于迁移结束建议花几分钟做这几件事抽查渲染效果用目标编辑器打开若干页面确认表格、图片、链接正常。修复残余链接用正则批量查找未转换的onenote://链接并手工处理。补充元数据利用 Front Matter 里的创建/更新时间在目标平台重建时间线。保留原始备份导出前先给 OneNote 笔记本做一次备份迁移确认无误后再清理。现在就开始你的迁移onenote-md-exporter 最打动人的地方在于它把迁移这件事从一场噩梦变成了一个可重复执行的任务。结构完整保留、链接策略可选、全流程离线再加上命令行和配置文件带来的自动化潜力它完全有资格成为你笔记体系升级的起点。不必追求一次完美先拿示例笔记本sample/TestNotebook.onepkg或一个小分区试跑熟悉配置项的效果再逐步迁移正式内容。挑一个周末的下午导出第一份 Markdown 笔记你会发现——原来告别 OneNote 也可以这么轻松。迁移不只是搬数据更是换一种更开放、更可控的知识管理方式而这一步现在就可以迈出去。【免费下载链接】onenote-md-exporterConsoleApp to export OneNote notebooks to Markdown formats项目地址: https://gitcode.com/gh_mirrors/on/onenote-md-exporter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考