tools/ptm/README.md

ptm - PDF to Markdown Converter

一个简单易用的命令行 PDF 转 Markdown 工具。

✨ 功能特性

• 📄 PDF 文本提取: 从 PDF 文件中提取纯文本内容
• 📝 Markdown 转换: 将提取的文本转换为 Markdown 格式
• 💾 灵活输出: 支持原地生成或指定输出路径
• 📋 剪贴板支持: 可直接复制生成的 Markdown 到剪贴板

📦 安装

从源码编译

cd ptm
cargo build --release

全局安装

cargo install --path . --force

安装后可直接使用 ptm 命令。

🚀 使用方法

基本格式:

ptm <PDF文件> [选项]

命令示例

1. 基本用法（原地生成）

# 将 test.pdf 转换为 test.md（同一目录）
ptm test.pdf

2. 指定输出路径

# 输出到指定位置
ptm test.pdf -o output/result.md

# 使用完整路径
ptm document.pdf -o C:\Users\macro\Documents\notes.md

3. 复制到剪贴板

# 转换并复制到剪贴板
ptm test.pdf -v

# 指定输出并复制
ptm test.pdf -o result.md -v

参数说明

参数	说明	示例
<INPUT>	PDF 文件路径（必需）	test.pdf
-o, --output	输出文件路径（可选，默认与输入同名）	-o result.md
-v, --verbose	复制内容到剪贴板	-v
-h, --help	显示帮助信息	-h
-V, --version	显示版本信息	-V

💡 使用场景

场景 1: 快速转换 PDF

ptm report.pdf
# 生成 report.md

场景 2: 批量处理

# PowerShell 批量转换
Get-ChildItem *.pdf | ForEach-Object {
    ptm $_.FullName
}

场景 3: 转换后直接粘贴

ptm article.pdf -v
# 现在可以直接在编辑器中 Ctrl+V 粘贴

场景 4: 自定义输出位置

ptm book.pdf -o notes/book-chapter1.md

📊 工作原理

1. 读取 PDF: 使用 pdf-extract 库解析 PDF 文件
2. 提取文本: 提取 PDF 中的所有文本内容
3. 格式转换:
   • 清理多余空行
   • 保留段落结构
   • 转换为纯文本 Markdown
4. 写入文件: 保存为 .md 文件
5. 可选复制: 如指定 -v,复制到剪贴板

⚠️ 注意事项

1. 文本型 PDF: 仅支持包含文本层的 PDF，扫描版 PDF 需要 OCR 处理
2. 格式限制: 当前版本主要提取纯文本，复杂格式（表格、图片）可能需要手动调整
3. 编码支持: 支持 UTF-8 编码，包括中文等多语言内容
4. 文件大小: 大文件可能需要较长时间处理

🔧 技术细节

依赖库

• pdf-extract: PDF 文本提取库
• clap: 命令行参数解析
• clipboard-win: Windows 剪贴板操作
• thiserror: 错误处理

转换逻辑

当前的 Markdown 转换采用简化策略：

• 保留原始段落结构
• 合并连续空行为单个空行
• 去除每行首尾空白
• 不尝试识别标题层级（需要更复杂的字体分析）

🎯 未来改进方向

• 智能识别标题层级（基于字体大小）
• 支持列表和表格转换
• 支持图片提取
• 更好的段落检测
• 支持 OCR 处理扫描版 PDF
• 批量处理模式
• 支持更多输出格式（HTML, TXT 等）

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目采用 MIT 许可证。

🙏 致谢

感谢以下开源项目：

• pdf-extract - PDF 文本提取库
• clap - 命令行参数解析库
• clipboard-win - Windows 剪贴板库

---

Made with ❤️ using Rust