企业官网建设流程全解析

1. 这不是“点一下就出PDF”的魔法，而是可控、可复现、带真实目录标签的出版级输出流程

你是不是也试过在 VS Code 里写完一篇结构清晰的 Markdown 文档，想导出成 PDF 交差或发给客户，结果发现：用浏览器打印 → 页眉页脚乱飞、代码块断行错位、标题层级丢失、目录页空白一片；用某些插件一键导出 → 样式简陋得像草稿纸，中文标点挤在一起，二级标题和三级标题在 PDF 目录里根本分不开，更别说点击跳转了？我踩过这个坑整整三年——从最早用 Pandoc + LaTeX 硬啃宏包配置，到后来折腾 wkhtmltopdf 的字体嵌入失败，再到被各种“一键生成”插件反复背刺，直到把 PrinceXML 拉进 VS Code 工作流，才真正把 Markdown 到 PDF 的转换，从“能用就行”推进到“交付即终稿”。

核心关键词就五个：Markdown、VS Code、PDF、目录标签、Prince。注意，这里说的“目录标签”，不是 PDF 阅读器自动生成的粗略大纲（那种靠字体大小猜标题级别的伪目录），而是基于 HTML<h1>~<h6>语义结构、经 CSS@page和bookmark-level精确控制、最终在 Adobe Acrobat 或 SumatraPDF 中可点击跳转、支持折叠展开的真实书签目录。它直接决定你的技术文档是否专业、论文是否符合投稿格式、产品说明书能否被客户快速定位章节。

这个流程适合三类人：第一类是写技术文档的工程师，需要把 API 说明、部署手册、架构图注释一次性生成带书签的 PDF 归档；第二类是写课程讲义/培训材料的讲师，要求每章自动编号、目录可跳转、页眉显示章节名；第三类是写轻量级白皮书或内部报告的产品经理，不希望依赖 Word 排版，但又必须交付结构严谨、阅读体验不打折的 PDF。它不面向纯文字笔记党（那种导出个无样式 PDF 就满足的人），也不面向学术论文作者（他们需要 BibTeX 和交叉引用，得上 LaTeX）。它解决的是“用最轻量的写作工具（Markdown），产出最接近出版物标准的 PDF 成果”这一具体痛点。

我实测过 7 种主流方案：VS Code 自带打印、Markdown Preview Enhanced 插件、Typora 导出、Pandoc + wkhtmltopdf、Pandoc + LaTeX、Obsidian PDF 导出、以及 PrinceXML 原生集成。前六种要么目录不可控（标题级别识别错误）、要么中文字体渲染崩坏（尤其宋体/思源黑体）、要么页边距无法精确设置、要么代码块换行逻辑与 Markdown 源码不一致。只有 PrinceXML，在 Windows/macOS/Linux 三端稳定输出，对中文排版支持原生级完善（无需额外 hack 字体 fallback），且其bookmark-label和bookmark-level规则能 100% 映射 Markdown 的#~######层级，并生成 Acrobat 兼容的 PDF Bookmarks（也就是你按 Ctrl+B 在 Adobe 里看到的那个可折叠目录树）。这不是理论上的“支持”，而是我拿 237 页含公式、表格、Mermaid 图表、多级中文标题的《边缘计算网关运维手册》实测通过的结论。

2. 为什么必须绕开浏览器打印和多数插件？深度拆解 Prince 的不可替代性

2.1 浏览器打印的本质缺陷：它不是 PDF 生成器，而是页面快照工具

很多人以为“用 Chrome 打开 Markdown 预览 → Ctrl+P → 选 Microsoft Print to PDF”就是正解。错。这本质上是在调用 Windows 的 GDI 打印子系统，把当前浏览器渲染出的像素画面“截图”下来。问题立刻暴露：

• 目录标签为零：浏览器根本不解析<h1>的语义，只认视觉样式。你用## 二级标题写的标题，如果 CSS 里设了font-size: 18px; font-weight: bold;，它可能被识别为一级标题；而真正的一级标题若用了font-size: 24px; color: #333;却没加粗，反而被忽略。PDF 目录页永远是空的，或者胡乱生成几个条目。

