如何在 VS Code 中将 Markdown 转为 PDF
用 Markdown PDF 从 VS Code 编辑器直接导出,或用 Markdown Preview Enhanced 从预览窗口导出。无需扩展时,也可以在浏览器中打印成文字可选取的 PDF。
VS Code 自带的 Markdown 预览没有导出 PDF 的命令。要把手头的 .md 文件发给别人,可以装一个扩展,从编辑器或预览窗口导出。如果只是偶尔转一份,也可以直接在浏览器里完成。
方法一:用 Markdown PDF 从编辑器导出
- 在 VS Code 的扩展视图中搜索
yzane.markdown-pdf,安装 Markdown PDF。 - 打开要转换的
.md文件,按F1或Ctrl+Shift+P(Mac 上按⌘⇧P)打开命令面板。 - 输入
export,选择markdown-pdf: Export (pdf)。在编辑区单击右键也能找到同一组导出选项,其中还有html、png、jpeg和all。
扩展通过 Puppeteer 调用 Chromium 渲染页面。它优先使用 markdown-pdf.executablePath 指定的浏览器,其次查找已安装的 Chrome、Edge 或 Chromium。如果都找不到,首次使用时会下载 Chromium。要关闭自动下载,把 markdown-pdf.chromium.autoDownload 设为 false。
纸张默认为 A4。如果讲义需要用 Letter 纸打印,四边各留 1.5 厘米,可以在 settings.json 中这样设置:
{
"markdown-pdf.format": "Letter",
"markdown-pdf.margin.top": "1.5cm",
"markdown-pdf.margin.bottom": "1.5cm",
"markdown-pdf.margin.left": "1.5cm",
"markdown-pdf.margin.right": "1.5cm"
}
启用 markdown-pdf.displayHeaderFooter 即可显示页眉和页脚,内容分别由 markdown-pdf.headerTemplate 和 markdown-pdf.footerTemplate 指定。markdown-pdf.outputDirectory 设置输出目录,markdown-pdf.styles 用于加载自定义 CSS。近期版本默认会过滤原始 HTML 中不安全的内容。
方法二:用 Markdown Preview Enhanced 从预览窗口导出
- 安装 Chrome 和扩展 Markdown Preview Enhanced(
shd101wyy.markdown-preview-enhanced)。 - 打开 Markdown 文件,运行
Markdown Preview Enhanced: Open Preview。要在侧边预览,按Ctrl+K V(Mac 上按⌘K V)。 - 在预览窗口内单击右键,选择
Chrome (Puppeteer),再选择导出 PDF。
如果这份文件要用 A4 纵向排版,把下面的 YAML 放在 Markdown 文件最开头:
---
puppeteer:
landscape: false
format: "A4"
---
方法三:不装扩展,在浏览器里转换
打开 ConverterTo 的 Markdown 转 PDF,选择文件和纸张大小(A4 或 Letter)。转换在浏览器内完成,两种输出适合不同的阅读需求。
- 生成图片型 PDF 会按行间位置分页,下载的 PDF 每页都是一张图,无法选取文字。
- 打印为 PDF(文字可选取) 会打开浏览器的打印对话框。在这里保存为 PDF,读者就能选中并复制段落。
三种方式怎么选?
| 对比项 | Markdown PDF | Markdown Preview Enhanced | ConverterTo |
|---|---|---|---|
| 准备工作 | 扩展和 Chromium 内核浏览器 | 扩展和 Chrome | 在浏览器中打开工具 |
| 能否选取文字 | 通常可以 | 通常可以 | 打印为 PDF 时可以 |
| 自定义 CSS | markdown-pdf.styles | 可调整预览样式 | 使用内置样式 |
| 准备好后能否离线使用 | 素材在本地时通常可以 | 素材在本地时通常可以 | 加载工具和远程图片需要联网 |
| 图片相对路径 | 本地有对应文件时通常可用 | 本地有对应文件时通常可用 | 图片需用绝对 URL |
| 适用场景 | 多份文件沿用同一套导出设置 | 边写边预览,再从预览导出 | 临时转一份 PDF |
常见问题排查
- 代理拦住 Chromium 下载。 设置 VS Code 的
http.proxy,或用markdown-pdf.executablePath指向已安装的浏览器。 - 图片没有显示。 如果写的是
images/chart.png,从 Markdown 所在文件夹检查路径。浏览器工具只读到所选文件,无法按相对路径找到旁边的图片,请改用绝对 URL。远程图片直接从图片主机加载,对方可以看到你的 IP 地址。 - 中日韩文字变成方框。 检查导出所用的电脑是否安装了包含这些字的字体。
- 希望某一节另起一页。 使用 Markdown PDF 时,在该节标题前单独写一行
<div class="page"></div>。
常见问答
保存时能自动导出吗? 使用 Markdown PDF 时,启用 markdown-pdf.convertOnSave 后需要重启 VS Code。使用 Markdown Preview Enhanced 时,在文件开头的 YAML 中添加顶层配置 export_on_save: { puppeteer: true }。
要发布网页或把文档交给别人编辑呢? 用 Markdown 转 HTML 生成网页,或用 Markdown 转 Word 生成可编辑文档。