在技术文档中，表格是读者最常查阅的元素之一。同时，它也是 Markdown 转换为 PDF 时最容易排版错乱的部分。在宽屏显示器上清晰美观的列，在 A4 页面上会显得异常拥挤；过长的单元格文字会将网格挤出边距，而行跨页切断则会导致表头失去意义。
md2pdf 负责解析 GitHub Flavored Markdown 表格并将其交由打印样式表或 A4 PDF 渲染引擎输出。工具能保持规范表格的清晰度，但无法凭空创造打印空间。核心关键在于优化 Markdown 源文档：精简列数、压缩单元格字数，并合理规划表格承载的内容。
本指南首先介绍源文档层面的优化技巧，随后提供打印输出前的核查要点。完整转换流程请参阅如何将 GitHub README 转换为 PDF。
为什么表格在打印时容易排版错乱
浏览器中的网页表格具有很高的弹性：它允许内容横向滚动或自适应收缩。但纸张页面具有固定的物理宽度，没有任何滚动条。一旦内容超出页面宽度，打印引擎要么直接截断超出部分，要么将其强行缩放至无法阅读。
以下三个习惯会加剧排版故障：
- 列数过多。 即使数据完整，局促的八列也远不如四列清晰易读。
- 单元格内塞入整段文字。 包含多行长句的单元格会将轻快的对比表变成密集的文本墙。
- 无空格的长代码或长 URL。 只要有一个不换行的超长字符串，整列的最小宽度就会被强行撑大。
解决之道不是盲目缩小字号，而是为表格减负，让其专注于核心指标。
从尺寸适中的基础表格开始
实用的表格往往目标明确且列数精炼。以下示例对比了打印主题，而无需罗列所有 CSS 属性：
| Setting | Clean | Business | Academic |
| --- | :--- | :--- | ---: |
| Body type | Sans | Serif | Justified serif |
| Best for | Specs | Reports | Course readers |
| Tone | Neutral | Formal | Editorial |该表格能够完美置入 A4 和 Letter 页面，且由于单元格极简，在多语言翻译后依然整洁稳定。:--- 代表左对齐，:---: 代表居中，---: 代表右对齐。
请依据数据含义选择对齐方式：数值类建议右对齐，短标签建议左对齐。居中对齐较少用到，过度使用会降低扫读效率。
根据读者诉求而非全部数据来设定列
在增加一列之前，请思考该表解答了读者的什么疑问。例如版本迁移表解答的是“变动了什么以及如何处理”，只需三列：变更项、变动说明与操作建议。包含十几个字段的数据库结构导出并不适合直接做成 PDF 表格。
大声朗读表头行是一个很好的检验方法：如果各列标题无法连贯表达对比意图，则说明表格承载了过多信息。
对于横向较宽的参数参考数据，建议改用双列定义表：
| Field | Meaning |
| --- | --- |
| `owner` | GitHub user or organization |
| `repo` | Repository name without the host |
| `ref` | Branch, tag, or commit SHA |相比多列宽表，这种双列结构在打印和翻译时都更为稳定可靠。
保持单元格文字精炼利于扫读
表格旨在快速对比，而非详尽叙述。如果一个单元格需要两句以上长文，请将详细解释移至表格下方，单元格内仅保留核心摘要。
实用排版准则：
- 使用精简短语。 例如写“需公开仓库”即可，不必扩充成长句。
- 将计量单位放在表头。 表头注明
大小 (MB)，无需每行重复写 MB。 - 避免单元格内强制换行。
<br>标签往往会干扰跨页分页。 - 使用简短链接文本。 避免直接粘贴未经缩短的完整 URL。
- 避免仅凭颜色区分状态。 打印文档可能会被黑白复印。
若必须包含超长命令行，请将其放置在表格下方的代码块中，并在表格中引用其名称。
在导出前重构超宽数据
当某些复杂数据无法删减列数时，请通过调整文档结构来解决宽度问题：
- 按受众拆分。 运维人员与前端开发人员关心的参数维度不同，可拆分为独立表格。
- 按时间拆分。 漫长的发布日志可按主版本号拆成多个子表。
- 行列转置。 当项目较少但属性较多时，可将属性作为行、项目作为列，使表格纵向延展。
- 转为列表展示。 若表格中存在大量空白单元格，采用带小标题的无序列表往往更为清晰。
重构后请再次检查源码，确保没有未换行的超长字符串撑宽列宽。
检查分页跨页与表头重复显示
单页显示正常的表格在跨页时可能产生缺陷。表头应当在次页正常重复，单行内容不应被硬性截半，表格也不应仅有一行留在页末。
浏览器自带打印与多文件图书导出的分页逻辑存在细微差异。如果表格较长，建议在表头上方添加一段简短说明文字，以便读者在第二页翻阅时依然清晰上下文。
导出前的检查清单
在正式打印或导出 PDF 前，请逐一确认：
- 表格主题明确，列数不超过五至六列。
- 表头简短，并已标注相应的计量单位。
- 单元格文字提纲挈领，无冗长段落。
- 无超出页面宽度的长代码或原始 URL。
- 数值与文本采用了合理的对齐规则。
- 跨页表格配备了上下文说明标题。
- 已实际打开生成的 PDF 文件进行翻页查验。
各主题的具体字体与边距细节，请参阅 Clean、Business、Academic 与 Dark 主题解析。
技术文档中的表格无需繁复修饰，最核心的是打印后清晰可辨。规范精简的表格始终优于拥挤混乱的宽表。
制作你自己的 README PDF
免费、无需登录，全程在浏览器本地完成。