PDF 中的 Markdown 代码块：围栏、长行与分页控制

在 Markdown 文档中，代码往往在屏幕上显示良好，但打印到纸面上时最容易排版错乱。适合宽屏显示器的长代码行会超出 A4 页面的右边距；代码块也可能刚好卡在页脚处，导致前两行留在上一页，其余内容被切断到下一页。

md2pdf 将围栏代码块渲染为打印布局中的预格式化文本。它不会强加彩色语法高亮，也不会为了适应页面而随意自动重排源代码，因为随意更改代码可能会破坏其结构或含义。实用的做法是在源文档中做好格式优化，使其无需转换就能清晰易读。

本指南将详细介绍围栏代码块、语言标签、行宽规范、主题搭配以及导出 PDF 前的排查清单。完整工作流程请参阅如何将 GitHub README 转换为 PDF。

转换器如何处理围栏代码块

GitHub Flavored Markdown 支持由三个或更多反引号或波浪号包裹的围栏代码块。md2pdf 会解析这些围栏，完整保留原始文本，并将其渲染在 <pre><code> 元素中。起始标记后的语言标签会被保留为 CSS 类名，但当前渲染器不会应用彩色语法高亮主题。

这意味着两点：

• 代码的缩进、空行和标点符号均严格保留原样。
• 视觉呈现为带有当前主题背景和边框的等宽纯文本，而非彩色代码标记。

如果文档依赖颜色来展示代码差异（diff），请在正文中添加简要说明，或在源代码中使用 + 和 - 符号标记。不要假定读者在打印件中能分辨红绿色彩。

使用围栏代码块而非空格缩进

在 Markdown 中缩进四个空格同样可以创建代码块，但围栏代码块更易掌控。它们明确界定了起始与结束位置，支持语言标识符，并且不会因代码内部某行缩进而意外断开。

标准的围栏代码块示例：

npm install
npm run build
npm test

请使用比代码内容中最长连续反引号更长的标记。如果代码示例包含三个反引号，请用四个反引号来开闭包裹。在编写关于 Markdown 本身的说明文档时尤为关键。

请避免在同一代码块中混用制表符与空格。渲染器会严格按原样输出，不一致的缩进会让正确的代码看起来像格式错误。

即使无高亮也请标注语言标签

即使没有语法高亮，语言标签依然具有重要价值。它记录了代码的编程语言，辅助编辑器与代码检查工具，并明确告知翻译人员此区域不应被翻译。同时也有利于源代码检索。

常见的标签包括 bash、js、ts、json、yaml、python、html、css、sql 以及 text。对于终端输出、运行日志或目录树，请使用 text。

不要仅仅因为某些工具支持就随意标注不匹配的语言，应准确反映内容的真实类型。

将代码行控制在可打印宽度内

打印时最常见的问题就是代码行超出页面宽度。在浏览器预览中代码块可以横向滚动，但纸质文档没有滚动条，长行会被直接截断或导致整体缩放变形。

对于 A4 或 Letter 纸张，舒适阅读等宽文本的推荐行宽一般在 80 到 90 个字符左右。

当单行代码过长时，请在源文件中优化换行，而非缩小打印比例：

const message = buildMessage({ owner, repo, branch, path });

这样的单行代码清晰可读。如果对象属性较多，请将其拆分为多行排版：

const message = buildMessage({
  owner,
  repo,
  branch,
  path,
});

对于终端命令可使用反斜杠换行或提取变量；过长的 URL 请单独成行放置。目标是消除对横向滚动的依赖。

合理处理控制台输出与日志

运行日志与命令输出通常比源代码更宽，且包含时间戳和长路径，无法随意断行。

适合打印的处理建议：

• 精简输出。 仅展示关键行，并在说明正文中使用省略号提示。
• 拆分展示。 将命令与输出结果分成两个独立的代码块，中间辅以简短说明。
• 使用表格展示结构化数据。 如果输出本质上是表格数据，Markdown 表格的打印效果往往优于纯文本代码块。
• 字号缩小仅作兜底选项。 调整主题字号会影响全文。

除非文档本身就是日志报告，否则切勿在 PDF 中粘贴两百行的完整运行记录。

根据打印主题调整代码排版

四个打印主题对代码块的处理各有特色。Clean 采用浅色背景与中性无衬线字体；Business 采用对比明显的深色底衬搭配衬线正文；Academic 保持轻简淡雅；Dark 针对屏幕浏览优化，其打印样式表会自动切换为易读的浅色底。

实用建议：

1. 在实际主题下检查对比度。 在 Clean 主题下适中的代码块，在 Business 中可能显得过于沉重，或在 Academic 中对比偏弱。
2. 打印时务必开启背景图形。 如果关闭背景图形，代码块的底色将丢失，仅保留外边框。

如果文档以代码为主，Clean 主题最为稳妥。详细对比请参阅 Clean、Business、Academic 与 Dark 主题解析。

仔细检查生成的 PDF 页面

打开生成的 PDF 文档，逐一检查每一个代码块：

• 右侧截断。 放大观察右边距，确认没有长指令被截断。
• 孤行断页。 避免代码块第一行孤零零落在页末。
• 缩进一致。 确认空格与制表符对齐工整。
• 空行完整。 检查逻辑分段的空行是否得到完整保留。
• 黑白打印对比度。 若文档需复印，建议在灰度模式下预览。
• 正文语言补充。 若语言标识对读者十分重要，请在正文中加以说明。

若文档需广泛分发，建议在不同浏览器中均预览一次打印效果。

代码块是技术文档中最常被复制和引用的部分。请保持其精简、准确并居于页面边界之内。了解更多转换隐私细节，请参阅浏览器端纯本地 Markdown 转 PDF 说明。