把 Markdown 文档发给没装任何工具的人：
导出单文件 HTML 实战

先说痛点：.md 发出去，对方看到的是「源码」

你精心排好的周报、方案、接口文档，本质是一个 .md 文本文件。发给装了 Typora、VS Code 的人没问题；但发给一个电脑上什么 Markdown 工具都没装的同事，用记事本或浏览器打开，看到的是这样的东西：

## 本周进展
### 已完成
- 完成登录模块联调，通过全部 42 个用例
![项目现场照片](photo.jpg)

满屏的 #、*、[]()，照片还裂着（photo.jpg 根本没跟着发过去）。我们之前写过一篇为什么 .md 打开全是 # 号专门解释这个现象——问题不在文件，在「看的方式」。

常见解法各有各的别扭：

• 转 PDF：排版固定没问题，但想改个措辞、复制段代码就费劲，而且 PDF 里的链接和目录跳转体验一般（想走这条路看转 PDF 教程）；
• 发截图：长文档要截十几张，文字变图片没法复制、没法搜索；
• 让对方装工具：只是看一份文档，凭什么让人家装个编辑器？
• 传到在线平台：内部资料上传第三方服务器，想过保密这关吗？

其实每台电脑上都预装了世界上兼容性最好的「文档查看器」——浏览器。缺的只是一个把 Markdown 渲染结果变成「浏览器直接能开、还自带图片」的文件。这正是 mdview「导出单文件 HTML」做的事。

单文件 HTML 是什么：一个文件 = 整个页面 + 全部图片

mdview 的导出不是把 .md 源码简单包一层，而是拿你屏幕上已经渲染好的那份页面来打包：

• 排版完整保留：标题层级、表格对齐、代码高亮、任务列表、脚注……渲染成什么样，导出物就是什么样；
• 本地图片全部内置：文档里引用的本地图（photo.jpg、assets/截图.png、甚至 ../素材/ 目录外的图）都被读出来转成 base64 编码，直接嵌进 HTML 文件内部——导出后整个文件夹只剩一个 .html，不依赖任何图片文件；
• 双击即开：接收方用 Chrome / Edge / Firefox 甚至手机浏览器双击打开就能看，不需要联网（下文细说）、不需要装任何工具；
• 主题跟随导出时刻：你当时是深色模式导的，对方打开就是深色模式。

一句话：把「你看到的样子」原封不动装进一个文件寄出去。

实操：三步导出，两步发送

第一步：用 mdview 打开文档

双击 .md 文件（装了 mdview 后默认就是它打开），或者右键 → 打开方式 → mdview。确认图片都能正常显示——导出物打包的是当前渲染结果，预览里裂的图导出后同样是裂的，所以先把图片路径修好。

第二步：右键 → 导出 → 导出单文件HTML

在预览窗口任意位置右键 → 导出 → 导出单文件HTML（就在「导出PDF」旁边）。弹出的保存对话框里选个位置，默认文件名与你的 .md 同名。点保存，一两秒后提示「已导出」。

这一步就是全部操作。mdview 会自动完成：扫描正文里所有 <img> → 把本地图片读出来转 base64 嵌入 → 组装成自包含的单文件 HTML。

第三步：把这一个文件发出去

微信、邮件、网盘……随便什么渠道，只发导出的那一个 .html 文件。对方收到后双击（或拖进浏览器），完事。

不用再打包图片文件夹了。传统做法要把 .md 和 images/ 一起压缩成 zip 发过去，对方解压后还经常因为相对路径变了而裂图。单文件 HTML 从根上消灭了这个问题——图片就在文件里面。

眼见为实：演示文档长这样

本文开头的下载卡片里放了一份完整的演示物料。源 .md 的关键部分如下——一份「项目周报」，中间引用了两张本地照片（我们预先把网络照片下载到了 .md 同目录，模拟最常见的「配图文档」场景）：

# 项目周报：第 35 周

## 现场照片

下面两张照片来自网络相册，导出成单文件 HTML 后会
**一起打包进 HTML 文件里**，对方收到文件就能直接看到：

![项目现场照片一](photo.jpg)

![项目现场照片二](photo2.jpg)

## 关键数据

| 指标 | 本周 | 上周 | 环比 |
| --- | ---: | ---: | ---: |
| 日活 | 12,400 | 11,800 | +5.1% |

在 mdview 里右键导出单文件 HTML 后，得到的 项目周报.html 用浏览器打开：

关于「离线」的几句实话

单文件 HTML 里，文字、表格、图片是 100% 离线可看的——它们都物理存在于这一个文件里。

有三个「增强项」走的是联网加载：代码块语法高亮、Mermaid 图表、KaTeX 公式的渲染引擎脚本，导出时引用的是官网静态资源而非内嵌（为了让大多数纯文字文档的导出物保持几百 KB 而不是几 MB）。联网打开时这些增强渲染全部生效；断网打开时正文无损，代码块退化为源码态展示，图表与公式保持原始文本。所以：

• 周报、方案、带照片的说明文档（绝大多数场景）：离线体验完整；
• 技术文档里如果大量依赖图表/公式，建议对方在有网环境首次打开。

另外，文档里本来就是 https:// 开头的网络图片不会被打包（它们不在你磁盘上），导出后依然按原链接加载——想让它们也内置，先把图下载到本地、把引用改成本地路径再导出即可。演示文档就是这么做的。

跟另外两种分享方式比一比

整个导出过程在你的电脑上完成，文档不经过任何服务器——和 mdview 的其他功能一样，纯本地处理。

几个实战小技巧

• 先修图再导出：预览里图片裂图（路径写错、文件挪了位置）导出物会原样保留裂图，导出前扫一眼；
• 大照片先压缩：base64 会让体积膨胀约三分之一，手机原图动辄 5MB，插文档前用 ImgTool 之类的工具压一下，导出物能小一个量级；
• 命名带日期：发给别人的版本建议存成「方案-0829.html」这种，避免来回修改后双方分不清哪个是最新版；
• 配合标题折叠：导出物同样支持 H1~H3 标题折叠，长文档对方也能收起无关章节快速定位。

小结

下次要把 Markdown 文档发给「什么工具都没装」的人，记住这条路径：

mdview 打开 → 右键 → 导出 → 导出单文件HTML → 发那一个文件。

渲染排版、表格、本地照片全部装进一个 .html，对方双击就看，看完想复制文字也随意。演示物料就在本文开头的下载卡片里，先下载那个 640KB 的 HTML 感受一下「收到的人看到什么」，再装个 mdview 自己导一份。