# pdf-toc

**Repository Path**: clzbgl/pdf-toc

## Basic Information

- **Project Name**: pdf-toc
- **Description**: PDF 书签生成工具——自动识别章节结构，给没有目录的电子书加上可跳转的书签。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pdf-toc

> 自动提取 PDF 章节信息，生成书签（目录大纲）。

很多 PDF 电子书没有书签，阅读时无法快速跳转章节，非常不便。pdf-toc 通过分析 PDF 内部的文本字号和章节标题格式，自动识别章节结构，生成可导航的书签。

## 功能

- 🔍 **两种识别策略**：字号聚类法 + 正则匹配法，可单独或组合使用
- ✏️ **可编辑的中间产物**：导出为 Markdown 风格的目录文件，人工调整后写回
- ⚡ **全自动模式**：一条命令完成识别 + 写入
- 🌐 **中英文支持**：识别"第一章""Chapter 1""1.1 概述"等常见格式

## 安装

依赖 [PyMuPDF](https://pymupdf.readthedocs.io/)：

```shell
pip install PyMuPDF
```

然后下载 `pdf_toc.py` 即可使用，无需额外安装。

## 使用

### 全自动生成书签

最简单的用法，一条命令搞定：

```shell
python pdf_toc.py auto input.pdf output.pdf
```

### 预览识别效果

不想直接生成文件，先看看识别结果：

```shell
python pdf_toc.py preview input.pdf

# 只用字号法，指定最小字号阈值
python pdf_toc.py preview input.pdf --mode font --min-size 14

# 只用正则法
python pdf_toc.py preview input.pdf --mode regex
```

### 分步操作：导出 → 编辑 → 写回

如果自动识别不够准确，可以导出目录文件，人工调整后再写回：

```shell
# 第一步：导出目录文件
python pdf_toc.py extract input.pdf toc.txt

# 第二步：用任意文本编辑器打开 toc.txt，调整标题、页码、层级

# 第三步：把编辑好的目录写回 PDF
python pdf_toc.py apply input.pdf toc.txt output.pdf
```

### 页码偏移

很多 PDF 前面有封面、版权页、目录等未编号页，导致识别出的页码与 PDF 实际页码不一致。用 `--offset` 参数修正：

```shell
# PDF 第 5 页对应书上第 1 页（前面有 4 页未编号），偏移量为 4
python pdf_toc.py auto input.pdf output.pdf --offset 4
```

### 其他参数

```shell
# 保留 PDF 原有书签，将识别结果追加进去
python pdf_toc.py auto input.pdf output.pdf --keep-existing

# 查看版本
python pdf_toc.py --version
```

## 识别原理

### 策略一：字号聚类法

扫描每页的文本块，收集所有字号。出现频率最高的字号大概率是正文字号，明显大于正文的文本行则被识别为标题。按字号从大到小映射为书签层级（最大 → 1 级，次大 → 2 级……）。

适合：排版规范的 PDF，标题字号与正文字号有明显差异。

### 策略二：正则匹配法

逐页扫描文本行，匹配常见的章节标题格式：

| 模式 | 层级 | 示例 |
|------|------|------|
| `第X编` | 1 | 第一编 基础理论 |
| `第X部分` | 1 | 第一部分 概述 |
| `第X章` | 1 | 第三章 数据结构 |
| `第X节` | 2 | 第二节 应用 |
| `Chapter X` | 1 | Chapter 5 Methods |
| `Part X` | 1 | Part III Results |
| `X.Y.Z 标题` | 3 | 1.2.3 实验设计 |
| `X.Y 标题` | 2 | 2.1 研究背景 |
| `X 标题` | 1 | 3 系统架构 |

适合：章节标题格式规范的 PDF，尤其是学术著作和教材。

默认两种策略同时启用（`--mode both`），结果合并去重。

## 目录文件格式

导出的目录文件是纯文本，Markdown 标题风格，任何编辑器都能打开：

```
# 第一章 概论                1
## 1.1 背景                  2
## 1.2 意义                  5
# 第二章 方法                10
### 2.1.1 实验设计            12
```

规则：

- `#` 的个数 = 书签层级（1 个 `#` = 1 级，2 个 `#` = 2 级……）
- 每行最后一个数字 = 跳转页码（Tab 或多个空格分隔均可）
- 删除某行 = 删除该书签
- 新增一行 = 新增书签
- 调整 `#` 数量 = 调整层级

## 许可证

[MIT](LICENSE)