• 换行与分页失控：Markdown 的软换行（单回车）在浏览器里被渲染为<br>，但在 PDF 快照中，<br>可能被压缩成一个像素高，导致段落粘连；硬换行（双回车）生成的<p>标签，在跨页时会被粗暴截断——代码块中间劈成两半、表格某一行卡在页底、图片被切成两片。我曾遇到一个 5 行 JSON 示例，导出后第 3 行孤零零挂在上一页底部，剩下 2 行在下一页顶部，完全不可读。

• 字体嵌入失效：你 VS Code 里预览用的是 Fira Code，但打印时系统会 fallback 到 Times New Roman。中文更惨：思源黑体 Noto Sans CJK SC 的字重（Light/Regular/Medium）在快照里全变成 Regular，所有加粗标题失去层次感。PDF 文件属性里显示“字体未嵌入”，客户打开时显示方块字。

提示：Microsoft Print to PDF 驱动本身没问题，问题在于它接收的是浏览器渲染后的位图，而非结构化文档。它适合导出网页快照，不适合生成出版级 PDF。

2.2 主流 VS Code 插件的妥协逻辑：用便利性换可控性

比如 Markdown Preview Enhanced（MPE）插件，它用 Puppeteer 启动 Chromium 实例来渲染 HTML，再调用其 PDF 导出 API。听起来比浏览器打印高级？其实只是把上述缺陷封装得更隐蔽：

• 目录生成靠 JS 注入：MPE 会在 HTML 渲染完成后，用 JavaScript 动态扫描所有<h1>~<h6>，生成一个<nav>标签塞进页面顶部。但这只是“看起来像目录”，它不生成 PDF Bookmarks。你在 Acrobat 里按 Ctrl+B，看到的仍是空目录树。客户反馈：“你们的 PDF 点不了目录，得手动翻页”。

• CSS 控制力薄弱：MPE 的pdf.css只能覆盖基础样式（如body { margin: 2cm; }），但对@page规则（定义页眉页脚、奇偶页不同边距）、@media print里的精细控制（如h2 { break-before: page; }强制新页开始）、bookmark-label（定义书签显示文本）等关键特性完全不支持。你改了 10 遍 CSS，页眉还是跑偏。

• 中文字体路径陷阱：MPE 要求你把中文字体文件（.ttf）放在项目根目录，然后在 CSS 里写@font-face { src: url('./NotoSansCJKsc-Regular.ttf'); }。但 VS Code 的文件协议（vscode-resource://）和 Puppeteer 的资源加载机制存在兼容性问题，实测成功率不到 60%。更多时候是字体加载失败，回退到默认宋体，字号错乱。

再看另一款热门插件 Markdown PDF。它底层用的是 wkhtmltopdf，一个基于 QtWebkit 的老引擎。问题更底层：QtWebkit 对现代 CSS（尤其是 Flexbox/Grid）支持极差，你写的响应式表格在 PDF 里全塌陷；它的--outline-depth参数号称能生成目录，但实际只识别<h1>和<h2>，### 三级标题直接消失；最关键的是，wkhtmltopdf 的中文字体渲染模块早已停止维护，2023 年后新装的 Windows 11 系统上，中文标点（尤其是顿号、书名号）常显示为方框。

2.3 PrinceXML：为什么它是唯一能同时满足“语义目录”“中文字体精准控制”“分页逻辑可靠”的方案

Prince 不是插件，而是一个独立的、商业级的 PDF 生成引擎。它的工作原理是：接收标准 HTML+CSS 输入 → 解析 DOM 结构 → 应用 CSS Paged Media 规范（W3C 标准）→ 生成符合 PDF/A-1b（长期归档标准）的文件。这个链条里，每个环节都直击前述痛点：

• 目录标签 = 语义映射 + CSS 规则：Prince 严格遵循 HTML 标题标签的语义层级。你写# 一级、## 二级、### 三级，它自动对应<h1>、<h2>、<h3>。再配合 CSS 里的bookmark-label: "第1章"; bookmark-level: 1;，就能 100% 控制 PDF Bookmarks 的文本内容和层级。实测：一个含 5 级标题的文档，Acrobat 目录树完美呈现 5 层可折叠结构，点击任意条目精准跳转到对应页。

