# mark2pdf 工作区使用指南

本文档说明如何在独立工作区（如 `pdfdata`）中使用 mark2pdf。

## 1. 环境配置 (推荐)

为了获得最佳体验并简化后续命令，强烈建议先配置 `alias`。

将以下内容添加到你的 `~/.zshrc` 文件中：

```bash
# 1. 打开配置
nano ~/.zshrc

# 2. 添加 Alias (请修改 /Users/fangjun/python/mark2pdf 为你的实际代码路径)
alias mark2pdf="uv run --project /Users/fangjun/python/mark2pdf mark2pdf"

# 3. 保存并生效
source ~/.zshrc
```

**配置后的优势**：
- 无需每次输入冗长的 `uv run --project ...`
- 可以直接使用 `mark2pdf` 的所有子命令

---

## 2. 初始化工作区

### 使用简化命令 (推荐)

```bash
# 初始化指定目录
mark2pdf init /path/to/pdfdata

# 或者在当前目录初始化
cd /path/to/pdfdata
mark2pdf init .
```

> **注意**：必须在**空目录**中运行初始化。

---

**执行后将创建的标准结构**：
```
pdfdata/
├── mark2pdf.config.toml   # 配置文件（工作区标识）
├── frontmatter.yaml      # 默认 Frontmatter 配置（系统自动加载）
├── createpdf.py          # [高级] 自定义预处理脚本
├── in/                   # 输入文件目录
│   └── images/           # **图片目录（必须）**
├── out/                  # 输出文件目录
├── tmp/                  # 临时文件目录
└── template/             # 本地模板目录（可选）
```

> **图片约定**：所有图片必须放在 `in/images/` 目录中，Markdown 中使用 `images/xxx.png` 相对路径引用。

---

## 3. 运行转换

在工作区目录中，直接使用 `mark2pdf convert` 命令即可：

```bash
cd /path/to/pdfdata

# 默认转换 in/index.md
mark2pdf convert

# 转换指定文件
mark2pdf convert myfile.md

# 常用选项
mark2pdf convert --verbose          # 显示详细信息
mark2pdf convert --overwrite        # 覆盖输出文件
mark2pdf convert -t card.typ        # 指定模板（优先级最高）
mark2pdf convert --template nb.typ  # 同上，完整写法
mark2pdf convert --tc               # 转换为繁体中文
mark2pdf convert --dir docs         # 合并并转换整个目录

mark2pdf convert --help
```

**模板优先级**：`--template` 参数 > 配置文件 `default_template` > 默认值 `nb.typ`

---

## 4. 使用本地模板

将模板文件复制到 `pdfdata/template/` 即可优先使用：

```bash
# 复制系统模板到本地
mark2pdf template nb.typ
```

本地模板会**优先于**系统模板使用。

---

## 5. 配置文件说明

`mark2pdf.config.toml` 支持以下配置：

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

[paths]
in = "in"           # 输入目录
out = "out"         # 输出目录
tmp = "tmp"         # 临时目录
template = "template"
fonts = "fonts"     # 字体目录（可选）

[build]
default_template = "nb.typ"    # 默认模板（可被 --template 覆盖）
cover = true                   # 是否生成封面
overwrite = false              # 是否覆盖输出文件
filename_with_title = false    # 使用 frontmatter title 作为输出文件名
```

### 字体命令

```bash
mark2pdf fonts list
mark2pdf fonts install <font_name>
mark2pdf fonts status
```

默认安装到 `paths.fonts` 指定目录（默认 `fonts/`）。

> [!IMPORTANT]
> `default_template` 必须放在 `[build]` 下，不要误放到 `[paths]`！否则配置会被忽略。

---

## 6. 默认 Frontmatter 配置

在工作区根目录下创建 `frontmatter.yaml` 文件，其中的字段将自动注入到所有 Markdown 文件中（不会覆盖文件内已有的字段）。

**frontmatter.yaml 示例**：
```yaml
title: "示例文档"
author: "张三"
headerfooter:
  headerleft: "我的工作区"
```

系统会自动读取该文件，并将其传递给转换核心，确保每个文件都有默认的元数据。

---

## 7. 图片清理工具 (mdimage)

mark2pdf 内置了图片清理工具，用于下载 Markdown 中的网络图片到本地，并自动处理 Substack 等平台的特殊链接。

```bash
# 清理单个文件 (默认保存为 *_processed.md)
mark2pdf mdimage download in/index.md

# 清理单个文件并直接覆盖原文件
mark2pdf mdimage download in/index.md --overwrite

# 批量清理目录下的所有 .md 文件
mark2pdf mdimage download in/
```

结构迁移（单文件/文件夹模式互转）：
```bash
mark2pdf mdimage todir in/abc.md
mark2pdf mdimage tofile in/abc/
```

**功能说明**：
- **自动下载**：将 http/https 图片下载到 `images/<文件名>/` 目录。
- **链接重写**：自动更新 Markdown 中的图片链接为本地相对路径。
- **去重**：如果图片已存在（基于 URL 哈希），会自动跳过下载。
- **Substack 优化**：自动去除 Substack 的多余外层链接封装。
- **微信兼容**：微信图片下载失败时自动生成占位符，避免转换报错。

---

## 附录 A：[高级] 自定义预处理脚本

`createpdf.py` 是根据当前工作区配置生成的 Python 脚本。它允许你通过 Python 代码自定义 Markdown 的预处理逻辑。

### A.1 何时使用
如果你需要在转换前对 Markdown 内容进行特殊的正则替换、内容修正，可以使用此脚本。

### A.2 使用方法

编辑 `createpdf.py`，修改 `preprocess()` 函数：

```python
# createpdf.py 中的预处理区域

def preprocess(content: str) -> str:
    """
    工作区特定的预处理逻辑
    """
    # 示例：替换敏感词
    # content = content.replace("敏感词", "***")
    return content
```

运行自定义脚本：
```bash
# 直接运行脚本替代 mark2pdf convert
./createpdf.py [options]
```

### A.3 更新脚本

当 `mark2pdf` 核心代码更新后，`createpdf.py` 可能需要更新以保持兼容。

```bash
cd /path/to/pdfdata
mark2pdf update
```

> [!TIP]
> `update` 命令会自动背份旧脚本，并检查是否有实质变更。

---

## 附录 B：直接使用 Python API

如果需要在其他 Python 脚本中集成 mark2pdf：

```python
import os
os.chdir('/path/to/pdfdata')

from markdown2pdf import convert_file

convert_file('your_file.md', indir='in', outdir='out', verbose=True)
```
