Markdown 配套文件全指南：渲染、模板与 PDF 导出实践

1. 一份 .md 文件脱离渲染环境之后，配套文件才真正开始承重

我见过太多人第一次把 Markdown 文档发给同事时的场面：对方用记事本打开，满屏的井号、星号、竖线和反引号，第一反应是"你发错文件了吧"。这不是对方水平问题，而是 Markdown 这个格式最本质的特征决定的——它本身只是一段带约定记号的纯文本，真正决定它长什么样、能不能打印、图片显示不显示、公式渲不渲染的，是那堆跟着它一起走的配套文件。标题里说"Markdown 配套文件下载"，讲的其实就是这件事：光有一个 .md 是半成品，配套的样式表、模板、字体、图标、代码片段、导出脚本凑齐了，它才是一份能交付的东西。

这篇内容适合三类人看：一是刚用 Markdown 写文档、笔记、周报，发现"导出成 PDF 就丑得没法发"的新手；二是已经在用，但每次换台电脑、换个编辑器就要重新配一遍的效率型用户；三是需要把 Markdown 当生产工具批量产文档、做技术手册、写简历或做课程讲义的人。我会把配套文件按功能拆成几层，讲清楚每一层解决什么具体问题、免费资源从哪里找、拿下来之后怎么落地到自己的目录里，最后把我在导出环节踩过的几个坑完整摊开——尤其是中文 PDF、图片相对路径、长表格被切断这几类，几乎是每个人都会撞上的。

先说个反直觉的结论：配套文件不是越多越好，而是要"能跟着文档一起版本化"。我早期干过一件蠢事，从各处收集了十几个主题样式，全塞进编辑器的全局配置里，结果某天升级之后预览面板字号乱跳、表格线全丢，排查了两个小时才发现是两个样式文件里的table选择器互相打架。从那之后我的原则就变了：所有配套文件必须放在文档仓库自己的assets/目录里，跟着项目走，绝不放全局。下面这套组织方式，就是被那次事故逼出来的。

排版这件事，在没有配套样式的情况下，浏览器默认给 Markdown 渲染结果的行高大概只有 1.4，中文读起来非常挤；代码块没有背景色和边框，跟正文混在一起；表格连最基本的内边距都没有，文字紧贴边框线。这些不是审美问题，是可读性问题，尤其在需要评审、需要打印的场景下，一份没有样式约束的文档，阅读成本会翻倍。

2. 把配套文件拆成五层：每层解决一个具体的"不显示"

我习惯把 Markdown 周边资源按"它到底修复了什么缺陷"来分类，而不是按文件后缀分类。这样分的好处是，当你发现某个问题（比如"公式变成了一堆美元符号"）时，能立刻定位到该补哪一层，而不用漫无目的地找资源。

2.1 渲染层：样式表要"作用域可控"，不要一把梭全局

渲染层的核心是一份 CSS。免费的主题样式库很多，开源社区里有专门为 Markdown 渲染结果做的排版样式，特点是给body限定一个容器类，然后所有选择器都挂在这个容器下面。这类文件我优先选，因为它不会污染宿主页面——你要是把样式全局注入编辑器，很容易把界面本身的按钮、侧边栏一起改掉。

拿到样式之后别急着直接用。我一般会做三件事：把正文字体换成系统里已有的中文字体族、把max-width从默认的 900px 左右调整到 46em 上下（中文一行 40 到 45 个字最舒服）、把代码块的font-size降到正文的 0.9 倍。这三点调完，可读性提升比换十个主题都明显。

还有一个容易被忽略的点：预览样式和打印样式必须分开。预览是屏幕阅读，行高可以到 1.8，字号可以大；打印是纸张，行高 1.6 就够，而且必须处理分页。很多人把屏幕样式直接拿去打印，结果标题孤零零挂在页底，表格从中间被劈开。

2.2 模板层：导出质量的差距，八成在这里

