# word2md

**Repository Path**: moregain/word2md

## Basic Information

- **Project Name**: word2md
- **Description**: word 转 md 文档
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-06-19
- **Last Updated**: 2025-07-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Word转Markdown工具

一个功能强大的Word文档转Markdown格式的Python工具，支持**双格式输入**和**多转换引擎**。

## 🚀 核心特点

- ✅ **全格式支持**: 支持`.doc`和`.docx`格式文档转换  
- ✅ **多转换引擎**: 内置解析器 + Pandoc + 格式转换
- ✅ **智能处理**: 自动检测文件格式并选择最佳转换策略
- ✅ 保留文档格式（标题、加粗、斜体、下划线等）
- ✅ 支持表格、图片转换（Pandoc模式）
- ✅ 支持批量转换多个文档
- ✅ 提供命令行和图形界面两种使用方式
- ✅ 详细的转换日志输出

## 🔧 转换引擎对比

### 内置转换器（基于python-docx）
**原理**: 直接解析`.docx`文件的XML结构，手动映射Word格式到Markdown语法

**优点**:
- 无需额外安装依赖
- 启动速度快
- 占用资源少

**缺点**:
- 仅支持`.docx`格式
- 不支持图片转换
- 复杂文档处理可能不够完善

### Pandoc转换器（推荐）
**原理**: 调用Pandoc命令行工具进行转换，Pandoc是学术界广泛使用的文档转换标准

**优点**:
- 🎯 **转换质量更高** - 支持更多Word格式
- 📄 **双格式支持** - 支持`.doc`和`.docx`文件
- 🖼️ **图片支持** - 自动提取并转换图片
- 📊 **复杂表格** - 更好的表格结构处理
- 📝 **格式保真** - 更准确的格式转换
- 🔗 **链接支持** - 保留超链接和书签
- 📋 **列表处理** - 完整的有序/无序列表支持

**缺点**:
- 需要单独安装Pandoc
- 首次运行稍慢

### .doc文件专用转换策略
**多重策略确保兼容性**:

1. **Pandoc直接转换** - 如果Pandoc可用，首先尝试直接转换
2. **格式转换策略** - 使用LibreOffice等工具转换为`.docx`后再转换
3. **文本提取策略** - 提取纯文本并转换为基础Markdown格式

**支持的.doc转换工具**:
- 🥇 **LibreOffice** (推荐，免费，全平台)
- 🥈 **Microsoft Word + doc2docx** (Windows/macOS)
- 🥉 **antiword** (Linux/macOS，轻量级)
- 🥉 **catdoc** (Linux/macOS，轻量级)
- 🥉 **docx2txt** (Python库，文本提取)

## 📦 安装依赖

### 1. Python依赖
```bash
pip install -r requirements.txt
```

### 2. Pandoc安装（强烈推荐）

**Windows**:
```bash
# 方法1: 官网下载安装包
# https://pandoc.org/installing.html

# 方法2: 使用包管理器
choco install pandoc      # Chocolatey
scoop install pandoc      # Scoop
```

**macOS**:
```bash
brew install pandoc
```

**Linux**:
```bash
# Ubuntu/Debian
sudo apt-get install pandoc

# CentOS/RHEL  
sudo yum install pandoc
```

### 3. .doc文件支持工具（可选但推荐）

