Markdown转中文PDF不再乱码：md2pdf双引擎搞定字体嵌入
内容提要
md2pdf是一款将Markdown转为PDF的命令行工具，专为中日韩文字优化。它提供Typst和CoreText双引擎，解决字体嵌入问题，内置五套字体预设，支持表格跨页和代码块完整分页。相比竞品，它轻量快速，无需复杂配置，适合中文文档排版。
延伸解读
字体嵌入：屏幕显示与PDF的差异
文章指出，屏幕显示与PDF字体嵌入是两套逻辑。屏幕渲染临时调用系统字体，而PDF需将字体数据打包。中文字体文件大、嵌入成本高，且苹果PingFang字体使用私有hvgl表，第三方引擎无法读取，导致macOS上常见乱码或字体回退。理解这一差异，有助于排查转换问题。
双引擎设计：Typst与CoreText的取舍
md2pdf提供Typst和CoreText双引擎。Typst引擎跨平台、轻量，但无法嵌入PingFang；CoreText引擎仅限macOS，通过系统框架渲染，能嵌入真PingFang，但需图形会话，不适合无头环境。用户需根据平台和字体需求选择，自动化场景只能用Typst引擎。
表格与代码块分页：排版引擎的优势
浏览器打印路线按页面切分内容，导致表格行被截断、代码块不完整。Typst作为专业排版引擎，分页时考虑元素完整性，表格行整体移动，代码块完整放置。这是排版引擎与打印引擎的本质区别，也是md2pdf解决此类问题的关键。
使用门槛与限制
md2pdf并非开箱即用：Typst引擎需Pandoc 3.1.3+和Typst，Linux自带Pandoc可能过旧；CoreText引擎需编译且依赖图形会话。字体预设覆盖常见场景，但自定义字体需通过--font参数指定系统字体名，对不熟悉字体管理的用户仍有门槛。
Q&A
md2pdf是什么？它主要解决什么问题？
md2pdf是一个将Markdown文档转换为排版精良的PDF的命令行工具，专为中日韩（CJK）文字优化。它主要解决中文等CJK文字在PDF转换中常见的字体嵌入、行距、表格跨页和代码块截断等问题。
为什么Markdown转PDF时中文字体会乱码或丢失？
因为大多数工具将Markdown转为HTML再用浏览器引擎打印PDF，对中文支持不佳。中文字体文件大、嵌入成本高，且部分字体如苹果的PingFang使用私有hvgl表，第三方引擎无法读取，导致字体无法嵌入或回退。
md2pdf的双引擎设计是什么？各自有什么特点？
md2pdf提供Typst和CoreText两个引擎。Typst引擎跨平台、轻量快速，通过Pandoc将Markdown转为Typst再编译PDF，适合大多数场景；CoreText引擎仅限macOS，使用系统CoreText框架渲染，能嵌入真正的PingFang字体，适合追求原汁原味中文排版的用户。
md2pdf内置了哪些字体预设？如何切换？
md2pdf内置五套字体预设：默认（Noto Sans CJK SC + Helvetica Neue）、hiragino（Hiragino Sans GB + Helvetica Neue）、songti（宋体 + Libertinus Serif）、wenkai（LXGW WenKai + Libertinus Serif）、pingfang（专用于CoreText引擎）。通过命令行参数即可一键切换，无需手动配置字体。
md2pdf如何解决表格跨页和代码块截断问题？
md2pdf的Typst引擎采用专业排版系统，分页时会考虑元素完整性，表格行不会被拆开，代码块若放不下会整体移到下一页，避免了浏览器打印引擎的截断问题。
md2pdf与md-to-pdf、Pandoc+LaTeX等工具有何区别？
md-to-pdf基于Chromium，分页会切断表格和代码块，且无法精确控制字体嵌入；Pandoc+LaTeX排版质量高但依赖庞大、配置复杂。md2pdf结合Typst和Pandoc，轻量快速，内置字体预设，双引擎设计解决了PingFang嵌入问题，更适合中文文档。
md2pdf有哪些使用限制或注意事项？
Typst引擎需要Pandoc 3.1.3以上版本，且需单独安装Typst；CoreText引擎需在macOS上编译，且需要图形会话，无法在纯SSH或CI环境运行；自定义字体需通过--font参数指定字体家族名称，用户需知道系统字体名。
md2pdf的PyPI包名是什么？为什么强调CJK？
md2pdf的PyPI包名是md2pdf-cjk，其中cjk代表中日韩文字，表明该工具从设计之初就将中日韩文字作为头等公民，专门为中文等CJK文字优化，而非简单支持。
