# PDF To Markdown

> 将 PDF 批量转换为 Markdown（.md）文件。用户提到"PDF转md/markdown"、"批量转换PDF"、"把电子书转成md"、"提取PDF文本为markdown"、"处理这个PDF"、"把PDF整理成可阅读的文本"等需求时使用。转换前自动检测 PDF 是否有文本层：带文本层的秒级提取，纯扫描版明确提示需 OCR 并跳过。适合电子书、技术文档、报告、论文等 PDF 的文本提取与归档。

- Skill: `share-budaozhe/pdf-to-markdown` (Agent Skill)
- Install (CLI): `npx skillmds@latest add share-budaozhe/pdf-to-markdown`
- Raw SKILL.md: https://api.skillmd.com/api/skills/share-budaozhe/pdf-to-markdown/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Author: share-budaozhe (https://skillmd.com/u/share-budaozhe)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/share-budaozhe/pdf-to-markdown

---


# PDF → Markdown 批量转换

将目录下的 PDF 转为 Markdown 文件，输出到 `md/` 目录（或用户指定目录）。

## 核心思路

PDF 分两类，处理方式截然不同：

- **数字版 PDF**（内嵌文本层）：可秒级提取文本，几秒到 1 分钟即可转换整本。
- **扫描版 PDF**（纯图片、无文本层）：必须 OCR 才能得到文字，速度慢（CPU 上每页数分钟）且需下载模型。本 skill 只做文本提取，扫描版会明确列出并跳过。

**因此第一步永远是花几秒检测文本层**，而不是直接上重型工具——这能避免把几秒能完成的事拖成几小时。

## 前置条件

- Python + `pypdfium2`。先检查：`python -c "import pypdfium2"`；缺失则 `pip install pypdfium2`。

## 执行步骤

### 1. 确认输入与输出

- 输入目录：工作目录，或用户指定的目录。
- 输出目录：默认 `<输入目录>/md/`，用户指定则用指定的。
- 列出所有 `*.pdf`，向用户汇报数量。

### 2. 运行提取脚本

执行随 skill 提供的 `scripts/extract_text.py`：

```
python <skill目录>/scripts/extract_text.py --input <目录> [--output <目录>]
```

脚本自动完成：检测每本 PDF 的文本层 → 数字版提取为 md → 扫描版跳过并列入报告。无需手动逐本处理。

### 3. 处理报告

脚本会输出报告，类似：

```
[转换] 某某书.pdf  (445 页, 95 页无文本)...
[完成] 某某书.md  (127 KB, 445 页)
[扫描版/跳过] 某某扫描书.pdf  （349 页，349 页无文本，需 OCR）
```

- 对扫描版，向用户说明："该 PDF 无文本层，需 OCR 工具（如 marker）才能提取文字，本 skill 仅做文本提取、不包含 OCR。"
- 若用户明确要求转换扫描版，告知这超出本 skill 范围，可考虑其他 OCR 方案。

### 4. 验证

- 抽查 1-2 页输出，确认文本完整、无乱码、段落正常。
- 核对 md 文件页标记数与源 PDF 页数一致（脚本报告里已有，页面标记 `<!-- page N -->` 数量应等于总页数）。

## 输出格式

- 文件命名：`<原PDF名>.md`，编码 **UTF-8**。
- 结构：

```
# <书名>

<!-- page 1 -->
<第 1 页文本>

---

<!-- page 2 -->
<第 2 页文本>
```

- 无文本/图像页标注：`<!-- page N（无文本/图像页） -->`。
- **取舍说明**：快速提取保留原文与段落，但表格、代码块、公式的排版会被简化。若用户需要精确还原版式（复杂表格、代码结构），需用 OCR 型工具（如 marker），应明确告知这一权衡，让用户决定是否接受。

## 环境注意

- Windows 控制台默认 GBK 编码，打印含特殊 Unicode 字符的文本会报 `UnicodeEncodeError`。脚本内已用 `sys.stdout.reconfigure(encoding="utf-8", errors="replace")` 处理；若另写代码也要注意。
- 写文件始终显式指定 `encoding="utf-8"`。