企业官网建设流程全解析

昨天一个朋友跟我吐槽：Markdown 笔记整理得清清楚楚，想转成 PDF 发给客户，结果折腾到大半夜——直接打印版式全乱，浏览器打开后导出，表格右边直接缺了一块，图片更是只显示路径名。说实话，Markdown 转 PDF 这操作听起来“有手就行”，但想要一份排版干净、能直接拿出去交付的 PDF，里面坑真的不少。这篇文章我把自己折腾几年积累下来的经验整理了 3 种最实用的方案，分别对应单文件快速导出、批量自动化生产、日常写作顺手导出这三类需求。每种的工具选型、用法要点、常见坑都会讲到，你可以直接照着选、照着做。

1. 别急着装工具，先想清楚你要的 PDF 是什么形态

很多人一上来就搜“Markdown 转 PDF 工具推荐”，然后装了一堆插件，导出一份丑到没法看的文件，又换下一个。问题往往不在工具，而在没有先想清楚需求。

1.1 先判断你的 PDF 是“能看就行”还是“要能交付”

我遇到过三种典型需求，处理方式完全不同：

• 给自己看的草稿：内容完整、能搜索、能打印就行，格式丑点无所谓。
• 发给同事/客户的正式文档：需要标题层级清晰、代码有高亮、表格完整、有页码，最好还能带个目录。
• 批量生成的报告/文档集：比如每周把一批 Markdown 周报统一转成 PDF 归档，手动一个个导出不现实。

先说“心里有数”，后面选方案才不会跑偏。如果你只是自己存档，用编辑器自带导出就行；如果要给别人看，就得在样式上多花点功夫；如果数量一大，必须上命令行脚本。

1.2 三个问题问完，方案基本就出来了

我会在脑子里过这三个问题：

1. 频率多高？一年导出一两次，还是每天都要用？
2. 对排版的要求到什么程度？能不能接受默认样式，还是必须和公司 PPT 风格统一？
3. 文档里有没有特殊内容？长表格、长代码块、数学公式、本地图片，这些往往是翻车的重灾区。

这三个问题的答案，基本决定了你该用 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></div>"

• header-template和footer-template可以设置页眉页脚，比如在每页底部显示“第几页 / 共几页”。我一般都会把页码加上，不然多页文档打印出来乱成一堆。
• outputDirectory默认是空，意思是生成在 Markdown 文件同目录下，如果你不想源文件和 PDF 混在一起，就填个相对路径。

这个方法最适合什么时候用？你只需要把一份临时笔记导出来发给别人，排版别太寒酸就行。我经常用它处理那种“突然被要一份说明文档”的紧急需求，一分钟出活。

2.2 Markdown Preview Enhanced：适合对排版有要求的进阶用户

另一个 VSCode 插件叫Markdown Preview Enhanced（简称 MPE），在 Markdown 生态里口碑很好。它的能力比“右键导出”强不少，尤其适合你对 PDF 排版有更高要求的场景。

使用流程是：

1. 装好 MPE 后，按Ctrl+Shift+V（Mac 是Cmd+Shift+V）打开预览。
2. 在预览页面右键，选择“Chrome (Puppeteer) -> PDF”。
3. 如果要自动导出，还可以在 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 支持好，中文没什么毛病，上手容易。
• xelatex（TeX Live 的一部分）：排版质量天花板，尤其适合学术文档和数学公式，但配置门槛高一些。

安装上，我用过的命令如下，供参考：

# macOS 或者 Linux（用包管理器） brew install pandoc wkhtmltopdf # 如果走 LaTeX 路线 brew install --cask basictex # Debian / Ubuntu sudo apt install pandoc wkhtmltopdf texlive-xetex

Windows 上用 winget 也是同样思路：

winget install pandoc winget install wkhtmltopdf

初学阶段，我的建议是只要装 Pandoc + wkhtmltopdf 就够用了。LaTeX 那条线等遇到数学公式需求再说，不然光安装包的时间就够劝退。

3.2 从一行命令到一套模板：Pandoc 的基本玩法

核心命令非常朴素：

pandoc input.md -o output.pdf --pdf-engine=wkhtmltopdf

