# mark2pdf 项目说明文档

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

---

## 一、项目概述

**yakultpdf** (PyPI 包名 `yakultpdf`) 是基于 Pandoc + Typst 的 Markdown → PDF 工具链。

核心特点：
- **工作区模式**：目录包含 `mark2pdf.config.toml` (配置文件仍沿用内部包名)。通过此文件定义项目特定的输入/输出路径、默认模板等环境配置。
- **独立模式**：无配置文件，默认在当前目录进行转换。
- **模板系统**：内置 Typst 模板 + 工作区本地模板覆盖。
- **图片与后处理**：内置 `mdimage` 图片清理/迁移，支持自动化图片下载。

---

## 二、目录结构

```text
mark2pdf/
├── src/
│   ├── mark2pdf/
│   │   ├── cli.py                # CLI 入口 (yakultpdf)
│   │   ├── commands/             # 子命令 (init, convert, etc.)
│   │   ├── config/               # 配置加载与管理
│   │   ├── core/                 # 核心转换逻辑
│   │   ├── helper_markdown/      # Markdown 预处理
│   │   ├── helper_typst/         # Typst 编译与依赖
│   │   ├── helper_mdimage/       # 图片下载与管理
│   │   ├── helper_workingpath/   # 路径解析
│   │   ├── helper_interfile/     # 中间文件处理
│   │   └── helper_gaozhi/        # 稿纸模式专用逻辑
├── template/                     # 内置 Typst 模板
└── pyproject.toml                # 项目配置
```

---

## 三、核心模块说明

### 3.1 CLI 与命令 (`commands/`)
- `workspace.py`: 处理 `init` 和 `template` 命令。
- `convert.py`: 处理转换逻辑调度。
- `mdimage.py`: 图片下载工具。
- `fonts.py`: 字体管理。

### 3.2 配置系统 (`config/`)
- `loader.py`: 加载 `mark2pdf.config.toml` 和 `frontmatter.yaml`。
- `workspace.py`: 工作区初始化与模板安装逻辑。
- `defaults.py`: 系统默认配置。

### 3.3 核心逻辑 (`core/`)
- `core.py`: 转换流程的主入口 (`convert_file`, `convert_directory`)。
- `conversion.py`: 具体的转换步骤实现。

### 3.4 辅助模块 (`helper_*`)
- `helper_markdown`: 处理 frontmatter 提取、内容预处理。
- `helper_mdimage`: 核心功能之一，负责从 Markdown 中提取、下载并替换图片链接。
- `helper_typst`: 调用 Typst CLI 进行编译。

---

## 四、工作模式

### 4.1 工作区模式（推荐）
- 目录包含 `mark2pdf.config.toml`。
- 推荐结构：Markdown 文件放在根目录或子目录，图片统一放在 `images/`。
- `yakultpdf convert` 自动读取配置。

### 4.2 独立模式
- 任意目录下直接运行 `yakultpdf convert file.md`。
- 默认在当前目录生成 PDF。

Config Loader 会自动向上查找配置文件，如果找到则进入工作区模式，否则为独立模式。

---

## 五、配置系统

### 5.1 mark2pdf.config.toml
环境配置文件，定义路径和默认行为。

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

[paths]
input = "."        # 输入目录（默认为当前目录）
output = "out"     # 输出目录
tmp = "tmp"        # 临时文件
template = "template"

[build]
default_template = "nb"
overwrite = false
```

### 5.2 frontmatter.yaml
文档元数据文件，定义标题、作者、样式等。

---

## 六、常用命令

```bash
yakultpdf init .            # 初始化工作区
yakultpdf convert           # 转换文档
yakultpdf fonts install     # 安装字体
yakultpdf mdimage download  # 下载图片
```