同一份 Markdown，用不同的模板导出成 PDF，观感能差出一个档次。模板负责的是页面级的规格：纸张大小、页边距、页码位置、标题是否自动编号、目录生成规则。免费方案里比较成熟的组合是"通用文档转换工具 + LaTeX 模板"或者"通用文档转换工具 + docx 参考文档"。

docx 参考文档这条路特别值得推荐给不熟悉排版系统的人：你只要新建一个 Word 文件，把各级标题样式、正文样式、代码样式调好，保存成reference.docx，之后所有导出都会继承这套样式。整个过程不需要写一行代码，改样式就在 Word 界面里点。我给自己维护的参考文档里固定设置了：标题 1 段前 18 磅段后 8 磅、正文首行缩进两个字符、代码样式用等宽字体加浅灰底纹。

2.3 资产层：图片和字体是最容易被忽略的两块

图片这一块的关键不是"下载好看的图"，而是路径管理。我在所有文档仓库里都强制一个规则：图片一律放在assets/images/下，引用一律用相对路径，绝不用绝对路径。原因很实际——绝对路径在你本机好好的，把文件夹发给别人就全裂了。

字体是第二块。中文文档导出 PDF 出现方块字，本质就是导出引擎找不到能渲染中文的字体。解决办法不是"下载一个中文字体装上"这么简单，而是要在导出参数里显式指定字体名，而且这个名字必须是字体系统识别到的名称，不是你下载的文件名。这一点后面第五节会详细说。

2.4 效率层与质检层：把重复劳动固化下来

效率层的核心是代码片段。我给自己的编辑器配了几个固定片段：输入tb3自动展开成三列表格骨架，输入toc展开成目录标记，输入note展开成引用块提示。看着是小事，但一周写五篇文档，累积下来省的时间很可观，更重要的是格式统一——不会这篇用三列那篇用四列。

质检层最实用的是一个二十行的路径检查脚本，每次提交前跑一遍，把所有引用了但实际不存在的图片路径打出来。这个脚本帮我拦下过至少十次"图还没导出来就先把文档发出去了"的事故。

3. 下载之前的四道筛子：我怎么判断一个免费配套资源值不值得用

"亲测免费"这四个字现在水很深。很多资源标着免费，实际是个人非商业授权，你拿去做公司文档就是违规；还有些是免费但依赖一大堆在线服务，断网就废。我在下载任何配套资源之前，会固定过四道筛子。

3.1 第一道：先看许可证，再看好不好看

顺序不能反。我看过太多人因为一个主题配色好看就直接用，用了半年才发现许可证写着非商业使用。判断方法很简单：仓库根目录找LICENSE文件，看它属于哪一类。

• 宽松型许可（允许商用、允许修改、要求保留版权声明）：随便用，最省心。
• 保留版权型（允许商用但衍生作品必须同许可发布）：内部文档没问题，但如果你的配套文件要随文档一起对外分发，要注意。
• 非商业型：个人笔记随便，公司项目别碰。
• 无许可证：默认保留所有权利，严格来说你不能随便改和分发，只能自己看看。

我的做法是给每个用到的外部资源在仓库里建一个CREDITS.md，记下来源、许可证类型、下载日期。半年后你根本记不住那个 CSS 是哪来的，这份记录能救命。

3.2 第二道：看活跃度，不看 star 数

star 多不等于能用。我真正看的是三样：最后一次提交时间、未关闭的问题数量、最近三个月有没有人回复问题。一个两年没更新、问题区堆了三百条的样式库，哪怕再好看我也不碰——因为渲染引擎的语法在演进，老样式很容易在新版本里失效。

有个具体的信号很好用：看问题区里有没有"某次升级后表格样式失效"这类报告，以及有没有人回应。有回应说明维护者在，没回应就是弃坑前兆。

3.3 第三道：算体积，看能不能离线跑