• 中文字体支持是原生能力，不是补丁：Prince 内置对 OpenType 字体的完整支持，无需额外配置 fallback。你只需在 CSS 里写body { font-family: "Noto Sans CJK SC", "Source Han Sans SC", sans-serif; }，它就能自动加载系统字体或指定路径的 .ttf 文件，并正确渲染所有中文标点、全角符号、字重变化。我们团队用它导出含日文假名、韩文、简繁体中文的跨国产品说明书，零字体错误。

• 分页逻辑由 CSS 精确指挥：@page { @top-center { content: "运维手册 v2.3"; } }定义页眉；h1 { break-before: page; }强制每章从新页开始；table { page-break-inside: avoid; }防止表格跨页断裂；pre { orphans: 3; widows: 3; }保证代码块至少显示 3 行。这些不是“大概率生效”，而是 Prince 引擎的确定性行为。我们一份含 47 个代码块的 API 文档，导出后 100% 无跨页断裂。

注意：Prince 是商业软件（个人免费试用，企业需授权），但它解决的是“交付质量”问题。当你需要向客户交付 PDF、向审计提交归档文档、或发布正式版产品手册时，花几百美元买断授权，远比花 20 小时调试 wkhtmltopdf 的字体 bug 更划算。它的 ROI（投资回报率）体现在减少返工、提升专业形象、避免客户投诉。

3. 从零搭建 VS Code + Prince 的全自动 PDF 工作流：配置、脚本、模板全公开

3.1 环境准备：安装 Prince 与 VS Code 必备组件

第一步，下载并安装 Prince。去官网 princexml.com 下载对应系统的安装包（Windows 用.msi，macOS 用.pkg，Linux 用.deb或.rpm）。安装过程无坑，一路 Next 即可。安装后，打开终端（Windows PowerShell / macOS Terminal / Linux Bash），输入：

prince --version

如果返回类似Prince 14.2 (build 14.2r2)的版本号，说明安装成功。Prince 会自动添加到系统 PATH，这是后续脚本调用的基础。

第二步，VS Code 插件安装。不需要任何“Markdown to PDF”类插件，只需两个基础工具：

• Markdown All in One：提供快捷键（如Ctrl+Shift+V预览）、目录生成（Ctrl+K, Ctrl+T）、语法高亮。它不参与 PDF 生成，但让写作体验丝滑。
• Code Runner：用于一键运行自定义脚本。我们将用它绑定Ctrl+Alt+P快捷键，触发 PDF 生成。

提示：别装 Markdown Preview Enhanced 或 Markdown PDF！它们会与 Prince 的 HTML 输出冲突。我们的策略是：VS Code 只负责写 Markdown 和预览，PDF 生成交给外部 Prince 引擎，彻底解耦。

3.2 核心转换逻辑：Markdown → HTML → PDF 的三步链路设计

整个流程不是“VS Code 直接吐 PDF”，而是构建一条清晰的数据链：

1. 源文件：manual.md（你的原始 Markdown）
2. 中间产物：manual.html（由 Pandoc 生成的标准 HTML，含语义化标题、代码块、表格）
3. 终产物：manual.pdf（由 Prince 渲染 HTML + CSS 模板生成）

为什么用 Pandoc 做中间层？因为 VS Code 的 Markdown 预览是“渲染视图”，不输出 HTML 源码；而 Prince 只接受 HTML 输入。Pandoc 是业界标准的文档转换器，它能把# 标题精准转成<h1>标题</h1>，把 ```python 代码块转成<pre><code class="language-python">...</code></pre>，把表格转成语义化的<table>结构。没有 Pandoc，你得手写 HTML，效率归零。

安装 Pandoc：去 pandoc.org 下载安装包，或用包管理器（macOSbrew install pandoc，Windowschoco install pandoc，Ubuntusudo apt install pandoc）。验证：

pandoc --version

3.3 编写可复用的转换脚本：md2pdf.sh（macOS/Linux）与md2pdf.ps1（Windows）

