Markdown2PDF：GitHub

22次阅读

获取下载链

微信关注「软件教程管家」公众号，回复 markdown2pdf

30秒速读

Markdown2PDF 是一个 GitHub Action：在工作流里加几行配置，就能把仓库里的 Markdown 自动转成 PDF。单文件输入生成单个 PDF，文件夹输入递归转换并按原目录结构打包成 ZIP。生成的 PDF 采用 PDF 2.0 标准并符合 PDF/UA-2 无障碍规范，适合文档构建、版本归档和发布可访问文档。但要注意三个硬限制：只跑在 Linux x86_64 的 runner 上、只接受公开仓库（会调 GitHub API 校验可见性）、转换器二进制本身是闭源的（包装代码 MIT 开源）。项目 2026 年 10 月初才创建，非常新，评估前建议看一眼仓库动态。

项目信息

项目名称	Markdown2PDF（itext/markdown2pdf-gh-action）
仓库地址	见文末开源地址按钮
开源协议	Action 包装代码 MIT；捆绑的转换器二进制为闭源限用许可（据仓库说明，见下文）
项目形态	GitHub Actions 复合 Action，非本地独立软件
运行环境	Linux x86_64 runner（如 ubuntu-latest），据仓库说明
输出格式	PDF 2.0，符合 PDF/UA-2，据仓库说明
项目状态	2026 年 10 月创建，仓库显示 34 star、3 个版本（据仓库信息）

核心功能

两种输入模式：单个 Markdown 文件生成一个 PDF；文件夹输入递归处理其中所有 .md 文件，生成保留原目录结构的 ZIP（含单个 .md 也会走 ZIP）。
生成的 PDF 使用 PDF 2.0 并符合 PDF/UA-2：Markdown 自带的标题、列表、表格、链接、替代文本等语义会被转成带标签的无障碍 PDF，满足最新 ISO 无障碍标准。
转换器随仓库一起提交（bin/itext-markdown2pdf），运行时不需要下载外部程序，减少构建时的网络依赖。
输出三个可用的工作流变量：生成文件的绝对路径、输出类型（pdf/zip）、生成的 PDF 数量，方便后续步骤引用。
示例覆盖常见排版：嵌套列表、图片与题注、代码块语法高亮、GitHub 告警块、徽章横幅、表情符号等，README 里有流行仓库 README 转换前后的对照截图。
配套 actions/upload-artifact 可把生成文件保存为工作流构件，供运行后下载归档；不配上传步骤的话 runner 回收后文件就没了。

上手指南

在你的公开仓库里新建工作流文件，job 至少保留 contents: read 权限（转换器要用默认 GITHUB_TOKEN 做仓库可见性校验）。
runner 指定 runs-on: ubuntu-latest；先用 actions/checkout@v4 拉取代码，再加一步 uses: itext/markdown2pdf@v1，填 input（文件或文件夹路径）和 output（目标文件路径，注意扩展名要与输入模式匹配：文件输入配 .pdf，文件夹输入配 .zip）。
后面跟一步 actions/upload-artifact@v4，把上一步输出的 output-path 传进去，构件就会出现在工作流运行页的 Artifacts 区。
自托管 runner 需要预装 Bash、GNU coreutils、findutils 和 zip 并在 PATH 里；ARM 架构 runner 不支持。
常见报错可直接对表：提示仓库不公开就是私有仓库被拒；提示 requires an x86_64 runner 就是用了 ARM runner；文件夹里没有 .md 文件会直接失败而不是产出空包。

同类对比与适用边界

把 Markdown 转 PDF 的路线有三条：本地工具链（如 Pandoc、md-to-pdf）灵活可控、离线可用，但要自己装环境、调模板；在线转换服务零配置，但文档要上传到第三方、批量和自动化都弱；CI 集成型（如本项目）把转换嵌进发布流水线，文档一提交就自动出 PDF，代价是强绑定 GitHub Actions 生态。Markdown2PDF 的明确取舍是”为流水线而生”：它不做本地命令行、不做多格式输入，把全部精力押在”仓库提交即出无障碍 PDF”这一个场景上。另一个必须知道的取舍是许可：包装代码 MIT 开源，但真正干活的转换器二进制是闭源的，限用许可只允许配合这个官方 Action 使用——能接受”核心黑盒”再用。

适合：在 GitHub Actions 里自动生成文档 PDF 的开源项目维护者；需要批量把文档目录转成带目录结构的 PDF 压缩包做归档的团队；对 PDF 无障碍合规（PDF/UA-2）有要求的文档发布流程。不适合：私有仓库（会被可见性校验拒绝）；非 Linux x86_64 环境；想要一个本地命令行工具随手转 PDF 的用户——这类需求建议用 Pandoc 一类本地工具。

常见问题

Q：私有仓库能用吗？
A：不能。据 README，转换器会通过 GitHub API 校验仓库可见性，非公开仓库直接拒绝运行。这是硬限制，没有变通办法。

Q：转换器二进制闭源，会影响使用吗？
A：据仓库许可说明，Action 的包装代码（Java 封装、脚本、测试、文档）是 MIT，但 bin/itext-markdown2pdf 这个二进制是闭源的”限用许可”，只允许配合这个官方 Action 使用，不授予在外部分发或他用的权利。能接受核心黑盒再用，介意的话建议看仓库的 NOTICE 和 THIRD-PARTY-NOTICES 了解依赖清单。

Q：生成的文件会自动保留吗？
A：不会。Action 只是在 runner 的工作区里生成文件，runner 回收文件就没了。必须自己再加一步 actions/upload-artifact 把文件传成构件，才能在工作流运行页下载。

Q：文件夹输入里已经有 PDF，会被一起打包吗？
A：不会。据 README，只有本次转换生成的 PDF 会进 ZIP，输入文件夹里原有的 PDF 不会被复制；成功运行会覆盖目标文件，转换失败则保持原目标不变。

Q：中文 Markdown 转出来会乱码吗？
A：未实测。据 README 的示例覆盖了代码高亮、表情符号等排版，但未明确说明中文字体嵌入情况；中文文档建议先跑一次试转换，检查字体和排版再正式纳入流水线。