#### LibreOffice（推荐，免费）
**Windows**: 从 [官网](https://www.libreoffice.org/download/) 下载安装包
**macOS**: 
```bash
brew install --cask libreoffice
```
**Linux**: 
```bash
sudo apt-get install libreoffice
```

#### 其他工具
```bash
# 文本提取库（已包含在requirements.txt中）
pip install docx2txt

# Microsoft Word支持（需要已安装MS Word）
pip install doc2docx

# Linux/macOS轻量级工具
sudo apt-get install antiword catdoc  # Ubuntu/Debian
brew install antiword catdoc          # macOS
```

### 4. 验证安装
```bash
# 检查Pandoc是否安装成功
pandoc --version

# 运行完整测试套件
python test_converter.py

# 查看支持的转换工具
python word2md.py --install-guide
```

## 📋 使用方法

### 1. 命令行方式

#### 基本转换
```bash
# 自动选择最佳转换器（推荐）
python word2md.py document.docx
python word2md.py document.doc

# 指定使用Pandoc（推荐）
python word2md.py document.docx --engine pandoc
python word2md.py document.doc --engine pandoc

# 指定使用内置转换器（仅支持.docx）
python word2md.py document.docx --engine builtin

# 转换并指定输出路径
python word2md.py document.doc -o output.md
```

#### 批量转换
```bash
# 批量转换（自动检测.doc和.docx文件）
python word2md.py /path/to/documents -b

# 批量转换使用Pandoc
python word2md.py /path/to/documents -b --engine pandoc

# 批量转换并指定输出目录
python word2md.py /path/to/documents -b -o /path/to/output
```

#### 获取帮助
```bash
# 查看命令行帮助
python word2md.py -h

# 查看安装指南（Pandoc + .doc支持工具）
python word2md.py --install-guide
```

#### 命令行参数说明
- `input`: 输入的Word文档路径或目录（支持`.doc`和`.docx`）
- `-o, --output`: 输出文件或目录路径（可选）
- `-b, --batch`: 批量转换模式
- `--engine`: 转换引擎选择 (`auto`, `pandoc`, `builtin`)
- `--install-guide`: 显示安装指南
- `-h, --help`: 显示帮助信息

### 2. 图形界面方式

启动图形界面：

```bash
python word2md_gui.py
```

图形界面功能：
- 📁 文件/目录选择器（支持`.doc`和`.docx`）
- 🔧 转换引擎选择（自动/Pandoc/内置）
- ⚙️ 批量转换模式切换
- 📊 实时转换进度显示
- 📝 详细的转换日志
- 🛠️ 安装指南
- ℹ️ 关于和帮助信息

## 🎯 .doc文件转换流程

当处理`.doc`文件时，工具会按以下优先级尝试转换：

### 策略1: Pandoc直接转换
```
.doc文件 → Pandoc → .md文件
```
- **条件**: Pandoc已安装
- **优点**: 速度快，格式保留较好
- **适用**: 大多数标准.doc文件

### 策略2: 格式转换后转换
```
.doc文件 → LibreOffice/doc2docx → .docx文件 → Pandoc/内置转换器 → .md文件
```
- **条件**: LibreOffice或MS Word可用
- **优点**: 格式保留最佳
- **适用**: 复杂格式的.doc文件

### 策略3: 文本提取转换
```
.doc文件 → antiword/catdoc/docx2txt → 纯文本 → 基础Markdown
```
- **条件**: 有任一文本提取工具
- **优点**: 兼容性最好
- **缺点**: 格式信息丢失
- **适用**: 其他方法失败时的兜底方案

## 支持的格式转换

| Word格式 | Markdown格式 | 说明 |
|---------|-------------|------|
| 标题 1-6 | `# ## ### #### ##### ######` | 自动识别标题级别 |
| 粗体 | `**文本**` | 保留粗体格式 |
| 斜体 | `*文本*` | 保留斜体格式 |
| 下划线 | `**文本**` | 转换为粗体格式 |
| 表格 | Markdown表格 | 保留表格结构 |
| 图片 | `![](image.png)` | Pandoc模式下自动提取 |
| 列表 | `- 项目` 或 `1. 项目` | 有序/无序列表 |
| 链接 | `[文本](URL)` | Pandoc模式下保留 |
| 引用 | `> 引用文本` | 居中文本转为引用 |

## 🧪 测试和验证

### 运行测试套件
```bash
python test_converter.py
```

测试套件包括：
- 📄 **格式检测测试** - 验证文件格式识别
- 🔧 **转换器功能测试** - 测试各种转换场景
- 🛠️ **工具可用性测试** - 检查.doc支持工具
- 📊 **依赖检查** - 验证所需库是否安装

### 手动测试
```bash
# 测试.docx文件
python word2md.py sample.docx

# 测试.doc文件
python word2md.py sample.doc

# 测试批量转换
python word2md.py ./test_documents -b

# 测试图形界面
python word2md_gui.py
```

## 🛠️ 故障排除

### .doc文件转换失败

**问题**: 转换.doc文件时出现错误

**解决方案**:
1. **安装LibreOffice** (推荐)
   ```bash
   # 访问 https://www.libreoffice.org/download/
   ```

2. **安装文本提取工具**
   ```bash
   pip install docx2txt
   ```

3. **手动转换格式**
   - 用Word或LibreOffice打开.doc文件
   - 另存为.docx格式
   - 使用.docx文件进行转换

4. **使用在线转换工具**
   - [Zamzar](https://www.zamzar.com/)
   - [CloudConvert](https://cloudconvert.com/)

### Pandoc相关问题

**问题**: Pandoc转换失败或未检测到

**解决方案**:
1. **安装Pandoc**
   ```bash
   # 查看安装指南
   python word2md.py --install-guide
   ```

2. **使用内置转换器**
   ```bash
   python word2md.py document.docx --engine builtin
   ```

### 依赖问题

**问题**: 缺少必要的Python库

**解决方案**:
```bash
# 安装所有依赖
pip install -r requirements.txt

# 检查依赖状态
python test_converter.py
```

### 文件格式问题

**问题**: 文件格式检测错误或文件损坏

**解决方案**:
1. **检查文件完整性**
   ```bash
   # 运行格式检测
   python test_converter.py
   ```

2. **重新获取文件**
   - 确保文件未在传输中损坏
   - 尝试从原始来源重新获取

3. **使用格式修复工具**
   ```bash
   python doc_format_fixer.py problem_file.doc --diagnose-only
   ```

## 📊 性能对比

| 转换方式 | .docx文件 | .doc文件 | 图片支持 | 格式保真度 | 速度 |
|---------|----------|----------|----------|-----------|------|
| Pandoc | ✅ 优秀 | ✅ 优秀 | ✅ 支持 | 🥇 最佳 | 🥈 中等 |
| 内置转换器 | ✅ 良好 | ❌ 不支持 | ❌ 不支持 | 🥈 良好 | 🥇 最快 |
| 格式转换+Pandoc | ✅ 优秀 | ✅ 优秀 | ✅ 支持 | 🥇 最佳 | 🥉 较慢 |
| 文本提取 | ✅ 基础 | ✅ 基础 | ❌ 不支持 | 🥉 基础 | 🥇 最快 |

## 🎉 使用建议

### 最佳实践
1. **优先使用.docx格式** - 获得最佳转换效果
2. **安装Pandoc** - 显著提升转换质量
3. **安装LibreOffice** - 确保.doc文件兼容性
4. **批量转换前先测试** - 确保转换效果符合预期

### 格式建议
- **简单文档**: 使用内置转换器即可
- **复杂文档**: 推荐使用Pandoc
- **.doc文件**: 建议先转换为.docx格式
- **包含图片**: 必须使用Pandoc

### 性能优化
- **大文件**: 考虑分批处理
- **批量转换**: 使用`--engine pandoc`获得一致效果
- **频繁使用**: 考虑安装所有支持工具

## 📚 常见问题 (FAQ)

**Q: 支持哪些Word格式？**
A: 支持`.doc`（Word 97-2003）和`.docx`（Word 2007+）格式。

**Q: .doc文件转换效果如何？**
A: 取决于可用工具。LibreOffice + Pandoc组合效果最佳，纯文本提取方式格式会丢失。

**Q: 需要安装Microsoft Word吗？**
A: 不需要。推荐安装免费的LibreOffice来处理.doc文件。

**Q: 图片如何处理？**
A: Pandoc模式下会自动提取图片到`images`目录，内置转换器不支持图片。

**Q: 批量转换时如何处理混合格式？**
A: 工具会自动检测每个文件的格式并选择合适的转换策略。

**Q: 转换失败如何处理？**
A: 查看错误信息，运行`python word2md.py --install-guide`获取安装建议，或使用`python test_converter.py`诊断问题。

## 🔗 相关链接

- [Pandoc官网](https://pandoc.org/)
- [LibreOffice官网](https://www.libreoffice.org/)
- [python-docx文档](https://python-docx.readthedocs.io/)
- [项目GitHub](https://github.com/your-repo/word2md)

## 📄 许可证

MIT License - 详见 LICENSE 文件

## 🤝 贡献

欢迎提交问题报告和功能请求！

---

**享受您的Word转Markdown之旅！** 🚀