rwadurian/docs/scripts/docx2md/README.md

DOCX 转 Markdown 转换器使用说明

安装依赖

首先安装所需的 Python 库：

pip install -r requirements.txt

或者直接安装 mammoth：

pip install mammoth

使用方法

1. 单文件转换

转换单个 docx 文件为 markdown：

# 自动生成同名 .md 文件
python docx_to_md.py document.docx

# 指定输出文件名
python docx_to_md.py document.docx output.md

2. 批量转换

批量转换整个目录下的所有 docx 文件：

# 在同一目录下生成 .md 文件
python docx_to_md.py --batch ./documents

# 指定输出目录
python docx_to_md.py --batch ./documents ./markdown_output

功能特性

• ✅ 支持标题、段落、列表等基本格式
• ✅ 保留文本样式（粗体、斜体等）
• ✅ 转换表格为 Markdown 表格格式
• ✅ 保留链接
• ✅ 支持单文件和批量转换
• ✅ 自动生成输出文件名
• ✅ 错误处理和转换警告提示

程序化使用

你也可以在自己的 Python 代码中导入使用：

from docx_to_md import docx_to_markdown, batch_convert

# 转换单个文件
docx_to_markdown('input.docx', 'output.md')

# 批量转换
batch_convert('./input_folder', './output_folder')

注意事项

1. 图片处理: mammoth 默认不会提取图片，如果需要处理图片，可能需要额外配置
2. 复杂格式: 非常复杂的 Word 格式可能无法完美转换
3. 编码问题: 程序使用 UTF-8 编码保存 markdown 文件

示例输出

输入 Word 文档：

标题一
这是一段普通文本，包含粗体和斜体。

输出 Markdown：

# 标题一

这是一段普通文本，包含**粗体**和*斜体*。

故障排除

问题：提示 "No module named 'mammoth'"

解决: 运行 pip install mammoth 安装依赖

问题：转换后格式不理想

解决: mammoth 已经是最好的纯 Python 转换方案，如需更好效果可尝试 pypandoc

问题：中文乱码

解决: 程序已使用 UTF-8 编码，确保你的终端也支持 UTF-8

许可证

本程序为示例代码，可自由使用和修改。