一行命令就能出 PDF，但它默认样式很“素”，页面边距也比较大。想控制输出，再往下加参数：

pandoc input.md -o output.pdf \ --pdf-engine=wkhtmltopdf \ --toc \ -V margin-top=2cm \ -V margin-bottom=2cm \ --css=custom.css

• --toc会在开头自动生成目录，多页文档就有了导航。
• -V margin-top=2cm控制页边距，wkhtmltopdf 引擎会识别这些变量。
• --css=custom.css传入自定义样式表，这是 Pandoc 方案灵活性的核心。

如果你要频繁生成固定样式的 PDF，可以把这些参数写成一个 shell 脚本，甚至做一个简单的 Makefile：

# build.sh #!/bin/bash for f in docs/*.md; do pandoc "$f" -o "out/${f%.md}.pdf" \ --pdf-engine=wkhtmltopdf \ --toc \ -V margin-top=2cm \ --css=assets/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-engine=wkhtmltopdf

只要环境和依赖在 runner 上装好，就能自动出 PDF。

3.4 为什么说 Pandoc 上限最高、坑也最多

Pandoc 的能力强，但配置链路长，你可能会遇到不少问题：

• wkhtmltopdf 在 Linux 上可能缺字体，特别是中文。解决办法是装中文字体包：

  sudo apt install fonts-noto-cjk

• LaTeX 引擎需要额外指定 CJK 字体，否则中文会变豆腐块：

  pandoc input.md -o output.pdf --pdf-engine=xelatex \ -V CJKmainfont="Noto 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 插件，一分钟搞定，不用打开第二款软件。
• 每周/每月批量生成周报、日报 PDF：直接上 Pandoc + shell 脚本，一次配置，长时间受益。
• 写博客/笔记时想顺手留一份 PDF：Typora 的导出体验最顺滑，主题也最优雅。
• 需要数学公式排版：别犹豫，选 xelatex 引擎的 Pandoc，其他方案导出的公式质量很难达标。

说实话，这三者不是互斥关系。我自己电脑上就同时装着 Pandoc 和 VSCode 插件，Typora 偶尔用来做快速预览。根据当天任务的性质，选择不同的出口，这才是最能提高效率的方式。

6. 避坑实录：图片路径、表格超宽、长代码换行、中文与页边距

最后把最常见的坑集中梳理一遍。这些坑和具体方案无关，是 Markdown 转 PDF 的“通用雷区”，建议收藏备用。

6.1 图片路径是最容易翻车的点

Markdown 里插图用的是相对路径，比如![](./images/foo.png)。这在编辑器预览里没问题，但转 PDF 时如果当前工作目录或者资源路径没对上，图片就会消失或者只显示路径名。

几个实操建议：

• 规范文件目录，图片放在assets/或images/下，路径保持相对路径。
• 文件名尽量别带空格和中文，如果你控制不了文件名，至少把文件夹理顺。
• Typora 里可以在“偏好设置 -> 图像”里设置“复制图片到指定路径”，粘贴进来的图片会自动存到统一目录，避免路径混乱。
• 用 Pandoc 时，如果图片常用引用，比如目录下有多个子目录，可以用--resource-path=assets指定默认资源目录。

一句话：图片路径问题，在写作初期就规范好，比后期补救省心一百倍。

6.2 表格宽度超限会直接“缺胳膊少腿”

这是最容易被忽略的坑。Markdown 表格天生适合窄表，一旦字段多了、内容长了，PDF 里就会出现右侧被裁掉、文字被截断的惨状。

我有一次把一张 9 列的接口配置表放进文档，用默认样式导出后，右边三列完全消失。排查了半天才发现问题不在工具，而在于表格本身太宽。

应对办法：

1. 能不写成表格就别写。字段多、内容长的时候，改用小节标题 + 列表描述，阅读体验往往更好。
2. 拆表。把一个大表拆成多个小表，每个表聚焦一个主题。
3. 自定义 CSS 缩小字号和 padding。比如设置table { font-size: 12px; } td { padding: 4px 6px; }。
4. 实在不行，把表格截图成图片插入。

这背后的逻辑是：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-engine=xelatex \ -V CJKmainfont="Noto 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 质量的是你对内容结构、表格宽度、图片路径这些细节的管理习惯。