先说一下我为什么会盯上这个 3MB 的小东西。上周有位同事拿一篇 200 多页的技术方案 Markdown 来找我说急着转成 Word 给客户在线转换网站传了三次都超时换了两个平台不是要求注册就是限制文件大小。公司内网环境下这类在线工具更是直接歇菜。我在网上翻了一圈最后找到一个只有 3MB 的本地小工具 mdput绿色免安装双击就能用。实测下来打开 Markdown 基本是秒开转 Word、PDF、HTML 都是一键完成关键是完全离线运行断网也能干活没有任何广告和付费墙。这篇就当作一次纯个人向的使用记录把 mdput 的安装、日常操作、各种格式导出的细节以及我踩过的坑都梳理一遍。不管你是只拿 Markdown 记笔记的新手还是需要频繁把文档交付出去的开发者、技术写作者这篇内容应该都能帮你省下不少时间。1. 内容整体设计与思路拆解为什么一个 3MB 的工具敢说“全都能干”1.1 大而全工具的痛点杀鸡用了宰牛刀市面上主流的 Markdown 编辑器要么走“全家桶”路线要么走“在线优先”路线。前者像 VS Code 装上各种 Markdown 插件功能确实强但为了写一篇笔记要启动一个几百 MB 的编辑器配置同步、插件更新、工作区设置折腾一圈下来很多时间都耗在工具本身。后者像各类在线转换网站上传下载流程繁琐不说文档隐私基本没有保障。我身边很多同事的情况是手上根本不缺 Markdown 编辑器缺的是一个能快速把 Markdown 变成正式交付物的转换工具。方案评审要 Word日报周报要 PDF内部知识库要 HTML每次都要在不同工具之间来回切换。mdput 解决的就是这个“最后一公里”的问题它把 Markdown 编辑和三种格式导出全部做进了一个 3MB 的可执行文件里。1.2 3MB 体积是怎么做到的轻量壳加内置转换引擎第一次看到 3MB 这个体积我也怀疑过是不是挂着羊头卖狗肉。后来看了下它的运行方式才明白mdput 没有捆绑庞大的运行时环境而是调用了操作系统自带的 WebView 组件来渲染界面再加上一个用原生语言写的解析和转换核心所以体积才能压到这么小。这意味着它对运行环境有一个基本要求Windows 10/11 需要系统里带有 WebView2 运行时macOS 和 Linux 则依赖系统自带的 WebKit/GTK 组件。绝大多数更新过的系统都已经具备这些组件我自己的 Windows 笔记本上一切正常另一台老旧的 Win10 机器上也能直接用。说句实在话这个设计思路有点像“用最小的刀干最精准的活”。它没有把目标定成替代 VS Code 或 Typora而是专注做一件事轻量打开、快速转换。目标用户也很清晰——不想折腾、只想把文档快速交付出去的人。这是它能在如此小的体积下保持完整功能的关键。2. 安装与环境准备拿到手 5 分钟跑起来2.1 下载前先确认系统环境能省掉后续 80% 的麻烦mdput 的下载包很小从官网或项目发布页拿下来通常就是一个压缩包。Windows 下解压后是一个mdput.exe单文件Linux 是mdput.AppImagemacOS 则是.dmg。不用安装、不用写注册表放在 U 盘里带走也能用对经常换电脑的人来说非常友好。下载之前建议先确认两件事。第一操作系统是不是 64 位现在的新版本基本都是按 64 位打包的第二Windows 系统是否安装了 WebView2 运行时。检验方法很简单在 Edge 浏览器地址栏输入edge://settings/help能看到版本号说明 WebView2 已经存在。如果缺失微软官网有独立安装包装完重启一次 mdput 就正常了。2.2 从压缩包到能编辑文件只需要三步解压之后的操作没什么门槛但为了第一次使用能顺畅一些我把步骤拆开说明一下。将下载好的压缩包解压到一个固定目录比如D:\Tools\mdput不要直接放在桌面或下载文件夹里避免误删。双击运行mdput.exe首次启动因为要初始化本地配置可能稍微慢一点正常也就一两秒。在界面左上角点击“打开文件”找一个已有的.md文件载入。如果手上没有现成的 Markdown 文件可以直接点击“新建”在左侧编辑区输入内容右侧预览会实时刷新。到这里基本环境就搭好了。关闭软件后它会自动记住上次打开的目录和最近编辑的文件列表。我用了几天后发现如果直接双击.md文件想用 mdput 打开需要在系统设置里手动关联一下文件后缀否则系统会默认调用记事本。在 Windows 上右键.md文件选择“打开方式”指向mdput.exe并勾选“始终使用此应用”以后双击就是秒开。2.3 关于离线运行与免费授权谁适合用它既然标题强调“离线全免费”我就把这两点实测结果说清楚。mdput 的所有功能都在本地执行编辑、转换、导出全程不需要联网。我专门断网试过除了首次启动时检查版本更新那一步会失败不影响使用其他功能完全正常。导出 PDF 和 Word 时也没有任何“需要联网下载组件”的提示。免费这一点目前看来是实打实的没有隐藏付费菜单没有文件数量限制导出也不会像某些在线工具那样偷偷嵌入水印。不过要提醒一下这种轻量工具通常靠捐赠或者后续可能推出的 Pro 版维持开发。我的建议是趁现在免费且稳定先用它把工作流跑起来。如果以后真推出专业版再根据需求决定要不要升级。3. 核心功能实操Markdown 编辑与“秒开”背后到底有什么3.1 秒开不是玄学是轻量渲染引擎的功劳很多人对“秒开”没什么概念我自己之前用 Electron 框架的编辑器打开一个包含大量图片和表格的长文档预览面板总要卡顿一两次。mdput 秒开的体验来自于两点一是没有加载冗余插件和后台服务二是预览渲染用的是内置的高性能 Markdown 解析库而不是加载整个浏览器内核。我实测打开一个 1.5MB、包含 200 多行代码块和若干表格的 Markdown 文档从双击文件到完整渲染出预览大约 1 秒。继续滚动、编辑时预览更新也基本没有肉眼可见的延迟。如果你日常处理的文档大多在几百 KB 以内这个工具用起来会非常轻快。3.2 编辑器的核心操作快捷键和常用功能mdput 的界面走的是“左侧源码、右侧预览”的双栏布局和大多数 Markdown 编辑器一致几乎不需要学习成本。顶部工具栏只有几个核心按钮打开、保存、导出、切换主题。快捷键支持得很完整常用的几个我在下表中列出来方便第一次上手的读者直接“抄作业”。操作Windows 快捷键macOS 快捷键新建文件Ctrl NCmd N打开文件Ctrl OCmd O保存文件Ctrl SCmd S加粗Ctrl BCmd B斜体Ctrl ICmd I插入代码块Ctrl Shift KCmd Shift K切换预览/编辑模式Ctrl Shift PCmd Shift P导出菜单Ctrl ECmd E这里重点说一下“插入代码块”这个快捷键。mdput 插入的代码块会直接生成带语言标注的围栏代码块如果你在写 Python 或 JavaScript它会自动加入对应的语言标识。相比先手打三个反引号再补语言名快捷键操作能省掉不少麻烦。3.3 从零写一篇带表格和代码块的 Markdown为了验证编辑器的语法支持我专门从零写了一份包含标题、列表、表格、代码块的测试文档。实际体验下来mdput 对 GFMGitHub 风格 Markdown的支持比较完整常见的表格、任务列表、删除线都能正确渲染。这里给新手一个参考你新建文件后可以直接把下面这段内容粘贴进去体验效果# 季度总结报告 ## 完成事项 - [x] 完成身份认证模块重构 - [ ] 补充自动化测试用例 | 模块 | 负责人 | 状态 | | ---- | ------ | ---- | | 登录 | 张三 | 已完成 | | 支付 | 李四 | 开发中 | ## 核心代码示例 python def welcome(name): return fhello, {name}粘贴后右侧预览会立刻渲染出标题、勾选框、表格和带语法高亮的代码块。输入体验整体很流畅没有明显的输入延迟。唯一的小遗憾是它目前不支持像 Typora 那样的“所见即所得”模式源码和预览始终是分开的。但对于主要用途是“快速编辑加转换”的使用场景来说这个设计并不影响效率。 ## 4. 一键导出 Word / PDF / HTML三个格式的完整操作细节 ### 4.1 导出 Word标题自动映射但别忽略样式微调 导出 Word 是很多办公场景的刚需也是我实测下来最满意的一项功能。点击工具栏的“导出”按钮选择“Word 文档”程序会基于 OOXML 规范生成一个 .docx 文件。这里有几个关键细节需要留意。 mdput 在导出 Word 时会把 Markdown 的各级标题自动映射为 Word 的“标题 1”“标题 2”“标题 3”样式。这意味着生成的文件自带大纲层级在 Word 里可以直接用导航窗格跳转章节也可以一键生成目录。代码块会渲染成等宽字体加灰色底纹表格则映射为 Word 原生表格列宽会按照内容自动分配。 实际操作中我发现如果文档里使用了非常长的表格自动生成的列宽可能会不太合理。建议导出后在 Word 中选中表格使用“自动调整”里的“根据窗口调整表格”一键优化。另外如果你希望在导出时就固定某些样式比如中文字体必须是宋体、小四号目前 mdput 还不支持在导出界面里直接配置自定义样式需要到 Word 里批量修改。这个算是它的一个局限但对于大多数内部交付场景已经够用。 ### 4.2 导出 PDF先调整页面设置再导出避免中文乱码和分页错乱 PDF 导出是最容易出问题的一环尤其是中文文档。mdput 在导出 PDF 时实际上是用内置的打印引擎把渲染后的页面输出为 PDF 文件因此页面设置直接决定了输出效果。 我第一次直接导出时发现中文显示正常但默认页边距偏大一些较宽的表格被截断到了页面外。后来在导出前先点击界面右上角的“页面设置”把页边距从默认的 25mm 调整为 15mm表格截断的问题就基本解决了。如果你文档里有很宽的代码块建议开启“允许代码块换行”选项否则长代码行会被裁切。 字体方面如果出现中文乱码或者“豆腐块”通常是系统缺少对应中文字体。Windows 系统一般自带微软雅黑和宋体macOS 自带苹方理论上都能正常渲染。真遇到字体问题时最简单的办法是在页面设置里切换一下字体选项或者确认系统字体是否完好。PDF 分页方面mdput 会尽量保留标题与下方内容的关联不会出现标题孤悬在页面底部的情况。 ### 4.3 导出 HTML主题切换与插入网页场景 把 Markdown 导出成 HTML 也是很多技术写作场景的需求。mdput 在导出 HTML 时提供了几套内置主题包括 GitHub 风格、护眼绿、极简白、暗黑模式。我平时写技术文档基本用 GitHub 风格原因很简单代码高亮的配色看着舒服和主流代码托管平台的阅读体验一致。 导出时需要注意一点如果你在文档中引用了本地图片默认情况下 HTML 中会使用相对路径引用图片文件而不是把图片内嵌到 HTML 里。这意味着单独把 HTML 文件发给别人图片可能显示不出来。解决办法有两个一个是在导出前勾选“嵌入图片”把图片转为 Base64 编码直接写进 HTML缺点是文件体积会变大另一个是连同图片目录一起打包发送。 对于需要发布到内部知识库的场景我一般选择“嵌入图片”的 HTML这样单文件就能完整展示所有内容。而对于要长期维护的文档我则保留相对路径版本方便后期更新。 ### 4.4 批量转换与命令行调用一次处理几十个文件的正确姿势 mdput 还提供了一个命令行工具叫 mdput-cli用于批量转换。如果你有几十个甚至上百个 Markdown 文件需要统一转成 PDF用图形界面一个个点显然不现实。命令行模式下几秒就能跑完。 下面是我在 Windows PowerShell 和 Linux 终端中实测可用的几个命令示例 bash # 单个文件转 Word mdput-cli report.md -o report.docx # 单个文件转 PDF mdput-cli report.md -o report.pdf # 批量转 HTML输出到指定目录 mdput-cli docs/*.md --outdir output --format html # 指定转换主题仅对 HTML 有效 mdput-cli report.md -o report.html --theme github批量转换时有一个容易被忽略的细节如果 docx 或 pdf 文件名与源文件同名务必确认输出目录不能是源文件所在目录否则可能因为锁定问题导致转换失败。另外命令行模式下批量转 PDF 时如果文档数量很大建议分批处理每批控制在 50 个以内这样既能避免内存占用过高也方便排查中途出错的文件。5. 常见问题与排查技巧实录那些文档里不会写的坑5.1 导出 Word 后格式错乱问题可能出在“空行”上有次我把一篇从某个在线文档平台直接复制的 Markdown 内容导入 mdput导出 Word 后发现很多段落粘在一起标题层级也乱了。排查了半天发现根因是原文的空行不规范——有些地方用了两个空格加换行有些地方用了多个空行导致 mdput 的解析器把同一段落的内容当成了不同段落。解决方法是先在 mdput 的编辑界面里打开“源代码”点击工具栏的“清理格式”功能。这个功能会自动把多余空行压缩、标准化换行符。之后再导出 Word格式就正常了。我后来养成了一个习惯任何从外部复制来的 Markdown 内容第一件事就是先点一下“清理格式”再开始编辑。5.2 PDF 中文乱码或字体缺失先检查系统字体不要急着怪工具有一次我在一台精简版的 Windows 服务器上导出 PDF所有中文都变成了方框。第一反应以为工具出问题了后来在系统字体目录里一看那个系统居然连中文字体都没装全。这种情况并不是 mdput 的问题而是操作系统缺少可用中文字体。确认方式很简单在 mdput 的页面设置里切换字体查看列表中有没有可用的中文字体。如果没有安装一款免费开源的思源黑体或者从其他电脑复制微软雅黑字体文件并安装刷新后重新导出即可。另外如果你的文档中包含了生僻字或者特殊符号在导出前先做一次预览确认没有显示异常再导出 PDF可以避免浪费打印纸张和调整时间。5.3 大文档卡顿或内存占用偏高时的两个优化方案虽然 mdput 体积小但如果你打开一个几十 MB 的超大 Markdown 文件任何工具都会有压力。我测试过一个包含大量高清图片的 20MB 文档预览滚动时出现了明显的卡顿。这里有两个优化经验。第一个是拆分文档。如果是为了转换而不是编辑直接用命令行工具按章节拆分成多个文件再分别处理效率反而更高。第二个是在图形界面中关闭实时预览切换到纯编辑模式等编辑完成后再打开预览。具体方法是点击顶部工具栏的眼睛图标把预览面板关掉。编辑和渲染互不干扰卡顿感会大幅减轻。5.4 表格和图片丢失大概率是语法或路径写错了表格缺失的问题通常出在 Markdown 表格语法不规范上。比如表头和分隔行之间少了空格或者单元格里的竖线没有转义。mdput 的解析器会直接把这种无效表格当作纯文本处理而不是报错。遇到这种情况检查原文档中的表格语法是否符合 GFM 规范修复后重新导出即可。图片丢失则更多是路径问题。在图形界面中编辑时相对路径的图片能正常显示是因为 mdput 会自动基于文档所在目录解析。但如果你预览正常、导出后图片却丢了尤其是转为 PDF 或内嵌 HTML 时确认导出设置中的“嵌入图片”是否开启。如果只勾选“复制图片”而不是“嵌入”记得把图片目录一起带走否则在另一台电脑上打开文件就看不到图了。5.5 常见问题速查表现象可能原因快速处理办法Word 导出后标题层级错乱原文空行不规范标题前缺少空行先“清理格式”再导出PDF 中文显示为方框系统缺少中文字体安装中文字体后重新导出表格被截断到页面外页边距过大或表格过宽页面设置调小边距开启自动换行导出 HTML 后图片不显示未嵌入图片或图片路径失效开启“嵌入图片”或连同图片目录一起分发打开超大文件卡顿实时预览压力过大关闭预览使用纯编辑模式命令行批量转 PDF 失败输出目录与源目录相同文件被锁定更换输出目录分批转换双击 .md 文件无法用 mdput 打开系统尚未关联文件后缀右键“打开方式”手动关联一次6. 一些使用心得和进阶技巧工具这个东西好不好用往往用一段时间才知道。mdput 我连续用了快三周现在的日常状态是VS Code 依然装着但它对我来说变成了一个纯粹的代码编辑器而只要涉及 Markdown 阅读、简单编辑、格式导出这些事我全部交给 mdput因为它启动够快、没有干扰、导出稳定。分享一个我很常用的小流程我会在项目仓库的 docs 目录下直接用 mdput 新建文档写好之后用mdput-cli一次性把新增的几篇文档转成 PDF 发给同事评审同时再导出一份 HTML 挂到内部知识库。整个流程从文档完成到对外可见不会超过五分钟。以前用在线工具时还要考虑文件大小限制、上传等待和隐私问题现在完全不用操心了。如果你和我一样经常需要在 Markdown 和 Word/PDF/HTML 之间来回切换可以试着把 mdput 当成你的默认 Markdown 打开工具用上一周再回来看这篇内容你会发现大部分操作已经变成了肌肉记忆。我个人觉得它最值钱的地方不是那 3MB 的体积而是它把“从 Markdown 到正式交付物”这条链路压缩到了几秒钟同时还不依赖网络不绑架你的数据。