# mark2pdf 配置指南

本文档描述 `mark2pdf` 项目的完整配置体系。

---

## 配置文件分工

两个配置文件，职责分明：

| 文件 | 职责 | 典型内容 |
|------|------|----------|
| `mark2pdf.config.toml` | 环境/构建配置 | 路径、模板、覆盖选项 |
| `frontmatter.yaml` | 文档元数据 | 标题、样式、禁用项 |

**归类原则**：路径/环境 → `config.toml`，文档内容/行为 → `frontmatter.yaml`

---

## mark2pdf.config.toml

```toml
project_name = "MyProject"

[paths]
input = "_working/in"
output = "_working/out"
tmp = ".tmp"
template = "template"
fonts = "fonts"

[options]
default_template = "nb.typ"
overwrite = false

[frontmatter]
# 可选：全局 frontmatter 默认值（最低优先级）
```

---

## Frontmatter 配置

### 配置层级（优先级从低到高）

1. **config.toml [frontmatter]** — 全局默认
2. **frontmatter.yaml** — 工作区默认
3. **index.md frontmatter** — 目录级默认（批量模式）
4. **文件 frontmatter** — 最高优先级

> **深度合并**：嵌套结构（`pubinfo`、`headerfooter`）支持部分覆盖，不会丢失未指定的子字段。

---

### 输出控制

| 字段 | 类型 | 说明 |
|------|------|------|
| `template` | string | 模板文件名，如 `nb.typ` |
| `exportFilename` | string | 输出文件名（无需后缀） |

**文件名优先级**：`exportFilename` > `title` > 原始 md 文件名

---

### 禁用项 disables

统一控制功能开关：

```yaml
disables:
  - cover       # 禁用封面与封底
  - backcover   # 仅禁用封底
  - toc         # 禁用目录
  - indent      # 禁用首行缩进
  - pagenumber  # 禁用页码
  - header      # 禁用页眉
```

不写 `disables` = 全部启用。

---

### 文档元信息

| 字段 | 类型 | 说明 |
|------|------|------|
| `title` | string | 文档标题 |
| `description` | string | 描述（封面） |
| `author` | string | 作者 |
| `date` | string | 日期 |
| `sourcelink` | string | 目录页底部来源信息 |

---

### 出版信息 pubinfo

```yaml
pubinfo:
  edition: "AI 未来学校"      # 系列名称（封面右上角）
  info: "2026年1月出版"       # 出版信息（封面底部）
  logo: ./images/qr.png       # 封面/封底 logo
  font: "SourceHanSerif"      # 正文字体
  titlefont: "SourceHanSans"  # 标题字体
  watermark: "张华读书会"      # 页面水印
```

---

### 封面图 heroimage

```yaml
heroimage:
  image: ./images/cover.jpg   # 纯路径，不加 ![]()
  caption: "封面图注"          # 纯文本
```

> ⚠️ `image` 是**纯路径字符串**，不要用 Markdown 图片语法。

---

### 页眉页脚 headerfooter

```yaml
headerfooter:
  headerleft: "AI 未来学校"          # 文字：加引号
  headerright: "自定义右侧"          # 文字：加引号（缺省为 title）
  footerleft: "页脚左侧"             # 文字：加引号
  footerright: ![](images/qr.png)   # 图片：Markdown 语法，不加引号！
```

> ⚠️ 图片必须用 `![](path)` 语法且**不加引号**，加引号会显示为字面文字。

---

### 其他

| 字段 | 类型 | 说明 |
|------|------|------|
| `toc-depth` | number | 目录深度（默认 3） |
| `overview-fill` | string | overview 块背景色 |

---

## 完整示例

```yaml
---
title: "AI 时代的教育变革"
author: "张三"
date: "2026年1月"
description: "探索人工智能如何重塑教育形态"
template: nb.typ
exportFilename: ai-education
pubinfo:
  edition: "AI 未来学校"
  info: "2026年1月第一版"
  logo: ./images/logo.png
  font: "SourceHanSerif"
  titlefont: "SourceHanSans"
  watermark: "内部资料"
heroimage:
  image: ./images/cover.jpg
  caption: "未来课堂"
headerfooter:
  headerleft: "AI 未来学校"
  footerright: ![](images/qr.png)
toc-depth: 2
overview-fill: lightblue
disables:
  - backcover
---
```

---

## 历史字段（不再支持）

| 废弃字段 | 替代方案 |
|----------|----------|
| `edition` | `pubinfo.edition` |
| `publication-info` | `pubinfo.info` |
| `logo` | `pubinfo.logo` |
| `tyfont` | `pubinfo.font` |
| `tyfont_title` | `pubinfo.titlefont` |
| `watermark` | `pubinfo.watermark` |
| `no-toc` | `disables: [toc]` |
| `no-indent` | `disables: [indent]` |
| `no-pagenumber` | `disables: [pagenumber]` |
| `nocover` / `withcover` | `disables: [cover]` |
| `leftheader` | `headerfooter.headerleft` |
| `footer-image` | `headerfooter.footerright` |