我吃过一次亏：用一个在线加载字体和图标资源的模板，结果在没网的环境下导出，字体全回落成默认衬线体，整个文档的观感崩掉。从那以后我的标准是所有配套资源必须本地化，字体、图标、样式一个都不许走网络请求。

具体检查方法：打开样式文件全文搜@import和url(http，凡是命中的一律下载到本地改成本地路径。图标字体如果体积太大，干脆换成内联的矢量路径。

3.4 第四道：小样测试，别直接上正式文档

这条最土但最有效。任何新下载的配套文件，我一定先拿一篇两千字左右、包含标题、列表、表格、代码块、图片、公式的"全要素测试文档"跑一遍，确认六种元素都正常再投入使用。直接拿正式文档试的代价太大——你可能要花半小时才能发现是样式问题还是自己的语法写错了。

我把这份测试文档叫smoke.md，常年放在仓库根目录，每次换模板、换编辑器版本都跑一遍，属于低成本高回报的投入。

4. 目录怎么搭：一套能跟着文档走、换电脑不用重配的结构

配套文件散落在下载文件夹里，是最常见的失败起点。我现在的做法是让它们全部住在文档项目内部，跟着版本管理一起走，换机器的时候克隆下来就能用。

4.1 目录骨架

my-docs/ ├── docs/ │ ├── 01-intro.md │ └── 02-usage.md ├── assets/ │ ├── css/ │ │ ├── preview.css # 屏幕预览用 │ │ └── print.css # 打印/导出用 │ ├── fonts/ │ │ └── (本地字体文件) │ ├── images/ │ │ └── arch-01.png │ └── templates/ │ ├── reference.docx │ └── default.latex ├── snippets/ │ └── markdown.json ├── scripts/ │ ├── build.sh │ └── check-assets.sh ├── smoke.md ├── CREDITS.md └── .editorconfig

这个结构的核心逻辑是"文档和它的渲染环境在同一个版本里"。assets/下所有东西都是相对引用，克隆到任何路径都能跑；scripts/里是可执行的一键构建；CREDITS.md记录外部资源出处；smoke.md是做回归的测试样本。

.editorconfig这个文件很多人不用，但它能强制统一换行符和末尾空行。团队协作时，Windows 和 macOS 混用会让整个文件的 diff 变成"全文件修改"，一个.editorconfig就解决了。

4.2 编辑器配置只写项目级，不写全局

不管你用哪个编辑器，配置都分全局和项目级。配套文件相关的配置一律写项目级，也就是跟着仓库走的那个配置文件。这样换项目、换电脑都不会互相污染。下面是我常用的一组项目级配置，针对 Markdown 写作场景：

{ "markdown.preview.fontSize": 15, "markdown.preview.lineHeight": 1.8, "markdown.styles": ["./assets/css/preview.css"], "[markdown]": { "editor.wordWrap": "on", "editor.lineNumbers": "off", "editor.renderWhitespace": "none", "editor.quickSuggestions": { "other": true, "comments": false, "strings": true }, "editor.tabSize": 2, "files.trimTrailingWhitespace": true }, "markdown.extension.toc.levels": "2..3", "markdown.extension.list.indentationSize": "adaptive", "markdown.extension.tableFormatter.enabled": true }

这里每一行都有理由。lineNumbers关掉是因为 Markdown 里行号纯干扰，而且会让预览和源码的对应关系变得更难判断；wordWrap必须开，否则长段落要左右滚动，写起来极其难受；trimTrailingWhitespace很重要——行尾空格在 Markdown 里是有语义的（两个空格代表换行），但多数人不需要这个特性，反而容易误留，导致 diff 里一堆看不见的改动；indentationSize设成自适应，是因为列表嵌套的缩进规则在不同风格下不一样，硬编码成 2 或 4 都可能踩坑。

4.3 打印样式单独写一份，重点处理分页

打印样式和屏幕样式最大的差异在分页控制。下面这份是我用了很久的骨架，可以直接抄：

@media print { @page { size: A4; margin: 18mm 16mm 20mm 16mm; } body { font-family: "Noto Serif CJK SC", "Source Han Serif SC", "Songti SC", serif; font-size: 10.5pt; line-height: 1.65; color: #1a1a1a; } /* 标题后面不要立刻分页 */ h1, h2, h3, h4 { page-break-after: avoid; } /* 表格、代码块、图片不要被从中间劈开 */ table, pre, figure, blockquote { page-break-inside: avoid; } /* 表格线在打印时必须显式声明 */ table { border-collapse: collapse; width: 100%; font-size: 9.5pt; } th, td { border: 0.5pt solid #999; padding: 4pt 6pt; } /* 代码块加浅底纹，黑白打印机也能区分 */ pre { background: #f4f4f4 !important; border: 0.5pt solid #ddd; padding: 6pt 8pt; font-size: 9pt; white-space: pre-wrap; word-break: break-all; } /* 外链在打印件里必须能看到地址 */ a[href^="http"]::after { content: " (" attr(href) ")"; font-size: 8pt; color: #555; } /* 目录页单独起一页 */ .toc-page { page-break-after: always; } }

几个关键点的用意：page-break-inside: avoid里的avoid在现代浏览器里其实已经改成break-inside，但保留旧写法兼容性更好；代码块加white-space: pre-wrap和word-break: break-all，是因为长命令在 A4 宽度里一定会溢出，不换行就会被裁掉；外链后加地址，是因为打印件上的链接点不了，读者需要看到真实地址。

4.4 一键构建脚本：把所有导出参数固化

纯手工敲导出命令，三天就记不住参数了。我把它写成脚本，参数集中在脚本头部：

#!/usr/bin/env bash set -euo pipefail SRC="${1:?用法: ./scripts/build.sh docs/01-intro.md}" NAME="$(basename "${SRC%.md}")" OUT="dist" mkdir -p "$OUT" # 通用参数：开启 GFM 表格、数学公式、脚注 PANDOC_ARGS=( --from "gfm+tex_math_dollars+footnotes+pipe_tables" --resource-path=".:assets/images" --metadata "date=$(date +%Y-%m-%d)" ) # 1) 导出 HTML，资源和样式全部内联，方便单文件分发 pandoc "$SRC" "${PANDOC_ARGS[@]}" \ --to html5 \ --standalone \ --css assets/css/print.css \ --highlight-style tango \ --embed-resources \ --metadata title="$NAME" \ -o "$OUT/$NAME.html" # 2) 导出 PDF，指定中文字体，否则方块字 pandoc "$SRC" "${PANDOC_ARGS[@]}" \ --pdf-engine=xelatex \ --template assets/templates/default.latex \ -V CJKmainfont="Noto Serif CJK SC" \ -V CJKsansfont="Noto Sans CJK SC" \ -V geometry:margin=2cm \ -V fontsize=10.5pt \ -o "$OUT/$NAME.pdf" echo "done: $OUT/$NAME.html $OUT/$NAME.pdf"

注意--resource-path这个参数，它决定了图片路径的解析基准。很多人导出的 PDF 里图片全丢，就是因为转换工具在临时目录里处理，找不到相对路径的图片。显式加上这个参数，把项目根目录和图片目录都写进去，问题基本就解决了。

--embed-resources是导出单文件 HTML 的关键，它会把 CSS、图片、字体全部转成内联数据。好处是发出去就一个文件，不会出现"HTML 能打开但图全裂"的情况；代价是文件体积会变大，一张 500KB 的图内联进 HTML 大约是 700KB 左右的文本。

5. 导出环节的连环坑：从方块字到断表格，我是这么一个个排掉的

这一节是全篇最实用的部分，因为下面这几个问题几乎百分之百会遇到，而且报错信息通常非常含糊，不看具体现象根本无从下手。

5.1 中文 PDF 变成方块：字体名和字体文件是两回事

现象：导出的 PDF 里，英文和数字正常，中文全是方框。

根因：导出引擎默认使用的字体不包含中文字形。解决办法是显式指定一个含中文字形的字体，但指定的名字必须是字体系统里注册的名称，不是你下载的文件名。比如你下载的文件叫SourceHanSerifSC-Regular.otf，在参数里写这个名字是无效的，要写Source Han Serif SC。

怎么确认正确的名字？列一下系统已识别的字体，找中文名对应的英文族名。名字对了还是方块，通常是字体没有真正安装到系统，只是放在了文件夹里——有些导出引擎不会去扫描任意目录下的字体文件。

另外一个隐性坑：粗体和斜体需要单独指定。主字体指定好了，正文正常显示，但加粗的地方看起来没变粗，或者斜体变成了正体，这就是缺CJKmainfont的粗体字重。解决方式是指定字重参数，或者在模板里配置字体族回退链。

5.2 图片相对路径在导出后全断：基准目录不是你以为的那个

现象：编辑器预览里图片显示正常，导出 HTML 或 PDF 之后全部裂图。

根因：预览时的路径解析基准是"当前打开的文件所在目录"，而导出时的基准可能是"执行命令的目录"或者"临时工作目录"。这两个不一样，相对路径自然失效。

排查步骤我固定成三步：第一步，把 Markdown 里的图片引用全部打出来看格式，确认都是assets/images/xxx.png这种不带./也不带../的干净相对路径；第二步，在导出命令里显式加资源搜索路径参数，把项目根目录和图片目录都包含进去；第三步，导出后在输出文件里搜一下图片文件名，如果搜不到，说明转换环节根本没读到，问题在路径；如果搜到了但显示不出来，问题在图片编码。

还有一个细节：文件名里带空格或中文，在某些导出链路上会出问题。我的规则是图片文件名一律用小写英文加连字符，绝不带空格。

5.3 长表格被从中间切断：不是样式问题，是分页策略问题

现象：导出的 PDF 里，一个十几行的表格前面几行在上一页，后面几行在下一页，表头也不重复。

根因：表格被当成了一个不可分割的块，但它又太长，超出一页高度，排版引擎只能硬切。

处理分两个方向。如果表格不算特别长，给它加"内部不分页"的约束，让它整体挪到下一页；如果表格很长（超过一页），那就反过来，允许它跨页，但必须让表头在每一页重复。后者在 HTML 打印样式里通过表头分组实现，在 LaTeX 模板里则是另一套写法。

实际操作中我还有个更省事的办法：把超长表格拆成两张逻辑表，或者把其中几列合并成"备注"列。文档里的表格超过八列、超过十五行，阅读体验就已经很差了，拆开反而更好读。

5.4 代码高亮在导出后消失：高亮主题和样式表打架

现象：预览时语法高亮正常，导出 HTML 后代码全变成一种颜色。

根因：高亮是由转换工具在导出时重新生成的，用的是它自己的高亮主题，而不是你 CSS 里那套。你 CSS 里如果也定义了代码颜色，两边就会冲突，后加载的赢。

解决办法是二选一，别混着来：要么在导出参数里指定高亮主题、CSS 里完全不碰代码颜色；要么导出时关掉内置高亮，全靠 CSS 自己写。我选前者，因为内置主题的颜色搭配通常经过调校，比自己随手写的协调。

5.5 一个通用的排查思路

上面四个坑看着各不相同，排查逻辑其实一样：先确认问题发生在哪一层，再往下钻。顺序是：源文件语法对不对 → 编辑器预览对不对 → 导出的中间产物（比如 HTML）对不对 → 最终的 PDF 对不对。每一层都正确才能进入下一层，一旦某层出错就停在那里查，不要跳层猜。

我见过有人 PDF 里图片不显示，直接去改 LaTeX 模板，折腾一下午。其实只要先导出一次 HTML 看看，五秒钟就能确定是路径问题。

6. 配套文件也需要"养"：版本管理、回归检查和定期瘦身

配套文件最容易出的问题不是一开始配错，而是配好之后没人管，慢慢腐烂。编辑器升级一次、转换工具升级一次、系统字体更新一次，任何一环变动都可能让半年前的配置失效。所以我把配套文件当成代码来维护。

6.1 全部纳入版本管理，包括二进制文件

CSS、脚本、模板、配置文件自然要进版本库。字体和 docx 参考文档这类二进制文件也有必要进，虽然它们没法做行级 diff，但至少能保证"哪次提交换的字体"这件事可追溯。我遇到过导出突然变丑的情况，翻提交记录发现是某次不小心把参考文档覆盖成了一个默认模板，五分钟就定位了。

二进制文件多了会让仓库变大，所以我有两条规矩：单个字体文件超过 10MB 的不进库，改成在文档里写明下载来源和校验值；图片进库前先压缩，超过 300KB 的图片要么压要么改成链接引用。

6.2 一个二十行的资产检查脚本，拦住大部分低级错误

这个脚本我每次提交前跑，逻辑就是扫 Markdown 里的图片引用，逐个检查文件是否存在：

#!/usr/bin/env bash set -uo pipefail FAIL=0 while IFS= read -r md; do base="$(dirname "$md")" # 提取所有 ![alt](path) 里的 path grep -oE '!\[[^]]*\]\([^)]+\)' "$md" 2>/dev/null \ | sed -E 's/.*\(([^)]+)\)/\1/' \ | while IFS= read -r p; do # 跳过网络图片和 data URI case "$p" in http*|https*|data:*) continue ;; esac # 去掉可能存在的锚点 clean="${p%%#*}" if [ ! -f "$base/$clean" ]; then echo "缺失图片: $md -> $p" fi done done < <(find docs -name '*.md') echo "资产检查结束"

这段脚本不复杂，但覆盖了最容易出问题的场景：图片改名后忘了同步、新建文档时路径写错、从别处复制内容带过来了不存在的图。跑一次不到一秒，比发出去被人指出来体面得多。

6.3 每季度做一次回归：用 smoke.md 全量验证

我会在每季度固定跑一次全要素验证：拿smoke.md分别导出 HTML、PDF、docx 三种格式，肉眼扫一遍六种元素——标题层级、有序无序列表、表格、代码块（含长行）、图片、数学公式。哪个出问题就修哪个。

这套流程听起来有点重，但实际每次不超过十分钟，而它能避免的是"半年后要交一份正式文档，结果发现导出链路早就坏了，临时抱佛脚"这种被动局面。

6.4 定期瘦身：删掉不用的主题和模板

下载资源有个惯性，看到好看的就存下来，结果目录里堆了二十个主题，实际只用那一个。多余的资源除了占空间，更大的问题是干扰判断——出问题的时候你会怀疑是不是某个没用到的样式在捣乱。

我的清理标准很简单：连续两个季度没用过的主题、模板、字体，删掉，只保留来源记录。真需要的时候再去下载，反正有记录，五分钟的事。

6.5 一个容易忽略的维护点：编辑器版本升级

编辑器大版本升级后，插件配置项名字可能变、默认行为可能变。我的习惯是升级后立刻跑一遍smoke.md，重点看三件事：预览样式还生效吗、表格格式化还正常吗、代码片段还能展开吗。这三样正常，基本就说明配套环境没坏。

有个具体的经验：升级后如果预览面板的字体大小突然变得很大或很小，先别去改 CSS，去看编辑器的预览字号配置项有没有被重置。我遇到过两次，都是配置被升级覆盖了，CSS 本身没问题。

最后分享一个小技巧，也是我这几年最受益的一条：把你最常用的一份完整配置单独存成一个模板仓库，新项目直接复制过去。这样你永远有一个"已知可用"的起点，而不是每次从零开始拼装，出问题时也有对照物可以比。配套文件这东西，价值不在于你收集了多少，而在于你有一套自己验证过、能稳定复现的最小集合。