yakultpdf (mark2pdf)

基于 Pandoc 和 Typst 的 Markdown 转 PDF 专业工具链

一个强大的文档转换工具，旨在将 Markdown 文件转换为排版精美的 PDF 文档。它支持类似 Hugo/Jekyll 的工作区管理、Frontmatter 配置以及高度可定制的 Typst 模板系统。

注意: 本项目在 PyPI 上包名为 yakultpdf，导入模块时使用 mark2pdf，命令行工具名为 yakultpdf。

系统依赖

在安装之前，请确保已安装以下系统依赖：

• Pandoc - 通用文档转换工具
• Typst - 现代排版系统

macOS 安装

brew install pandoc typst

Linux 安装

# Ubuntu/Debian
sudo apt-get install pandoc typst

# 或使用 cargo 安装 typst
cargo install typst-cli

快速开始

1. 安装

pip install yakultpdf

2. 初始化工作区 (推荐)

我们强烈建议使用工作区模式来管理你的文档项目：

mkdir my-docs && cd my-docs
yakultpdf init .

这将创建标准目录结构 (in/, out/, mark2pdf.config.toml 等)。

3. 开始转换

将 Markdown 文件放入 in/ 目录，然后运行：

yakultpdf convert

生成的 PDF 将出现在 out/ 目录中。

4. 封面开关

默认不生成封面。

可以用三种方式开启：

# CLI 显式开启
yakultpdf convert test.md --with-cover

# mark2pdf.config.toml
[options]
withcover = true

# frontmatter.yaml 或文件头
theme:
  withcover: true

优先级是：CLI > 单文件 YAML 头 > frontmatter.yaml > config > 默认关闭。
只要显式传了 --with-cover 或 --no-cover，CLI 就会覆盖文件头、frontmatter.yaml、disables: [cover] 和 config。
只有没传 CLI 时，disables: [cover] 才会按禁用处理。

5. 目录模式 title/image 自动注入

当使用 yakultpdf convert --dir <目录> 时：

• 会读取 index.md 与各子文件 frontmatter 的 title / image。
• image 会自动注入为 topimage 块：

::: {#topimage}
images/cover.jpg
:::

• title 会自动注入为 H1 标题（# 标题）。
• 该行为仅在目录模式生效，默认开启。
• 如需关闭，在 index.md frontmatter 配置：

disables:
  - title_injection

• 若只想关闭 index 的题图注入（保留 index 标题和子文件注入）：

disables:
  - index_image

文档导航

所有详细文档均位于 ./docs 目录：

• 入门必读: 💪 工作区使用指南 - 最佳实践、环境配置与工作流。
• 命令手册: 🛠 CLI 使用说明 - 所有命令参数详解。
• 配置参考: ⚙️ 配置指南 - config.toml、封面开关与 Frontmatter 参数全解。
• 模板语法: 🎨 模板语法指南 - 如何使用高级排版特性（NB模板）。
• 架构说明: 🏗 项目说明文档 - 开发者视角的设计文档。
• 常见问题: ❓ FAQ - 疑难解答。

核心特性

• 工作区管理: 自动管理输入输出路径、模板与资源。
• 智能图片处理: 自动下载远程图片、微信公众号图片修复、本地路径重写。
• 混合排版: 支持标准 Markdown 与 Typst 语法混合使用。
• 多模式转换: 支持单文件转换、目录合并转换、批量转换。
• 中文优化: 内置简繁转换、常用中文字体下载与管理。
• 稿纸模式: 特有的 gaozhi 转换器，生成书写练习稿纸。

Python API

也可以在 Python 代码中直接使用（注意导入模块名为 mark2pdf）：

from mark2pdf import convert_file, convert_directory

# 单文件转换
convert_file("input.md", output_file="output.pdf")

# 目录转换（合并目录下所有 Markdown）
convert_directory("docs", output_file="merged_report.pdf")