# mark2pdf 配置指南

本文档是 `mark2pdf` 的完整配置参考手册。

## 配置体系概览

mark2pdf 使用两层配置体系：

1.  **环境配置 (`mark2pdf.config.toml`)**: 管理工作区路径、构建行为、默认模板。
2.  **文档元数据 (`frontmatter.yaml` / 文件头)**: 管理文档内容、标题、出版信息。

---

## 1. 环境配置 (mark2pdf.config.toml)

此文件通常位于工作区根目录。

### 完整示例

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

[paths]
# 所有路径均相对于配置文件所在目录
input = "."             # Markdown 源文件目录 (默认当前目录)
output = "out"         # PDF 输出目录
tmp = ".tmp"           # 临时构建目录
template = "template"  # 本地模板目录
fonts = "fonts"        # 字体文件目录

[build]
default_template = "nb.typ"  # 默认模板
cover = true                 # 是否生成封面
overwrite = false            # 是否覆盖已存在的 PDF
filename_with_title = false  # true=使用标题作文件名, false=使用源文件名

[frontmatter]
#在此处定义的字段将作为全局默认值注入到所有文档中
#优先级：文件内 > frontmatter.yaml > config.toml
author = "默认作者"
```

---

## 2. 文档元数据 (Frontmatter)

你可以通过两个地方定义 Frontmatter：
1.  **`frontmatter.yaml`**: 工作区根目录，作用于所有文件。
2.  **文件头部 YAML**: 仅作用于当前 Markdown 文件 (优先级最高)。

### 基础元信息

```yaml
title: "示例文档"      # 文档标题 (封面/页眉)
author: "张三"        # 作者
date: "2026年1月"     # 日期 (封面底部)
description: "副标题"  # 描述/副标题 (封面中间)
```

### 出版信息 (pubinfo)

用于控制封面和版权页的详细信息。

```yaml
pubinfo:
  edition: "内部资料"         # 右上角系列标识
  info: "2026年第1版"         # 封面底部出版信息
  logo: ./images/logo.png    # 封面/封底 Logo (路径相对于 input 目录)
  watermark: "机密"           # 页面水印
  font: "SourceHanSerif"     # 指定正文字体
  titlefont: "SourceHanSans" # 指定标题字体
```

### 样式与行为

```yaml
template: "nb.typ"       # 指定使用的模板
exportFilename: "my-doc" # 自定义输出文件名 (不含后缀)
toc-depth: 3             # 目录显示层级 (默认 3)
overview-fill: "#E4F6F6" # Overview 页面背景色
```

### 页眉页脚 (headerfooter)

```yaml
headerfooter:
  headerleft: "左侧页眉文字"
  headerright: "右侧页眉 (默认标题)"
  footerleft: "左侧页脚"
  footerright: ![](images/qr.png)  # 支持图片 (注意不要加引号)
```

### 封面图 (heroimage)

```yaml
heroimage:
  image: ./images/cover.jpg  # 纯路径字符串
  caption: "封面图注"
```

### 功能禁用 (disables)

通过列表禁用特定组件：

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

---

## 常见配置场景

### 场景 A：纯文本报告 (无封面/无目录)

```yaml
---
disables:
  - cover
  - backcover
  - toc
---
```

### 场景 B：指定字体

```yaml
---
pubinfo:
  font: "LXGWWenKai"      # 正文用霞鹜文楷
  titlefont: "SimHei"     # 标题用黑体
---
```

### 场景 C：自定义封面背景

需配合 `darkbg` 样式（视模板支持而定）：

```yaml
---
theme:
  coverstyle: "darkbg"
  coverbg: "images/bg.jpg"
---
```