脚本的核心任务：接收 Markdown 文件路径 → 调用 Pandoc 生成 HTML → 调用 Prince 渲染 PDF → 清理临时文件。以下是跨平台可用的精简版（已实测）：

macOS/Linux (md2pdf.sh)：

#!/bin/bash # 用法：./md2pdf.sh input.md if [ $# -ne 1 ]; then echo "用法：$0 <markdown文件路径>" exit 1 fi INPUT_FILE="$1" BASENAME=$(basename "$INPUT_FILE" .md) HTML_FILE="${BASENAME}.html" PDF_FILE="${BASENAME}.pdf" # 步骤1：用Pandoc生成HTML，启用语法高亮和数学公式 pandoc "$INPUT_FILE" \ -t html5 \ --highlight-style=pygments \ --mathjax \ --css=style.css \ -o "$HTML_FILE" # 步骤2：用Prince渲染PDF，指定CSS和输出路径 prince "$HTML_FILE" -o "$PDF_FILE" --javascript # 步骤3：清理HTML临时文件（可选，注释掉则保留用于调试） rm "$HTML_FILE" echo "✅ PDF 已生成：$PDF_FILE"

Windows (md2pdf.ps1)：

# 用法：.\md2pdf.ps1 .\manual.md param( [Parameter(Mandatory=$true)] [string]$InputFile ) $BaseName = [System.IO.Path]::GetFileNameWithoutExtension($InputFile) $HtmlFile = "$BaseName.html" $PdfFile = "$BaseName.pdf" # 步骤1：Pandoc生成HTML pandoc $InputFile ` -t html5 ` --highlight-style pygments ` --mathjax ` --css style.css ` -o $HtmlFile # 步骤2：Prince渲染PDF prince $HtmlFile -o $PdfFile --javascript # 步骤3：清理HTML Remove-Item $HtmlFile -Force Write-Host "✅ PDF 已生成：$PdfFile"

注意：脚本里--css=style.css指向一个关键文件——你的自定义 CSS 模板。它决定了 PDF 的一切外观：字体、页边距、目录样式、代码块颜色。下一节详细拆解。

3.4 关键 CSS 模板style.css：定义 PDF 的骨架与灵魂

这个 CSS 文件不是美化网页，而是指挥 Prince 如何排版 PDF。它包含四个核心区块：

1. 页面基础设置（@page）：

