昨天一个朋友跟我吐槽Markdown 笔记整理得清清楚楚想转成 PDF 发给客户结果折腾到大半夜——直接打印版式全乱浏览器打开后导出表格右边直接缺了一块图片更是只显示路径名。说实话Markdown 转 PDF 这操作听起来“有手就行”但想要一份排版干净、能直接拿出去交付的 PDF里面坑真的不少。这篇文章我把自己折腾几年积累下来的经验整理了 3 种最实用的方案分别对应单文件快速导出、批量自动化生产、日常写作顺手导出这三类需求。每种的工具选型、用法要点、常见坑都会讲到你可以直接照着选、照着做。1. 别急着装工具先想清楚你要的 PDF 是什么形态很多人一上来就搜“Markdown 转 PDF 工具推荐”然后装了一堆插件导出一份丑到没法看的文件又换下一个。问题往往不在工具而在没有先想清楚需求。1.1 先判断你的 PDF 是“能看就行”还是“要能交付”我遇到过三种典型需求处理方式完全不同给自己看的草稿内容完整、能搜索、能打印就行格式丑点无所谓。发给同事/客户的正式文档需要标题层级清晰、代码有高亮、表格完整、有页码最好还能带个目录。批量生成的报告/文档集比如每周把一批 Markdown 周报统一转成 PDF 归档手动一个个导出不现实。先说“心里有数”后面选方案才不会跑偏。如果你只是自己存档用编辑器自带导出就行如果要给别人看就得在样式上多花点功夫如果数量一大必须上命令行脚本。1.2 三个问题问完方案基本就出来了我会在脑子里过这三个问题频率多高一年导出一两次还是每天都要用对排版的要求到什么程度能不能接受默认样式还是必须和公司 PPT 风格统一文档里有没有特殊内容长表格、长代码块、数学公式、本地图片这些往往是翻车的重灾区。这三个问题的答案基本决定了你该用 VSCode 插件、Pandoc 命令行还是 Typora。下面逐一展开。2. 方法一VSCode 插件方案五分钟搞定单文件导出如果你平时就用 VSCode 写 Markdown这个方法是最顺手的。它解决的是“单份文档、快速导出、样式基本能看”的场景几乎零学习成本。2.1 Markdown PDF右键直接导出零配置入门的默认选择你需要在扩展市场搜Markdown PDF扩展 ID 是yzane.markdown-pdf装好后打开任意.md文件右键选“Markdown PDF: Export (pdf)”一个 PDF 就生成了。它的原理是调用本机的 Chromium 内核做页面渲染所以对 CSS 的支持很好。我实测下来代码高亮、标题层级、引用块这些常见元素都能识别中文只要系统里有中文字体就不会乱码。几个值得调整的配置项markdown-pdf.type: [pdf], markdown-pdf.outputDirectory: , markdown-pdf.header-template: div style\font-size: 9px; text-align: center;\span class\title\/span/div, markdown-pdf.footer-template: div style\font-size: 9px; text-align: center;\span class\pageNumber\/span / span class\totalPages\/span/divheader-template和footer-template可以设置页眉页脚比如在每页底部显示“第几页 / 共几页”。我一般都会把页码加上不然多页文档打印出来乱成一堆。outputDirectory默认是空意思是生成在 Markdown 文件同目录下如果你不想源文件和 PDF 混在一起就填个相对路径。这个方法最适合什么时候用你只需要把一份临时笔记导出来发给别人排版别太寒酸就行。我经常用它处理那种“突然被要一份说明文档”的紧急需求一分钟出活。2.2 Markdown Preview Enhanced适合对排版有要求的进阶用户另一个 VSCode 插件叫Markdown Preview Enhanced简称 MPE在 Markdown 生态里口碑很好。它的能力比“右键导出”强不少尤其适合你对 PDF 排版有更高要求的场景。使用流程是装好 MPE 后按CtrlShiftVMac 是CmdShiftV打开预览。在预览页面右键选择“Chrome (Puppeteer) - PDF”。如果要自动导出还可以在 Markdown 文件开头加一段 YAML Front Matter--- title: 我的文档标题 author: 作者名 date: 2024-06-01 ---导出时这些信息会渲染到文档顶部形成一个类似论文封面的头部。这比起单纯正文直接压进 PDF 要正式得多。MPE 还支持自定义 CSS 文件和文档内分页控制比如在需要新起一页的位置加上一条!-- pagebreak --注释。这在排版长文档时非常管用比如每个大章节单独一页而不用手动调节空白。2.3 插件方案的边界在哪插件的短板也很明显本质上是“单文件”操作。虽然有.pdf批量导出的命令但日常用下来还是一个个处理。样式定制有上限。你想做一套带封面、页眉页脚、特定字体字号的完整版式插件能实现但过程比较费劲。依赖编辑器环境。换台机器没装插件就回到原点。所以我的经验是插件方案适合“中轻度的即时导出”但不适合做成团队统一规范或自动化流水线。3. 方法二Pandoc 命令行方案批量生产与自动化交付的正解如果你要处理多份文档甚至希望每次写完自动生成 PDF那一定绕不开Pandoc。它是文档转换里的“瑞士军刀”可以读 Markdown、HTML、LaTeX、docx 等格式转换成 PDF、docx、HTML 等等。3.1 环境准备Pandoc 加一个 PDF 引擎Pandoc 本身不直接产出 PDF它需要调用一个 PDF 引擎。常见两种wkhtmltopdf基于 WebKit 渲染对 HTML/CSS 支持好中文没什么毛病上手容易。xelatexTeX Live 的一部分排版质量天花板尤其适合学术文档和数学公式但配置门槛高一些。安装上我用过的命令如下供参考# macOS 或者 Linux用包管理器 brew install pandoc wkhtmltopdf # 如果走 LaTeX 路线 brew install --cask basictex # Debian / Ubuntu sudo apt install pandoc wkhtmltopdf texlive-xetexWindows 上用 winget 也是同样思路winget install pandoc winget install wkhtmltopdf初学阶段我的建议是只要装 Pandoc wkhtmltopdf 就够用了。LaTeX 那条线等遇到数学公式需求再说不然光安装包的时间就够劝退。3.2 从一行命令到一套模板Pandoc 的基本玩法核心命令非常朴素pandoc input.md -o output.pdf --pdf-enginewkhtmltopdf一行命令就能出 PDF但它默认样式很“素”页面边距也比较大。想控制输出再往下加参数pandoc input.md -o output.pdf \ --pdf-enginewkhtmltopdf \ --toc \ -V margin-top2cm \ -V margin-bottom2cm \ --csscustom.css--toc会在开头自动生成目录多页文档就有了导航。-V margin-top2cm控制页边距wkhtmltopdf 引擎会识别这些变量。--csscustom.css传入自定义样式表这是 Pandoc 方案灵活性的核心。如果你要频繁生成固定样式的 PDF可以把这些参数写成一个 shell 脚本甚至做一个简单的 Makefile# build.sh #!/bin/bash for f in docs/*.md; do pandoc $f -o out/${f%.md}.pdf \ --pdf-enginewkhtmltopdf \ --toc \ -V margin-top2cm \ --cssassets/print.css done跑一次整个目录的 Markdown 全部转成 PDF。配合文件命名规则归档和分发都非常好使。3.3 批量和自动化进 CI/CD 也不成问题Pandoc 是命令行工具意味着它可以挂在各种自动化流程里。比如我做过一个内部文档站提交 Markdown 后自动构建同时把最新版本导出成 PDF 上传到附件目录。这个需求用 Pandoc 实现基本是半小时以内的事。在 GitHub Actions 里甚至可以加一步- name: Build PDFs run: | pandoc README.md -o README.pdf --pdf-enginewkhtmltopdf只要环境和依赖在 runner 上装好就能自动出 PDF。3.4 为什么说 Pandoc 上限最高、坑也最多Pandoc 的能力强但配置链路长你可能会遇到不少问题wkhtmltopdf 在 Linux 上可能缺字体特别是中文。解决办法是装中文字体包sudo apt install fonts-noto-cjkLaTeX 引擎需要额外指定 CJK 字体否则中文会变豆腐块pandoc input.md -o output.pdf --pdf-enginexelatex \ -V CJKmainfontNoto Serif CJK SC表格和代码块的样式在默认模板下不够好看需要 CSS 慢慢调。但话说回来一旦你把环境和模板都调顺后面就是一键的事。这也是为什么我至今仍在批量文档场景里首选 Pandoc它值得投入前期成本。4. 方法三Typora 直接导出日常写作顺手 PDF 的最优解第三种方案要给 Typora 一个位置。它的核心竞争力就一句话所见即所得。你在编辑区看到的样子基本就是 PDF 导出的样子。4.1 Typora 怎么导出 PDF 以及效果如何操作路径非常短打开一个 Markdown 文件点菜单栏“文件 - 导出 - PDF”。Typora 本质是一个沉浸式的写作工具写的时候就会实时渲染标题层级、加粗、表格、代码块。默认主题有好几套比如 GitHub、Pisum、Newsprint 等每个主题的字体、间距、代码配色都不同。主题即样式选一个顺眼的再导出PDF 就能直接看。如果默认主题不够贴合需求Typora 也支持自定义 CSS 主题。你可以写一套公司主题放在主题目录下导出时切换即可。4.2 适合谁、不适合谁Typora 适合的是日常记录型创作者笔记、周报、博客草稿想要一份干净 PDF 随时发给别人。重视编辑体验的人不想边写边因为预览渲染而分心。不追求复杂自动化一次性导出少量文件。不适合的是批量生产。你不可能开几十个文件逐个点导出。团队级统一模板。它的主题体系相对独立跨机器共享比较麻烦。需要复杂页眉页脚、页面布局的场景。它不像 Pandoc 那样能通过参数一股脑控制所有层。另外提醒一句Typora 现在是付费软件有 15 天免费试用之后需要购买授权。如果你已经在用自然没话讲如果还没入坑也可以先用 VSCode 插件方案替代功能上并不差太多。4.3 我对 Typora 的定位我个人现在把 Typora 当成“轻量交付”工具。比如写完一篇内部技术方案想在系统里归档一份 PDF或者给别人发一份带格式的注意事项用 Typora 导出是最高效的。它的价值在“顺手”而不是“强大”。所以如果你需要一个日常写写改改、导出 PDF 基本不用调的方案Typora 值得入。5. 三种方案放在一起比一比再对号入座前面讲了每个方案的使用路径现在直接上对比表维度VSCode 插件Markdown PDF / MPEPandoc wkhtmltopdf/xelatexTypora 导出学习成本低中高极低定制化能力中高中中文支持好好需按环境配置好批量处理弱强弱自动化接入一般强弱费用免费免费付费适用场景单文件快速导出批量/自动/重排版日常写作顺手交付针对几个典型需求我的推荐逻辑是临时给客户发一份带格式的说明优先 VSCode 插件一分钟搞定不用打开第二款软件。每周/每月批量生成周报、日报 PDF直接上 Pandoc shell 脚本一次配置长时间受益。写博客/笔记时想顺手留一份 PDFTypora 的导出体验最顺滑主题也最优雅。需要数学公式排版别犹豫选 xelatex 引擎的 Pandoc其他方案导出的公式质量很难达标。说实话这三者不是互斥关系。我自己电脑上就同时装着 Pandoc 和 VSCode 插件Typora 偶尔用来做快速预览。根据当天任务的性质选择不同的出口这才是最能提高效率的方式。6. 避坑实录图片路径、表格超宽、长代码换行、中文与页边距最后把最常见的坑集中梳理一遍。这些坑和具体方案无关是 Markdown 转 PDF 的“通用雷区”建议收藏备用。6.1 图片路径是最容易翻车的点Markdown 里插图用的是相对路径比如。这在编辑器预览里没问题但转 PDF 时如果当前工作目录或者资源路径没对上图片就会消失或者只显示路径名。几个实操建议规范文件目录图片放在assets/或images/下路径保持相对路径。文件名尽量别带空格和中文如果你控制不了文件名至少把文件夹理顺。Typora 里可以在“偏好设置 - 图像”里设置“复制图片到指定路径”粘贴进来的图片会自动存到统一目录避免路径混乱。用 Pandoc 时如果图片常用引用比如目录下有多个子目录可以用--resource-pathassets指定默认资源目录。一句话图片路径问题在写作初期就规范好比后期补救省心一百倍。6.2 表格宽度超限会直接“缺胳膊少腿”这是最容易被忽略的坑。Markdown 表格天生适合窄表一旦字段多了、内容长了PDF 里就会出现右侧被裁掉、文字被截断的惨状。我有一次把一张 9 列的接口配置表放进文档用默认样式导出后右边三列完全消失。排查了半天才发现问题不在工具而在于表格本身太宽。应对办法能不写成表格就别写。字段多、内容长的时候改用小节标题 列表描述阅读体验往往更好。拆表。把一个大表拆成多个小表每个表聚焦一个主题。自定义 CSS 缩小字号和 padding。比如设置table { font-size: 12px; } td { padding: 4px 6px; }。实在不行把表格截图成图片插入。这背后的逻辑是PDF 是固定页面宽度而 Markdown 表格不会自动缩小字号去适应页面。所以最可靠的方案是“设计上就别让它超宽”而不是指望工具自动处理。6.3 长代码行不换行PDF 里根本没法看代码块里长度超过一行的代码在部分 PDF 渲染方案里会被直接截断或者挤到页面外。特别是一些长 URL、长命令、日志输出。我的经验是提前在 CSS 里加上换行处理pre { white-space: pre-wrap; word-wrap: break-word; }如果是 Pandoc 走 xelatex 引擎可以在文档元数据里设置代码块相关的包参数让长行自动断行。只要预先想好这个问题是最容易规避的。另外我会在写作阶段就养成习惯超过一定长度的代码行主动拆分。这不仅是 PDF 导出的问题也是代码可读性的问题。把复杂命令用\换行写成多行谁看谁谢你。6.4 中文显示、页边距和页眉页脚的联动问题中文乱码在 VSCode 插件和 Typora 里基本不会出现但在 Pandoc LaTeX 路线里要求你配置中文字体pandoc input.md -o output.pdf --pdf-enginexelatex \ -V CJKmainfontNoto Serif CJK SC如果没有装字体先装。wkhtmltopdf 路线下则只需保证系统有中文字体比如 Linux 服务器上执行sudo apt install fonts-noto-cjk页边距和页眉页脚方面我的实践是用 VSCode 插件时页眉页脚在扩展设置里配置header-template、footer-template。用 Pandoc wkhtmltopdf 时通过-V margin-top这类变量控制页边距。用 Typora 时在“偏好设置 - 导出 - PDF”里可以调整边距和是否包含页码。这里想多提醒一句页边距不要为了省纸调到太小。一边是 1.5cm 是底线再小打印出来很难看装订起来更痛苦。设置边距之前先想清楚你的 PDF 会被打印、装订还是只做电子阅读场景不同最优边距也不同。6.5 一个容易被忽略的“软性”坑写作阶段就要考虑输出效果很多人是在 Markdown 写完之后才开始想“怎么转 PDF”这其实有点晚了。我的习惯是开写之前先想清楚最终输出形态这份文档最终是电子阅读还是打印需不需要目录如果需要标题就得层级分明。表格多不多多的话写之前就控制列数。有没有大图大图在 PDF 里会被缩放还是需要特殊排版这些在写作阶段先想清楚后期转换几乎不用返工。如果全部写完才来调样式那不管用哪个方案都得花不少冤枉时间。我最终的选择逻辑三种方案我都实际用过长期跑下来我的选择逻辑很简单临时交付用 VSCode 插件批量生产用 Pandoc日常写作顺手导出则用 Typora。它们各有擅长综合下来并不存在“一款工具通吃所有场景”的银弹。如果你现在正对着一个 Markdown 文件发愁我建议直接照这个思路选文件少、时间紧就装 Markdown PDF 插件如果是高频的重复劳动花半天把 Pandoc 环境和脚本配好后面一劳永逸。折腾过一轮之后你也会发现工具之间的差距并没有那么大真正决定 PDF 质量的是你对内容结构、表格宽度、图片路径这些细节的管理习惯。