# mark2pdf 项目说明文档

> 更新日期：2026-01-01
> 目标：介绍当前 mark2pdf 的模块结构、工作模式与配置系统

---

## 一、项目概述

**mark2pdf** 是基于 Pandoc + Typst 的 Markdown → PDF 工具链，提供命令行与可编程 API。

核心特点：
- 工作区模式：通过 `mark2pdf.config.toml` 管理输入输出、模板与默认配置
- 独立模式：无配置文件也可在当前目录直接转换
- 模板系统：内置 Typst 模板 + 工作区本地模板覆盖
- 图片与后处理：`mdimage` 图片清理/迁移，`postprocess` 可插拔链

> 包名仍为 `markdown2pdf`（PyPI），命令行入口为 `mark2pdf`。

---

## 二、目录结构

```text
mark2pdf/
├── src/
│   ├── mark2pdf/             # CLI + 工作区管理
│   ├── markdown2pdf/         # 核心转换 API
│   ├── postprocess/          # 内置后处理器
│   ├── helper_markdown/      # 预处理与 frontmatter 工具
│   ├── helper_typst/         # Pandoc/Typst 管线
│   ├── helper_mdimage/       # 图片下载与迁移
│   ├── helper_workingpath/   # 路径与模板解析
│   ├── helper_interfile/     # 沙箱/临时文件管理
│   └── helper_gaozhi/        # 稿纸排版预处理
├── template/                 # 内置 Typst 模板
├── scripts/                  # 兼容/辅助脚本
├── _logs/                    # 方案、报告与文档
└── pyproject.toml            # 依赖与打包配置
```

---

## 三、核心模块说明

### 3.1 mark2pdf（CLI 与工作区）
- `cli.py`: CLI 入口（`mark2pdf`）
- `commands/`: 子命令（`init`/`update`/`mdimage`/`gaozhi`/`clean` 等）
- `config_loader.py`: 配置加载与模板解析
- `workspace_manager.py`: 工作区初始化与更新
- `conversion.py`: CLI 转换调度（单文件/目录/批量）
- `reporter.py`: `--show-config` / `--dry-run` 输出

### 3.2 markdown2pdf（核心转换 API）
- `convert_file` / `convert_directory`: 可编程调用入口
- `ConversionOptions`: 转换参数封装
- 沙箱执行：临时目录写入 + `images/` 链接 + Pandoc 调用

### 3.3 postprocess（内置后处理器）
- `remove_links`: 移除链接，保留文本
- `to_traditional_chinese`: 简繁转换

### 3.4 helper_*（基础能力）
- `helper_markdown`: 预处理链、frontmatter 提取
- `helper_typst`: Typst 依赖解析与编译
- `helper_mdimage`: 图片下载与结构迁移
- `helper_workingpath`: 路径解析与模板定位
- `helper_interfile`: 沙箱与临时文件管理
- `helper_gaozhi`: 稿纸排版预处理

---

## 四、工作模式

### 4.1 工作区模式（推荐）
- 工作区目录包含 `mark2pdf.config.toml`
- 输入/输出/模板路径由 `[paths]` 指定
- 自动读取 `frontmatter.yaml` 作为默认 frontmatter

### 4.2 独立模式（无配置）
- 在当前目录直接执行 `mark2pdf convert` / `mark2pdf gaozhi`
- 默认：输入/输出为当前目录，临时目录为 `.mark2pdf_tmp`
- `clean` / `update` 仍要求工作区

配置文件向上查找（CWD → 父目录），未找到则进入独立模式。

---

## 五、配置系统

### 5.1 mark2pdf.config.toml（工作区配置）

```toml
[project]
name = "我的项目"

[paths]
in = "in"
out = "out"
tmp = "tmp"
template = "template"

[build]
default_template = "nb.typ"
cover = true
overwrite = false
filename_with_title = false

[frontmatter]
author = "张三"
```

### 5.2 frontmatter.yaml（默认 frontmatter）
- 位于工作区根目录
- 与 `[frontmatter]` 合并（文件内字段优先）

---

## 六、常用命令概览

```bash
mark2pdf init <dir>         # 初始化工作区
mark2pdf update             # 更新 createpdf.py
mark2pdf convert <file>     # 单文件转换
mark2pdf convert --dir <d>  # 合并目录转换
mark2pdf convert --batch .  # 批量转换
mark2pdf mdimage download <path>
mark2pdf gaozhi <file|--dir>
mark2pdf coverprepare check <image>
mark2pdf clean
```

---

## 七、测试与开发

```bash
# 运行全部测试
uv run pytest

# 只跑核心测试
uv run pytest src/markdown2pdf/tests/ src/mark2pdf/tests/
```

建议开发时关注：
- 配置加载与路径解析
- 模板依赖解析与沙箱清理
- 预处理链与后处理器组合