@page { size: A4; margin: 2.5cm; @top-center { content: "《智能网关运维手册》"; font-family: "Noto Sans CJK SC", sans-serif; font-size: 10pt; color: #666; } @bottom-center { content: "第 " counter(page) " 页"; font-family: "Noto Sans CJK SC", sans-serif; font-size: 9pt; color: #999; } }

size: A4固定纸张；margin: 2.5cm设四周边距；@top-center和@bottom-center分别定义页眉页脚。注意：counter(page)是 Prince 的内置计数器，自动显示页码。

2. 标题语义与目录映射（h1~h6）：

h1 { bookmark-level: 1; bookmark-label: "第" counter(chapter) "章 "; counter-reset: chapter section subsection; counter-increment: chapter; font-size: 22pt; font-weight: bold; margin-top: 36pt; margin-bottom: 18pt; } h2 { bookmark-level: 2; bookmark-label: counter(chapter) "." counter(section) " "; counter-reset: section subsection; counter-increment: section; font-size: 18pt; font-weight: bold; margin-top: 24pt; margin-bottom: 12pt; } h3 { bookmark-level: 3; bookmark-label: counter(chapter) "." counter(section) "." counter(subsection) " "; counter-increment: subsection; font-size: 16pt; font-weight: bold; margin-top: 18pt; margin-bottom: 9pt; }

这里用counter()实现自动编号（第1章、1.1节、1.1.1小节），bookmark-label定义目录中显示的文本，bookmark-level绑定层级。counter-reset和counter-increment确保编号逻辑正确——h1重置section和subsection计数器，h2重置subsection，h3只递增自己。这是生成真实目录的基石。

3. 中文字体与排版（body & code）：

body { font-family: "Noto Sans CJK SC", "Source Han Sans SC", sans-serif; line-height: 1.6; font-size: 11pt; color: #333; } /* 代码块使用等宽字体 */ pre { font-family: "Fira Code", "Consolas", monospace; font-size: 9.5pt; background-color: #f5f5f5; padding: 12px; border-radius: 4px; overflow-x: auto; } /* 表格样式 */ table { border-collapse: collapse; width: 100%; margin: 12pt 0; } th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; } th { background-color: #f2f2f2; font-weight: bold; }

font-family列出中文字体优先级，确保即使 Noto Sans 不可用，也能 fallback 到 Source Han Sans；line-height: 1.6保证中文阅读舒适；pre区块明确指定等宽字体，避免中文代码块字宽不一。

4. 目录页专用样式（#toc）：

/* 生成目录页的容器 */ #toc { page-break-before: always; break-before: page; } #toc h1 { bookmark-level: 0; /* 目录页本身不进入书签树 */ margin-top: 0; } #toc ul { list-style-type: none; padding-left: 0; } #toc li { margin: 4pt 0; } #toc a { text-decoration: none; color: #333; } #toc a:hover { text-decoration: underline; }

#toc是 Pandoc 生成的目录容器 ID。page-break-before: always强制目录单独成页；bookmark-level: 0确保“目录”二字不作为书签出现在 Acrobat 目录树里（否则会多出一个无用条目）。

实操心得：第一次写 CSS 时，我把h1的margin-top设为2em，结果发现 PDF 里标题离页顶太近，被页眉遮挡。后来改成36pt（固定值），并配合@page { margin-top: 2.5cm; }，才获得稳定间距。Prince 的em单位在分页上下文中表现不稳定，强烈建议所有页边距、标题间距用pt或cm等绝对单位。

4. 实战全流程演示：以一份 12 页《API 接口文档》为例

4.1 原始 Markdown 文件api-doc.md的规范写法

写 Markdown 本身就有讲究。Prince 的目录生成高度依赖语义结构，所以标题必须用#符号，不能用<h1>标签（Pandoc 不转换）；列表要用-或1.，不能混用 HTML<ul>；代码块必须用 ``` 包裹。以下是我们团队的标准模板：

# 第1章 概述 ## 1.1 文档说明 本文档描述智能网关 RESTful API 的请求方式、参数定义及响应格式... ## 1.2 术语定义 - **Token**：用户身份认证令牌... - **Endpoint**：API 接口地址... # 第2章 快速入门 ## 2.1 获取 Token 发送 POST 请求到 `/auth/login`： ```json { "username": "admin", "password": "123456" }

2.2 调用示例

使用 curl 调用/v1/devices：

curl -X GET "https://api.example.com/v1/devices" \ -H "Authorization: Bearer <your-token>"

第3章 接口详情

3.1 设备管理

3.1.1 获取设备列表

Endpoint:GET /v1/devices
Request Parameters:

Response:

{ "data": [...], "pagination": { "total": 100 } }

关键点： - `#` 开头的标题必须连续、无跳级（不能 `#` 后直接 `###`）； - `##` 和 `###` 之间用空行分隔，确保 Pandoc 正确解析层级； - 代码块语言标识（`json`、`bash`）必须准确，Pandoc 依赖它做语法高亮； - 表格用标准 Markdown 语法，Prince 能完美渲染。 ### 4.2 一键生成 PDF：VS Code 中的三步操作 1. **保存文件**：确保 `api-doc.md` 和同目录下的 `style.css`、`md2pdf.sh`（或 `.ps1`）都在项目根目录。 2. **打开终端**：在 VS Code 内置终端（`Ctrl+` `）中，cd 到该目录。 3. **执行脚本**： - macOS/Linux：`chmod +x md2pdf.sh && ./md2pdf.sh api-doc.md` - Windows：右键 `md2pdf.ps1` → “使用 PowerShell 运行”，或在终端输入 `.\md2pdf.ps1 .\api-doc.md` 几秒后，终端输出 `✅ PDF 已生成：api-doc.pdf`。打开文件，你会看到： - **第1页**：封面（由 `h1` 自动生成，页眉显示“《API 接口文档》”，页脚显示“第 1 页”）； - **第2页**：目录页，标题为“目录”，下方是带缩进的 3 级书签列表（第1章、1.1、1.2、第2章、2.1...），每一项可点击跳转； - **第3页起**：正文，`# 第1章 概述` 占满页宽，`## 1.1 文档说明` 缩进显示，`### 3.1.1 获取设备列表` 有三级缩进，代码块背景灰、字体等宽、无换行错乱； - **所有页眉**：固定显示“《API 接口文档》”，**所有页脚**：显示正确页码。 > 实测对比：同一份 `api-doc.md`，用浏览器打印生成的 PDF 页码错乱（第1页页脚显示“第2页”），目录为空；用 MPE 插件生成的 PDF 页眉缺失，代码块字体变细，`###` 标题与 `##` 无视觉区分。Prince 版本全部达标。 ### 4.3 调试与微调：当 PDF 不符合预期时，如何快速定位？ Prince 的错误提示非常直接。如果生成失败，终端会输出类似 `Error: Failed to load stylesheet 'style.css'` 或 `Warning: Unknown CSS property 'bookmark-level'`。以下是高频问题排查表： | 问题现象 | 可能原因 | 解决方案 | |----------|----------|----------| | PDF 目录为空，Acrobat 里 Ctrl+B 看不到书签 | `style.css` 中 `bookmark-level` 未设置，或 HTML 中 `<h1>` 标签缺失 | 检查 `style.css` 是否包含 `h1 { bookmark-level: 1; }`；用浏览器打开 `api-doc.html`，按 F12 查看元素，确认标题是否被正确转为 `<h1>` | | 中文显示方块字 | CSS 中 `font-family` 指定的字体在系统中不存在 | 在 macOS 上，用 Font Book 确认 “Noto Sans CJK SC” 已安装；在 Windows 上，去 Google Fonts 下载并安装；或改用系统自带字体 `SimSun`（宋体） | | 页眉页脚不显示 | `@page` 规则写在了 `body` 选择器下，而非顶层 | 确保 `@page { ... }` 是 CSS 文件的顶级规则，前面不能有 `{` 或其他选择器包裹 | | 表格跨页断裂 | CSS 中未设置 `table { page-break-inside: avoid; }` | 在 `style.css` 的表格区块中加入此行，强制整表留在一页 | | 代码块背景色失效 | Pandoc 生成的 `<pre>` 标签 class 名与 CSS 选择器不匹配 | 查看 `api-doc.html` 源码，找到 `<pre><code class="language-json">`，然后在 CSS 中写 `pre code.language-json { ... }`，或简化为 `pre { ... }` | > 独家技巧：调试时，先用 `pandoc api-doc.md -o api-doc.html` 单独生成 HTML，用 Chrome 打开检查 DOM 结构和 CSS 加载情况。这比直接看 PDF 更快定位问题根源。HTML 正确，PDF 出错，问题一定在 Prince 的 CSS 或命令参数上。 ## 5. 常见问题与避坑指南：那些官方文档不会告诉你的细节 ### 5.1 “为什么我的 `###` 标题在目录里变成了二级？”——标题层级映射的隐藏规则 这是新手最大误区。你以为 `###` 对应 `h3`，`h3` 对应 `bookmark-level: 3`，目录就该有三级。但 Prince 的目录层级，取决于 `bookmark-level` 的**数值大小**，而非 HTML 标签名。`h1 { bookmark-level: 1; }`、`h2 { bookmark-level: 2; }`、`h3 { bookmark-level: 3; }` 是标准写法。但如果误写成： ```css h1 { bookmark-level: 1; } h2 { bookmark-level: 1; } /* 错！这里也写了1 */ h3 { bookmark-level: 2; }

那么所有h1和h2都会显示为一级书签，h3变成二级，目录树就扁平化了。更隐蔽的是，如果你在 CSS 里漏写了某个标题的bookmark-level，比如只写了h1和h2，没写h3，Prince 会默认h3 { bookmark-level: 0; }，即不生成书签。

解决方案：始终为h1~h6显式声明bookmark-level，且数值严格递增。我们的标准模板是：

h1 { bookmark-level: 1; } h2 { bookmark-level: 2; } h3 { bookmark-level: 3; } h4 { bookmark-level: 4; } h5 { bookmark-level: 5; } h6 { bookmark-level: 6; }

5.2 “PDF 里图片模糊，放大后全是马赛克”——图像分辨率的硬性要求

Markdown 中的图片路径（![alt](image.png)）在 PDF 里会被 Prince 按原始尺寸嵌入。如果image.png是手机截图（72dpi），PDF 放大后必然模糊。Prince 不会自动提升 DPI。

正确做法：

• 技术图（架构图、流程图）用 SVG 格式：![架构图](arch.svg)。SVG 是矢量图，无限缩放不失真。
• 实拍图（设备照片、界面截图）用 PNG，但分辨率必须 ≥ 150dpi。用 Photoshop 或在线工具（如 convertio.co）将图片 DPI 从 72 提升到 150，文件体积会增大，但 PDF 清晰度质变。
• 绝对不要用 JPG 做技术文档配图。JPG 的有损压缩会导致线条图出现明显色块。

我们团队的 SOP：所有文档图片统一存放在./images/目录，命名规范fig-01-architecture.svg、fig-02-ui-screenshot.png，并在style.css中全局设置img { max-width: 100%; height: auto; }防止溢出页面。

5.3 “数学公式不显示，PDF 里一堆$E=mc^2$”——MathJax 渲染的致命依赖

Pandoc 的--mathjax参数，只是在 HTML 中插入 MathJax 的 CDN 脚本<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>。但 Prince 渲染时，默认禁用 JavaScript！所以 MathJax 不会执行，公式原样显示。

解决方案：在 Prince 命令中显式启用 JS，并指定 MathJax 本地路径（避免网络请求失败）：

prince "$HTML_FILE" -o "$PDF_FILE" --javascript --resource-path=./mathjax

其中./mathjax是你下载的 MathJax 离线包（去 mathjax.org 下载），解压后放在项目目录。这样 Prince 就能本地加载 MathJax，正确渲染$$E=mc^2$$为印刷体公式。

5.4 “客户说 PDF 不能编辑，但我们需要留签名栏”——添加可填写表单域的技巧

Prince 支持 PDF 表单域（Form Fields），但需在 HTML 中用<input type="text">或<textarea>标签，并添加name属性。例如：

<div style="page-break-before: always;"> <h2>客户确认签字</h2> <p>请在下方签署：</p> <p>姓名：<input type="text" name="customer_name" style="width: 300px; border: 1px solid #ccc;"></p> <p>日期：<input type="text" name="date" style="width: 150px; border: 1px solid #ccc;"></p> </div>

Pandoc 不会把 Markdown 转成<input>，所以这部分 HTML 需要手写，并保存为signature.html，最后用prince api-doc.html signature.html -o final.pdf合并。生成的 PDF 在 Acrobat 中，这些字段就是可点击填写的表单域。

注意：表单域在大多数 PDF 阅读器（如 SumatraPDF）中只读，仅在 Acrobat 或 Foxit 中可编辑。如果客户环境不确定，建议用 PNG 签名图替代。

5.5 性能优化：大型文档（>100页）的生成提速策略

一份 200 页的《系统架构白皮书》，用默认设置生成 PDF 可能耗时 2 分钟。优化点有三：

• 关闭不必要的渲染：prince ... --no-pdf-compression会禁用 PDF 压缩，加快生成但文件变大；--log-level=error减少日志输出，提升速度。
• 预编译 CSS：把style.css中的@import全部内联，减少 Prince 解析时间。
• 分章生成再合并：用pdftk（macOS/Linuxbrew install pdftk，Windows 下载 GUI 版）将各章 PDF 合并：pdftk ch1.pdf ch2.pdf ch3.pdf cat output manual.pdf。每章独立生成更快，且便于并行处理。

我们实测：237 页文档，单次生成 118 秒；分 5 章生成（每章约 50 页）+ 合并，总耗时 76 秒，提速 35%。

6. 进阶扩展：让工作流更智能的三个实战技巧

6.1 VS Code 快捷键绑定：Ctrl+Alt+P一键生成，无需开终端

Code Runner