mcpField
D
doc-to-markdown

doc-to-markdown

github.com/sheepmao文档处理11154 次安装39 周前更新
代码仓库

关于 doc-to-markdown

将 Microsoft Word 的 .doc 和 .docx 文件转换为 Markdown 的 Python 工具，可将图片另存为文件夹并生成相对链接，或嵌入 Markdown。适合整理供人或 LLM 阅读且需保留示意图的文档。

主要功能

  1. 01将 .doc 和 .docx 转为 Markdown
  2. 02导出图片并生成链接
  3. 03以 base64 嵌入图片
  4. 04通过 Shell 循环批量转换
  5. 05检查转换依赖

适用场景

  1. 01为基于 Markdown 的工作流准备 Word 文件
  2. 02将示意图与转换后的文档配套保存
  3. 03生成含嵌入图片的单个 Markdown 文件
  4. 04检查本地转换环境

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sheepmao/doc-to-markdown-skill --skill doc-to-markdown

安装后在 Claude Code 中输入/doc-to-markdown确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

convert_word_to_markdown.py
README.md
test_clean_markdown.py
clean_markdown.py
setup_venv.sh
convert_doc_to_docx.py
convert_with_images.py
.gitignore

详细介绍

Doc-to-Markdown（Word → Markdown）

将 Microsoft Word .doc / .docx 转换为：

  • 一个整洁的 Markdown 文件（.md）
  • 以及一个可选的图片文件夹（*_images/），其中包含相对图片链接

此工具旨在保持 Markdown 文件小巧（便于人类和大模型使用），同时保留图表。

快速开始（复制/粘贴）

# 1) Convert a single file (.docx or .doc)
python3 convert_word_to_markdown.py "path/to/document.docx"

# 2) Embedded mode (single self-contained .md, very large)
python3 convert_word_to_markdown.py --embedded "path/to/document.docx"

# 3) If anything fails, run a dependency check
python3 convert_word_to_markdown.py --check
批量转换（当前文件夹）
for f in *.doc *.docx; do
  [ -e "$f" ] || continue
  python3 convert_word_to_markdown.py "$f"
done

输出

默认（外部图片）：

document.docx
document.md
document_images/
  image1.png
  image2.png
  ...

嵌入模式：

document.docx
document.md   # contains base64 images

要求

  • 推荐（最可靠）： 在此仓库的本地虚拟环境中安装 markitdown
    • bash setup_venv.sh
    • （手动）python3.11 -m venv .venv + .venv/bin/python -m pip install 'markitdown[all]'
  • 替代方案： 全局安装 markitdown
    • python3 -m pip install 'markitdown[all]'（需要 Python 3.10+，且 markitdown 位于 PATH 中）
  • 后备方案： 使用 uv（提供 uvx），以便脚本无需通过 pip 安装即可运行 markitdown
    • macOS：brew install uv
  • 要支持 .doc（旧版）格式： 安装 LibreOffice（brew install --cask libreoffice）

环境变量覆盖（提高可靠性）

  • MARKITDOWN_UVX_PYTHON=3.11（默认值）——更改 uvx 使用的 Python 版本
  • MARKITDOWN_UVX_OFFLINE=0——允许 uvx 使用网络（默认：离线）
  • MARKITDOWN_CMD="... markitdown"——覆盖完整命令（高级选项）
  • UV_CACHE_DIR=/tmp/uv-cache——如果 uvx 无法写入其缓存目录，可使用此设置（默认：./.uv-cache/）

常见故障

  • .doc 转换失败：
    • LibreOffice 图形界面正在运行 → 退出 LibreOffice（或运行 killall soffice）后重试
    • 如果在沙盒化的工具运行器中看到 Abort trap: 6 / 退出代码 134 → 在沙盒外先将 .doc 转换为 .docx，然后再转换 .docx
  • WMF/EMF 图表无法显示：在沙盒环境中，可能会跳过 WMF/EMF → PNG 转换步骤；如有需要，请在沙盒外将这些图片转换为 PNG
  • 找不到 markitdown：创建 ./.venv/（推荐）或全局安装 markitdown
  • Failed to initialize cache at ~/.cache/uv：设置 UV_CACHE_DIR=/tmp/uv-cache 后重试

说明

  • convert_word_to_markdown.py 是入口点（同时处理 .doc 和 .docx）。
  • convert_with_images.py 是内部辅助脚本，仅支持 .docx。

评论

支持 Markdown