内容
<p align="center">
<img src="https://raw.githubusercontent.com/thomas-villani/all2md/main/docs/source/_static/logo.svg" alt="all2md logo" width="120" />
</p>
# 通用文档转换库
[](https://pypi.org/project/all2md/)
[](https://github.com/thomas-villani/all2md/actions/workflows/ci.yml)
[](https://codecov.io/gh/thomas-villani/all2md)
[](https://all2md.readthedocs.io/)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/all2md/)
**集成 AI 助手**
是一款全面的文档转换器，可以将 PDF、Office 文件、HTML、电子邮件、电子表格和 40 多种其他格式转换为干净的 Markdown — 并返回。基于 AST 的架构，提供强大的程序化文档处理功能，适用于 Python 应用程序、CLI 工作流、数据管道和 AI 助手。
📖 **[阅读文档](https://all2md.readthedocs.io/)** | 🚀 **[快速开始](#快速开始)** | 🎯 **[用例场景](#用例场景)**
## 快速开始
在 30 秒内开始使用：
```bash
# 安装 PDF 支持
pip install "all2md[pdf]"
# 将任何文档转换为 Markdown
all2md document.pdf
# 转换为文件
all2md report.docx -o report.md
# 在 Python 中使用
python -c "from all2md import to_markdown; print(to_markdown('document.pdf'))"
```
就是这样！对于更多格式，请安装您需要的依赖项：`all2md[docx,html,xlsx]` 或 `all2md[all]` 以获取所有内容。
**想与 AI 助手集成？** 请参阅下面的 [MCP 服务器](#mcp-服务器用于-ai-助手) 和 [代理技能](#代理技能) 部分。
## 基本 CLI 命令速查表
除了基本转换外，还提供强大的命令用于处理任何文档格式：
```bash
# 在终端中以丰富格式查看文档（类似 fancy cat）
all2md doc.pdf --rich
rcat doc.pdf # `rcat` = `all2md --rich` 的简写
# 快速将 Markdown 转换为 DOCX、PDF 或其他格式
all2md report.md --out report.docx
all2md notes.md --out presentation.pptx
# 打包论文以提交到 ArXiv
all2md arxiv paper.md -o submission.tar.gz --bib references.bib
# 在网页浏览器中以 HTML 预览查看任何文档
all2md view document.pdf
all2md view spreadsheet.xlsx --theme docs
# 通过 HTTP 提供目录（或通配符）服务，支持实时 HTML 预览
all2md serve ./docs --recursive
all2md serve "reports/*.docx" # 只提供匹配通配符的文件
# 在基于浏览器的 Markdown/WYSIWYG 编辑器中编辑任何文档并保存回去
all2md edit notes.md # md 源：覆盖原始文件（带有 .bak）
all2md edit report.docx # 非 md：默认保存为 report.md（兄弟）
# 按标题名称提取特定部分
all2md doc.pdf --extract "Introduction"
all2md view report.docx --extract "Q3 Results"
# 在任何文档类型（PDF、DOCX 等）中搜索
all2md grep "search term" documents/*.pdf
all2md grep -i "case insensitive" report.docx
# 跨文档集合进行关键词和向量搜索
all2md search "machine learning" ./research_papers/
all2md search "project timeline" --semantic ./docs/
# 支持 stdin/stdout 管道和链式命令（使用 '-' 表示 stdin）
curl https://example.com/doc.pdf | all2md - | grep "important"
cat report.html | all2md - --format html --rich
all2md document.docx | wc -w # 计算任何文档中的字数
# 所有文件命令都支持通过 '-' 使用 stdin
echo "<h1>Quick Note</h1>" | all2md view - # 从 stdin 查看
cat doc.pdf | all2md grep "search term" - # 搜索 stdin 内容
echo "<p>Version 1</p>" | all2md diff - version2.html # 与 stdin 进行差异比较
```
这些命令适用于所有支持的格式 - 将 PDF、Word 文档和电子表格视为纯文本文件。全 stdin/stdout 支持意味着您可以将 all2md 集成到任何工作流中。
## 问题
现代文档工作流需要转换多种文件格式 - 将 PDF 转换为 Markdown 进行分析，将 Word 文档转换为 HTML 进行网页发布，将电子表格转换为可读文本进行处理。现有的解决方案通常需要多个工具，具有不一致的 API，产生凌乱的输出，或缺乏程序化控制。转换回 Markdown 甚至更难。
## 解决方案
`all2md` 提供了一个统一的、双向的转换管道，基于强大的抽象语法树（AST）架构：
1. **解析：** 将任何支持的文档转换为一致的 AST 表示
2. **转换：** 使用强大的转换管道以编程方式清理、修改或分析内容
3. **渲染：** 输出到 Markdown，或直接转换为其他富格式，如 DOCX、PDF 或 HTML
这种基于 AST 的方法实现了：
- **一致的转换** 跨所有格式
- **双向工作流** （Markdown ↔ DOCX/PDF/HTML）
- **程序化控制** 具有干净的 Python API
- **适用于 AI 工作流** - 将文档提供给 LLM 并将 Markdown 响应转换回富格式
## 为什么选择 all2md？
虽然像 Pandoc 这样的工具在文档转换方面表现出色，但 all2md 专门为 Python 开发人员、AI/LLM 工作流和程序化文档处理而设计。以下是选择 all2md 的原因：
**选择 all2md 时：**
- **Python 原生集成** - 为嵌入应用程序而设计的首选 Python API，而不仅仅是 CLI 使用
- **AI 助手集成** - 带有用于直接 Claude Desktop、ChatGPT 等 AI 模型集成的内置 MCP 服务器
- **基于 AST 的转换** - 用于以编程方式清理、修改和分析内容的强大文档处理管道
- **轻量级依赖** - 仅安装所需的内容；
- **可扩展性** - 使用 Python 入口点系统简单地添加自定义格式和转换
- **现代 Python** - 为 Python 3.10+ 构建，带有类型提示、数据类和现代模式
**选择 Pandoc 时：**
- 最大格式支持（100 多种格式）
- 学术文档功能（引用、参考文献）
- 独立二进制文件，无运行时依赖
- 久经考验的稳定性（15+ 年开发）
**同时使用两者：** all2md 补充了 Python 项目中的 Pandoc。使用 all2md 进行 LLM 预处理、程序化工作流和 AI 集成，然后在需要时将任务交给 Pandoc 处理特定的学术格式。
## 主要功能
- **全面格式支持**：转换数十种格式，包括 PDF、DOCX、PPTX、HTML、EML、EPUB、XLSX、IPYNB、RST、Org-Mode、ZIP 存档和 100 多种源代码和配置文件类型。
- **双向转换**：不仅转换为 Markdown！从 Markdown 转换为 DOCX、PDF 和 HTML 等格式。
- **文档比较**：内置 `diff` 命令，适用于任何文档格式。比较 PDF、Word 文档或混合格式，进行基于文本的对称比较。
- **自定义模板渲染**：使用 Jinja2 模板创建任何基于文本的输出格式（DocBook XML、YAML、ANSI 终端、自定义标记），无需编写 Python 代码。
- **MCP 服务器**：用于 AI 助手直接集成的内置模型上下文协议（MCP）服务器。使 Claude、ChatGPT 等 AI 模型能够直接读取和转换文档，以及查询工具来搜索语料库、差异比较文档和大纲文档的标题。
- **浏览器内预览和编辑器**：`all2md view` 在浏览器中渲染任何文档，`all2md edit` 提供实时 Markdown 编辑器 - 均带有暗黑模式切换和可选的独立窗口模式（ `--window`，`pip install all2md[window]` ）。
- **代理技能**：预构建的技能文件，用于教导 AI 编码助手（Claude Code、Cursor、Windsurf）如何有效使用 all2md。 使用 `all2md install-skills` 安装。
## 核心优势
- **基于 AST 的架构**：不像直接的格式到格式转换器，all2md 使用中间抽象语法树：
- 一致的文档表示跨所有格式
- 实现强大的转换（删除图像、偏移标题、重写链接等）
- 使双向转换成为可能且可靠
- 允许通过 Jinja2 模板创建自定义输出格式（DocBook XML、YAML、ANSI 终端等）
- 促进复杂的文档分析和操作
### 1. 基于 AST 的架构
与直接的格式到格式转换器不同，all2md 使用中间抽象语法树：
- 一致的文档表示跨所有格式
- 启用强大的转换（删除图像、偏移标题、重写链接等）
- 使双向转换成为可能且可靠
- 允许使用 Jinja2 模板创建自定义输出格式（DocBook XML、YAML、ANSI 终端等）
- 促进复杂的文档分析和操作
### 2. 生产就绪的 Python API
设计用于嵌入应用程序，而不仅仅是 CLI 使用：
- 清洁的、类型化的 API，适用于每种格式的综合选项类
- 适用于长时间运行的转换的进度回调
- 支持任意支持的格式之间的双向转换
- 用于高级文档处理的 AST 操作
- 用于系统文档修改的转换管道
- 每个格式都有详细的文档和示例
### 3. 强大的 CLI 功能
除了基本转换之外，CLI 还包括用于生产工作流的先进功能：
- **监视模式** - 自动转换文件更改时
- **并行处理** - 用于大型文档集的多 worker 处理
- **静态站点生成** - 内置 SSG，带有 5 种主题（暗黑、docs、极简主义、报纸、侧边栏）
- **快速预览** - `all2md view` 命令用于即时 HTML 预览
- **网页编辑器** - `all2md edit` 在 Markdown + WYSIWYG 编辑器中打开任何文档，并保存回任何支持的格式，自动备份
- **配置管理** - 生成、验证和管理转换配置
- **格式发现** - `all2md list-formats` 显示所有支持的格式和依赖项
- **代理友好** - 清洁、直观的界面，AI 代理可以直接使用，加上预构建的代理技能，可通过 `all2md install-skills` 安装
### 4. AI 原生集成
**MCP 服务器** - 内置模型上下文协议服务器，实现与 Claude Desktop 等 AI 助手直接集成。无需包装脚本或外部工具。
- 在 Claude Desktop 和其他 MCP 兼容的 AI 工具中直接读取文档
- 智能自动检测文件路径、数据 URI、base64 和纯文本
- 章节提取，用于有针对性的阅读
- 视觉模型支持，嵌入图像
- 安全优先的设计，带有文件允许列表和网络控件
**代理技能** - 预构建的技能文件，用于教导 AI 编码助手如何有效使用 all2md。
- 6 个专注的技能，涵盖阅读、转换、生成、grep、搜索和差异比较
- 与 Claude Code、Cursor、Windsurf 等技能感知代理配合使用
- 使用一个命令安装：`all2md install-skills`
- 可自定义 - 编辑已安装的技能文件以匹配您的项目需求
## MCP 服务器用于 AI 助手
`all2md` 包含一个内置的 MCP（模型上下文协议）服务器，允许 AI 助手（如 Claude）直接读取和转换文档：
```bash
# 安装 MCP 支持
pip install "all2md[mcp]"
# 启动 MCP 服务器，带有临时工作区
all2md-mcp --temp --enable-from-md
```
**工具：** `read_document_as_markdown`、`save_document_from_markdown`、`edit_document`，以及三个仅限读取的查询工具 - 默认情况下启用 `search_documents`（grep + 关键词/BM25 跨语料库）、`diff_documents`（比较两个文档）和 `get_document_outline`（文档结构导航）。
**关键功能：**
- **智能自动检测**：自动检测源类型（文件路径、数据 URI、base64 或纯文本）
- **语料库搜索**：跨多个文档进行 grep 和关键词/BM25 搜索，返回排名的片段而不是整个文件
- **章节提取和大纲**：按标题提取章节或列出文档的结构以便有针对的阅读
- **文档差异比较**：比较两个文档（任意格式）并获取统一或 JSON 差异
- **安全第一**：文件允许列表、网络控制和路径验证
- **vLLM 图像支持**：可选地将图像嵌入 base64 以支持视觉模型
### 一键安装（Claude Desktop）
安装预构建的 MCPB 包 - 无需手动配置或单独的 Python 安装（该包通过 `uv` 在首次运行时拉取 all2md）：
1. 从 [最新版本](https://github.com/thomas-villani/all2md/releases/latest) 下载 `all2md.mcpb`。
2. 打开 **Claude Desktop → 设置 → 扩展** （齿轮图标，或 `Ctrl+,` / `Cmd+,`）。
3. **将 `all2md.mcpb` 拖到扩展面板** （或使用 **安装扩展** / **高级** 按钮浏览它）。双击文件也可以，如果您的操作系统已注册了 `.mcpb` 关联，但路径不依赖于它。
4. 在安装对话框中，选择一个 **工作区文件夹**，all2md 可以从中读取和写入文件（默认为您的文档文件夹；外部文件被拒绝），并根据需要调整写入/渲染、就地编辑和网络访问的切换。
5. 然后，all2md 工具（`read_document_as_markdown`、`save_document_from_markdown`、`edit_document`、`search_documents`、`diff_documents` 和 `get_document_outline`）出现在 **"+" → 连接器** 面板中的聊天中，准备使用。
> 需要具有 MCPB 扩展支持的 Claude Desktop 版本（2025 年晚期或更新）。要自己重新构建包，请参阅 [`mcpb/README.md`](mcpb/README.md）。
### 手动配置（开发者 / 其他 MCP 客户端）
对于开发或其他非 Desktop MCP 客户端，请直接在 `claude_desktop_config.json` 中配置服务器：
```json
{
"mcpServers": {
"all2md": {
"command": "all2md-mcp",
"args": ["--temp", "--enable-from-md"]
}
}
```
请参阅 [MCP 文档](https://all2md.readthedocs.io/en/latest/mcp.html) 以获取完整详细信息。
## 代理技能
all2md 随附 **预构建的代理技能** - 一种结构化指令文件，用于教导 AI 编码助手（Claude Code、Cursor、Windsurf 等）如何有效使用 all2md。遵循 Anthropic 的渐进式披露模式，精简的 `SKILL.md` 概述路由到专注的按需参考指南，用于每个文档工作流（CLI 示例、Python API 模式和选项引用）。
```
all2md/
├── SKILL.md # 概述 + 索引
└── references/
├── read.md # 从任何文档中读取/提取文本和表格
├── convert.md # 在格式之间转换（PDF→DOCX、HTML→PDF，...）
├── generate.md # 从 Markdown 创建文档（DOCX、PDF、PPTX、EPUB、站点）
├── grep.md # 文档内的模式匹配（PDF 的 grep）
├── search.md # 跨集合的排名/语义搜索
└── diff.md # 比较任意两个文档，无论格式如何）
```
### 安装技能
```bash
# 安装到默认位置
all2md install-skills
# 列出可用技能
all2md install-skills --list
# 安装到本地项目（./.agents/skills/）
all2md install-skills --local
# 全局安装（~/.agents/skills/）
all2md install-skills --global
# 强制覆盖现有技能
all2md install-skills --force
# 删除已安装的技能
all2md install-skills --uninstall
```
安装后，代理自动发现技能并在相关任务出现时使用它们。 请参阅 [代理技能文档](https://all2md.readthedocs.io/en/latest/agent_skills.html）以获取完整详细信息。
## 支持的格式
`all2md` 使用模块化系统，仅需为需要处理的格式安装相关依赖。
| 格式 | 文件扩展名 | 输入（解析） | 输出（渲染） | 额外依赖 |
| ----------------------------- | --------------------------------------------- | :-----------: | :-------------: | ------------------ |
| **PDF** | `.pdf` | ✅ | ✅ | `pdf`、`pdf_render`|
| **Word 文档** | `.docx` | ✅ | ✅ | `docx` |
| **PowerPoint 演示文稿** | `.pptx` | ✅ | ✅ | `pptx` |
| **HTML** | `.html`、`.htm` | ✅ | ✅ | `html` |
| **MHTML 网页存档** | `.mhtml`、`.mht` | ✅ | (N/A) | `html` |
| **电子邮件消息** | `.eml` | ✅ | (N/A) | （内置） |
| **MBOX 邮箱存档** | `.mbox`、`.mbx` | ✅ | (N/A) | （内置） |
| **Outlook 消息/存档** | `.msg`、`.pst`、`.ost` | ✅ | (N/A) | `outlook` |
| **Jupyter Notebook** | `.ipynb` | ✅ | ✅ | （内置） |
| **EPUB 电子书** | `.epub` | ✅ | ✅ | `epub` |
| **FictionBook 2.0 (FB2)** | `.fb2` | ✅ | (N/A) | `fb2` |
| **CHM（编译 HTML 帮助）** | `.chm` | ✅ | (N/A) | `chm` |
| **OpenDocument 文本** | `.odt` | ✅ | ✅ | `odf` |
| **OpenDocument 演示文稿** | `.odp` | ✅ | ✅ | `odf` |
| **OpenDocument 电子表格** | `.ods` | ✅ | (N/A) | `odf` |
| **Excel 电子表格** | `.xlsx` | ✅ | (N/A) | `xlsx` |
| **CSV / TSV** | `.csv`、`.tsv` | ✅ | ✅ | （内置） |
| **富文本格式** | `.rtf` | ✅ | ✅ | `rtf` |
| **LaTeX** | `.tex`、`.latex` | ✅ | ✅ | `latex` |
| **AsciiDoc** | `.adoc`、`.asciidoc`、`.asc` | ✅ | ✅ | （内置） |
| **reStructuredText** | `.rst` | ✅ | ✅ | `rst` |
| **Org-Mode** | `.org` | ✅ | ✅ | `org` |
| **MediaWiki** | `.wiki`、`.mw` | ✅ | ✅ | `wiki` |
| **Textile** | `.textile` | ✅ | ✅ | （内置） |
| **BBCode** | `.bbcode`、`.bb` | ✅ | (N/A) | （内置） |
| **DokuWiki** | `.doku`、`.dokuwiki` | ✅ | ✅ | （内置） |
| **Evernote 导出** | `.enex` | ✅ | (N/A) | `enex` |
| **Safari 网页存档** | `.webarchive` | ✅ | (N/A) | `html` |
| **JSON** | `.json` | ✅ | ✅ | （内置） |
| **YAML** | `.yaml`、`.yml` | ✅ | ✅ | （内置） |
| **TOML** | `.toml` | ✅ | ✅ | （内置） |
| **INI / 配置** | `.ini`、`.cfg`、`.conf` | ✅ | ✅ | （内置） |
| **OpenAPI/Swagger** | `.yaml`、`.yml`、`.json` | ✅ | (N/A) | `openapi` |
| **纯文本** | `.txt`、`.text` | ✅ | ✅ | （内置） |
| **源代码** | 100+ 扩展名（`.py`、`.js`等） | ✅ | (N/A) | （内置） |
| **存档格式** | `.tar`、`.tgz`、`.7z`、`.rar`等 | ✅ | (N/A) | （内置） |
| **ZIP 存档** | `.zip` | ✅ | (N/A) | （内置） |
| **Jinja2 模板（自定义）** | 用户定义（`.jinja2`、`.j2`） | ❌ | ✅ | `jinja2` |
> **💡 新增！** 使用 Jinja2 模板创建自定义输出格式，无需编写 Python 代码。参见 [模板指南](https://all2md.readthedocs.io/en/latest/templates.html) 和 [示例/jinja-templates/](examples/jinja-templates/)，适用于 DocBook XML、YAML、ANSI 终端等。
## 安装
核心库没有依赖。你可以安装它并根据需要为格式添加支持。
**1. 基本安装**
```bash
pip install all2md
```
**2. 系统范围 CLI 安装（推荐给 CLI 用户）**
使用 [uv](https://docs.astral.sh/uv/) 安装 CLI 以便从任何地方直接访问：
```bash
# 如果您没有 uv，请安装它
curl -LsSf https://astral.sh/uv/install.sh | sh
# 系统范围安装 all2md CLI 及所有依赖
uv tool install "all2md[all]"
# 或安装特定格式
uv tool install "all2md[pdf,docx,html]"
# 现在可以在任何地方使用 all2md
all2md document.pdf
```
这样，您可以在无需激活虚拟环境的情况下全局使用 `all2md` 命令。
**3. 额外安装**
仅安装您需要的格式支持。您可以组合多个额外项。
```bash
# 安装 PDF、DOCX 和 HTML 支持
pip install "all2md[pdf,docx,html]"
# 安装电子表格和 ODF 文档支持
pip install "all2md[xlsx,odf]"
# 安装带有 OCR 的 PDF 支持（扫描文档；需要 Tesseract 引擎；需要系统二进制文件）
pip install "all2md[pdf,ocr]"
# ... 或使用二进制免费的 EasyOCR 引擎代替（无需系统二进制文件；首次使用时下载模型）
pip install "all2md[pdf,ocr-easyocr]"
# 安装带有 GNN 布局分析的 PDF 支持
pip install "all2md[pdf_layout]"
# 安装 Outlook MSG 文件支持
pip install "all2md[outlook]"
# 注意：PST/OST 支持需要额外的手动安装
# pip install libpff-python # 用于 PST/OST 文件（特定于平台）
```
**4. 完整安装**
安装所有支持的格式的所有可选依赖：
```bash
pip install "all2md[all]"
```
**5. 检查依赖**
您可以在任何时候使用内置的 CLI 命令检查可选依赖的状态：
```bash
all2md check-deps
```
## 命令行用法
`all2md` 提供了一个强大的命令行界面，用于快速转换和脚本编写。
**基本转换**
```bash
# 转换 PDF 并打印到 stdout
all2md document.pdf
# 将 Word 文档转换为文件
all2md report.docx -o report.md
```
**多文件和目录处理**
```bash
# 将目录中的所有 DOCX 文件转换为输出文件夹
all2md ./reports/*.docx --output-dir ./markdown_reports
# 递归转换整个目录
all2md ./source_docs --recursive --output-dir ./converted_docs
# 在输出中保留源目录结构
all2md ./source_docs -r --output-dir ./converted_docs --preserve-structure
```
**高级处理**
```bash
# 使用 4 个工作进程并行处理文件
all2md ./large_docs -r --output-dir ./output -p 4
# 监视目录中的更改并自动转换
all2md ./watched_folder -r --output-dir ./output --watch
# 从 stdin 传输内容
cat report.html | all2md - > report.md
curl https://example.com | all2md - --format html > example.md
```
**特定格式选项**
所有转换选项都作为 CLI 标志提供。使用 `--help` 来查看它们。
```bash
# 仅转换 PDF 的第 1-3 和第 5 页
all2md report.pdf --pdf-pages "1-3,5"
# 使用 OCR 转换扫描的 PDF（Tesseract 引擎；需要 Tesseract 二进制文件）
all2md scanned.pdf --pdf-ocr-enabled --pdf-ocr-mode auto --pdf-ocr-languages eng
# 相同，使用二进制免费的 EasyOCR 引擎（添加 --pdf-ocr-gpu 以在可用时使用 GPU 加速）
all2md scanned.pdf --pdf-ocr-enabled --pdf-ocr-engine easyocr --pdf-ocr-languages eng
# 转换 HTML 文件，提取 <title> 作为主标题
all2md page.html --html-extract-title
# 转换 DOCX 并将图像下载到文件夹
all2md document.docx --attachment-mode save --attachment-output-dir ./images
# 转换 MBOX 邮箱，限制为 100 条消息
all2md archive.mbox --mbox-max-messages 100
# 转换 Outlook PST 文件并过滤文件夹
all2md outlook.pst --outlook-folder-filter "Inbox" "Sent Items"
```
**使用转换**
直接从 CLI 应用 AST 转换。
```bash
# 从文档中删除所有图像
all2md report.docx -t remove-images
# 偏移所有标题级别（例如，H1 -> H2，H2 -> H3）
all2md chapter.docx -t "heading-offset --offset 1"
# 列出所有可用的转换
all2md list-transforms
```
**其他 CLI 命令**
CLI 包括多个用于发现和生产的实用命令：
```bash
# 列出所有支持的格式及其依赖
all2md list-formats
# 检查已安装的可选依赖
all2md check-deps
# 使用主题快速 HTML 预览（minimal、dark、newspaper、docs、sidebar）
all2md view document.pdf --theme docs
# 从 markdown 文件生成静态站点（Hugo、Jekyll、MkDocs、Zola 或 Eleventy）
all2md generate-site ./content --output-dir ./site --generator hugo
# 为 ArXiv 提交打包文档
all2md arxiv paper.md -o submission.tar.gz
all2md arxiv paper.docx -o submission.tar.gz --bib references.bib
# 为 AI 编程助手安装代理技能
all2md install-skills
# 配置管理 - 生成、显示或验证配置文件
all2md config generate > all2md.toml
all2md config show
all2md config validate all2md.toml
```
**静态站点生成**
`generate-site` 命令将文档集合转换为可部署的 [Hugo](https://gohugo.io/)、[Jekyll](https://jekyllrb.com/)、[MkDocs](https://www.mkdocs.org/)、[Zola](https://www.getzola.org/) 或 [Eleventy](https://www.11ty.dev/) 站点：
```bash
# 生成 Hugo 站点（默认 frontmatter：TOML）
all2md generate-site ./content --output-dir ./site --generator hugo
# 生成 Jekyll 博客（日期前缀帖子，YAML frontmatter）
all2md generate-site ./posts --output-dir ./blog --generator jekyll --scaffold
# 生成 MkDocs 文档站点
all2md generate-site ./docs --output-dir ./public --generator mkdocs --scaffold --recursive
# 还支持：Zola（TOML，Rust）和 Eleventy/11ty（YAML，JS）
all2md generate-site ./docs --output-dir ./site --generator zola --scaffold
all2md generate-site ./docs --output-dir ./site --generator eleventy --scaffold
# 命令处理：
# - 从文档元数据生成 frontmatter（标题、日期、作者、标签...）
# - 特定于生成器的目录结构和配置（--scaffold）
# - 图像/资产收集、复制和路径重写
# - 递归批量转换及排除模式（--recursive, --exclude）
```
有关动态、Flask 服务的 Markdown 站点，请参见 [examples/flask_markdown_site.py](examples/flask_markdown_site.py)。
## Python API 用法
将 `all2md` 直接集成到您的 Python 应用程序中，以实现编程控制。
**简单转换**
`to_markdown()` 函数是开始使用最简单的方法。
```python
from all2md import to_markdown
# 将文件转换为 Markdown
markdown_content = to_markdown('document.pdf')
print(markdown_content)
```
**使用配置选项**
通过传递 `Options` 对象或关键字参数来微调转换。
```python
from all2md import to_markdown, PdfOptions, MarkdownRendererOptions
# 使用选项对象以实现类型安全性和清晰度
pdf_opts = PdfOptions(pages="1-3,5", attachment_mode="base64")
md_opts = MarkdownRendererOptions(flavor="gfm", emphasis_symbol="_")
markdown_content = to_markdown(
'report.pdf',
parser_options=pdf_opts,
renderer_options=md_opts
)
# 转换扫描的 PDF 并使用 OCR
from all2md.options.common import OCROptions
# 引擎 = "tesseract"（默认，需要 Tesseract 二进制文件）或引擎 = "easyocr"
# （二进制免费；pip install all2md[ocr-easyocr]）。easyocr 还支持 gpu = True
# 在可用时使用 GPU 加速（被 tesseract 忽略）。
ocr_opts = OCROptions(enabled=True, mode="auto", engine="tesseract", languages="eng", dpi=300)
pdf_opts_with_ocr = PdfOptions(ocr=ocr_opts)
markdown_content = to_markdown('scanned.pdf', parser_options=pdf_opts_with_ocr)
# 或者，传递关键字参数
markdown_content = to_markdown(
'report.pdf',
pages="1-3,5", # PdfOptions
attachment_mode="base64", # BaseParserOptions
flavor="gfm", # MarkdownRendererOptions
emphasis_symbol="_" # MarkdownRendererOptions
)
# 转换 MBOX 邮箱并过滤消息
from all2md.options.mbox import MboxOptions
import datetime
mbox_opts = MboxOptions(
max_messages=100,
date_range_start=datetime.datetime(2024, 1, 1, tzinfo=datetime.timezone.utc),
output_structure="hierarchical"
)
markdown_content = to_markdown('archive.mbox', parser_options=mbox_opts)
# 转换 Outlook PST 文件并过滤文件夹
from all2md.options.outlook import OutlookOptions
outlook_opts = OutlookOptions(
folder_filter=["Inbox", "Sent Items"],
skip_folders=["Deleted Items", "Junk Email"],
max_messages=500
)
markdown_content = to_markdown('mailbox.pst', parser_options=outlook_opts)
```
**双向转换**
使用 `convert()` 函数在任意两个支持的格式之间进行转换。
```python
from all2md import convert
# 将 Markdown 转换为 DOCX
convert("input.md", "output.docx", target_format="docx")
# 将 HTML 转换为 PDF
convert("page.html", "page.pdf", target_format="pdf")
```
**使用 AST**
对于高级用例，您可以直接使用抽象语法树（AST）。
```python
from all2md import to_ast, from_ast
from all2md.ast import Document, Heading, Text
# 1. 将文档解析为 AST
doc: Document = to_ast("document.pdf")
# 2. 操作 AST
# 示例：在开头添加新的标题
new_heading = Heading(level=1, content=[Text(content="New Title")])
doc.children.insert(0, new_heading)
# 3. 将修改后的 AST 渲染回 markdown
markdown_output = from_ast(doc, target_format="markdown")
```
**使用 AST 转换**
`transforms` 模块提供了一种强大的方法来操作 AST。
```python
from all2md import to_ast
from all2md.transforms import render, HeadingOffsetTransform, RemoveImagesTransform
# 解析为 AST
doc = to_ast("report.docx")
# 在渲染之前应用转换列表
# 转换可以是类实例或已注册的字符串名称
markdown_output = render(
doc,
transforms=[
RemoveImagesTransform(), # 实例
"add-heading-ids", # 已注册名称
HeadingOffsetTransform(offset=1) # 带参数的实例
]
)
```
## 可扩展性：插件系统
`all2md` 构建为可扩展的。您可以通过利用 Python 的入口点为新的文件格式添加转换器和转换。
- **自定义转换器**：通过定义 `ConverterMetadata` 对象并在 `all2md.converters` 入口点下注册，来为新文件格式创建解析器。
- **自定义转换**：通过子类化 `NodeTransformer`、定义 `TransformMetadata` 对象并在 `all2md.transforms` 入口点下注册，来创建新的 AST 转换。
参见 [examples/simpledoc-plugin/](examples/simpledoc-plugin/) 以获取完整的插件示例，以及 [examples/watermark-plugin/](examples/watermark-plugin/) 以获取转换插件示例。
## 用例场景
`all2md` 设计用于服务具有不同需求的不同受众：
### 对于 Python 开发者
**场景：** 您正在构建一个文档系统、内容管理工具或需要处理多种文档格式的数据管道。
```python
from all2md import to_markdown, convert
from all2md.transforms import render, RemoveImagesTransform
# 将上传的文档转换为 markdown 进行存储
def process_upload(file_path):
markdown = to_markdown(file_path)
# 存储在数据库或文件系统中
return markdown
# 构建文档转换器 API
def convert_document(input_path, output_format):
convert(input_path, f"output.{output_format}", target_format=output_format)
# 清理文档以显示
def clean_for_web(doc_path):
from all2md import to_ast
doc = to_ast(doc_path)
return render(doc, transforms=["remove-images", "sanitize-html"])
```
**示例：** [batch_converter.py](examples/batch_converter.py)， [document_sanitizer.py](examples/document_sanitizer.py)
### 面向 AI/LLM 开发人员
**场景：** 您正在构建需要摄取文档、处理文档并生成新文档的 LLM 应用程序。
```python
# 设置用于 Claude Desktop 集成的 MCP 服务器
# 添加到 claude_desktop_config.json：
{
"mcpServers": {
"all2md": {
"command": "all2md-mcp",
"args": ["--temp", "--enable-from-md"]
}
}
}
# 或在 LLM 管道中以编程方式使用
from all2md import to_markdown, convert
# 1. 摄取：转换文档为 markdown 以进行 LLM 处理
document_text = to_markdown("research_paper.pdf")
# 2. 处理：发送到 LLM，获取 markdown 响应
llm_response = your_llm_call(document_text)
# 3. 生成：转换 LLM 输出回富格式
with open("output.md", "w") as f:
f.write(llm_response)
convert("output.md", "final_report.docx", target_format="docx")
```
**示例：** [llm_translation_demo.py](examples/llm_translation_demo.py)， [study_guide_generator.py](examples/study_guide_generator.py)
### 面向 CLI 用户和 DevOps
**场景：** 您需要批处理文档，将转换集成到脚本中，或监视目录中新文档。
```bash
# 监视目录并自动转换新文档
all2md ./incoming -r --output-dir ./processed --watch
# 使用并行工作线程进行批处理
all2md ./documents/*.pdf --output-dir ./markdown --parallel 8
# 集成到 CI/CD 管道
for doc in ./docs/*.docx; do
all2md "$doc" -o "./output/$(basename "$doc" .docx).md"
done
# 从 markdown 文件生成文档站点
all2md generate-site ./docs --output-dir ./public --generator mkdocs
# 在提交前快速预览
all2md view README.md --theme minimal
```
**示例：** [vcs-converter/](examples/vcs-converter/)（Git 预提交钩子集成）
### 面向数据科学家
**场景：** 您正在从 PDF、电子表格和文档中提取数据以进行分析或馈送到机器学习管道中。
```python
from all2md import to_markdown, to_ast
from all2md.ast import Table, CodeBlock
# 递归产生文档 AST 中的每个节点
def iter_nodes(node):
yield node
for attr in ("children", "content"):
for child in getattr(node, attr, None) or []:
yield from iter_nodes(child)
# 从 PDF 中提取表格以进行分析
def extract_tables(pdf_path):
doc = to_ast(pdf_path)
return [node for node in iter_nodes(doc) if isinstance(node, Table)]
# 处理电子邮件存档以进行 NLP
def process_email_archive(mbox_path):
from all2md.options.mbox import MboxOptions
opts = MboxOptions(
output_structure="flat",
extract_metadata=True
)
emails = to_markdown(mbox_path, parser_options=opts)
return emails
# 从文档中提取代码示例
def extract_code_blocks(doc_path):
doc = to_ast(doc_path)
return [node for node in iter_nodes(doc) if isinstance(node, CodeBlock)]
```
**示例：** [api_doc_extractor.py](examples/api_doc_extractor.py)， [code_example_generator.py](examples/code_example_generator.py)
## 常见问题
**问：** all2md 与 Pandoc 有何不同？
答： all2md 是纯 Python 的，专注于编程使用、LLM 集成和可扩展性。Pandoc 更适合学术文档，但基于 Haskell 且专注于 CLI。使用 all2md 进行 Python 项目和 AI 工作流；使用 Pandoc 进行学术出版。它们互相补充得很好。
**问：** 我可以将 Markdown 转换回 Word/PDF 吗？
答： 是的！all2md 支持双向转换。使用 `convert("input.md", "output.docx", target_format="docx")` 或 CLI： `all2md input.md -o output.pdf --to pdf`.
**问：** 馈送文档到 LLM 的最佳格式是什么？
答： 带有 `gfm`（GitHub Flavored Markdown）风格的 Markdown。它是结构化的、一致的，并且被 LLM 们很好地理解。使用 `to_markdown(file, flavor="gfm")`.
**问：** 如何添加对新文件格式的支持？
答： 创建一个解析器类，定义一个 `ConverterMetadata` 对象，并通过 `all2md.converters` 入口点在您的 `pyproject.toml` 中注册它。有关完整示例，请参阅 [examples/simpledoc-plugin/](examples/simpledoc-plugin/)。
**问：** all2md 是否适用于扫描的 PDF？
答： 是的！使用 OCR 支持安装（`pip install "all2md[pdf,ocr]"`）并使用 `--pdf-ocr-enabled` 标志或 Python 中的 `OCROptions(enabled=True)`。默认的 Tesseract 引擎需要系统上的 Tesseract 二进制文件；或者使用带有 `pip install "all2md[pdf,ocr-easyocr]"` 的无二进制 EasyOCR 引擎和 `--pdf-ocr-engine easyocr`（它会在第一次使用时下载模型，并且更重量级）。
**问：** 我能否自定义输出格式以超越 Markdown？
答： 是的！使用 Jinja2 模板创建任何基于文本的输出格式。有关 DocBook XML、YAML、ANSI 终端输出等示例，请参阅 [examples/jinja-templates/](examples/jinja-templates/)。
**问：** all2md 是否已准备好投入生产？
答： 是的！all2md 稳定且已准备好投入生产。该库包含全面的测试、广泛的文档，并且正在积极维护。
**问：** 如何高效处理大量文档批次？
答： 使用并行处理： `all2md ./docs -r --output-dir ./output --parallel 8` 或在 Python 中使用 `to_markdown()` 调用时的多进程。对于非常大的批次，请考虑使用监视模式进行增量处理。
## 获取帮助
- **文档：** [在 ReadTheDocs 上阅读完整文档](https://all2md.readthedocs.io/)
- **示例：** 浏览 [15+ 示例](examples/)，按复杂度和用例组织
- **问题：** 在 [GitHub Issues](https://github.com/thomas-villani/all2md/issues) 上报告错误或请求功能
## 性能基准测试
对于评估解析器更改的贡献者，all2md 提供了一个基准测试工具包，位于 [`benchmarks/corpus/`](benchmarks/corpus/)，它从公共文档语料库中提取确定性样本（arxiv、PubMed Central、govdocs1、Apache POI 测试数据、Enron 电子邮件发布），对每个文档进行转换计时，并生成分层 Markdown 报告。
```bash
# 完整管道：下载、基准测试、生成报告
python -m benchmarks.corpus.run
# 有针对性的运行：仅限 arxiv 的 PDF，限制在 20 个文档内
python -m benchmarks.corpus.run --sources arxiv --formats pdf --max-docs 20
```
配套的 `inspect` 助手保存转换后的 Markdown 文件，位于源文件的副本旁边，以便您可以手动审查精选子集（最慢、最大或随机）的转换质量：
```bash
python -m benchmarks.corpus.inspect --criteria slowest --n 10
python -m benchmarks.corpus.inspect --criteria random --sources pmc --n 5 --seed 1
```
有关完整的配置参考，请参阅 [`benchmarks/corpus/README.md`](benchmarks/corpus/README.md)，并参阅 [性能调优文档](https://all2md.readthedocs.io/en/latest/performance.html#corpus-benchmark-harness)，以获取概述。
## 贡献
欢迎贡献！我们感谢错误报告、功能请求、文档改进和代码贡献。
**贡献方式：**
- 通过 [GitHub Issues](https://github.com/thomas-villani/all2md/issues) 报告错误或建议功能
- 改进文档或添加示例
- 通过插件系统添加对新文件格式的支持
- 创建新的 AST 转换
- 修复错误或改进现有的转换器
有关开发设置和指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 许可证
该项目根据 MIT 许可证授权。有关详细信息，请参阅 `LICENSE` 文件。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器