# Typst 字体方案

## 问题

项目使用的中文字体（如 `Source Han Sans SC`）依赖系统安装，用户系统没装会编译失败。

## Typst 字体机制

- 默认从系统字体目录加载
- 可通过 `--font-path` 指定额外字体目录
- pandoc 调用时用 `--pdf-engine-opt="--font-path=./fonts"`

## 推荐方案（重新整理）

**以路径为核心，提供 fonts 命令辅助下载**：用户可直接下载到指定目录，运行时自动加入 Typst font-path。

优先级建议：
1. `mark2pdf.config.toml` 的 `paths.fonts`（默认 `fonts/`）
2. 模板同级 `fonts/`（便于模板自带字体）
3. 独立模式下当前目录 `fonts/`（存在时启用）

```
workspace/
├── fonts/
│   └── SourceHanSansSC-Regular.otf
├── in/
│   └── article.md
├── template/
│   └── nb.typ
└── mark2pdf.config.toml
```

**配置示例：**

```toml
[paths]
fonts = "fonts"          # 相对工作区根目录
# fonts = "/abs/path"    # 也可使用绝对路径
```

## 字体命令

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

## 实现要点

1. **检测字体目录**：读取 `paths.fonts`，并补充模板同级 `fonts/`
2. **传递路径**：调用 pandoc 时添加 `--pdf-engine-opt="--font-path=<dir>"`
3. **网络加载**：`fonts install` 从 GitHub Releases 下载字体并安装到 `fonts/`

## 手动测试方案（按步执行）

目标：验证字体目录优先级（`paths.fonts` → 模板同级 `fonts/` → 独立模式 `./fonts`）。

### 0. 准备字体与工作区

1. **初始化一个干净工作区**
   ```bash
   mkdir -p /tmp/mark2pdf-font-ws
   cd /tmp/mark2pdf-font-ws
   mark2pdf init .
   mark2pdf template nb.typ
   ```

2. **确认配置包含 fonts 路径**
   ```bash
   # 确认 [paths] 中有 fonts = "fonts"（老工作区请手动补上）
   rg -n "fonts" mark2pdf.config.toml
   ```

3. **准备一个本机未安装字体**（示例：悠哉字体）
   ```bash
   # 使用内置命令下载安装到工作区 fonts/
   mark2pdf fonts install yozai
   ```

4. **创建测试 Markdown**
   ```bash
   cat > in/font_test.md << 'EOF'
   ---
   title: 字体测试
   tyfont: "Yozai"
   ---
   
   # 测试标题
   
   这是一段中文测试文本，用于验证字体加载是否成功。
   EOF
   ```

### 1. 场景 A：使用 `paths.fonts`

1. **运行转换**
   ```bash
   mark2pdf convert font_test.md --verbose
   ```

2. **对比基线**
   ```bash
   mv fonts fonts.bak
   mark2pdf convert font_test.md --verbose
   mv fonts.bak fonts
   ```

3. **对比输出结果**：
   - 若无 fonts 时转换失败（如报字体缺失），属于预期。
   - 若成功生成 PDF，字体应明显不同（可打开 `out/` 下的两个文件对比）。

### 2. 场景 B：使用模板同级 `fonts/`

1. **清空工作区 fonts，改放到模板同级**
   ```bash
   rm -rf fonts
   mkdir -p template/fonts
   cp /tmp/mark2pdf-font-ws/fonts/*.ttf template/fonts/
   ```

2. **运行转换**
   ```bash
   mark2pdf convert font_test.md --verbose
   ```

### 3. 场景 C：独立模式 `./fonts`

1. **准备独立目录（无 mark2pdf.config.toml）**
   ```bash
   mkdir -p /tmp/mark2pdf-font-standalone
   cd /tmp/mark2pdf-font-standalone
   mkdir -p fonts
   cp /tmp/mark2pdf-font-ws/fonts/*.ttf fonts/
   cat > test.md << 'EOF'
   ---
   title: 字体测试
   tyfont: "Yozai"
   ---
   
   # 测试标题
   EOF
   ```

2. **运行转换**
   ```bash
   mark2pdf convert test.md --verbose
   ```

### 预期结果

| 场景 | 预期 |
|------|------|
| A：工作区 `paths.fonts` | 使用 Yozai 字体（与无 fonts 情况明显不同） |
| B：模板同级 `fonts/` | 使用 Yozai 字体 |
| C：独立模式 `./fonts` | 使用 Yozai 字体 |

## 伪代码

```python
# 获取字体路径（按优先级）
def get_font_paths(workspace_root, template_path):
    font_paths = []
    fonts_dir = workspace_root / "fonts"
    if fonts_dir.exists():
        font_paths.append(str(fonts_dir))
    template_fonts = Path(template_path).parent / "fonts"
    if template_fonts.exists():
        font_paths.append(str(template_fonts))
    return font_paths

# 调用 pandoc 时添加
for path in get_font_paths(workspace_root, template_path):
    cmd.extend(["--pdf-engine-opt", f"--font-path={path}"])
```
