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シェルループで複数ファイルを変換
  5. 05変換依存関係を確認

活用シーン

  1. 01Markdownベースのワークフロー向けに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 のサイズを小さく保ちながら（人間にも LLM にも扱いやすく）、図を維持できるように設計されています。

クイックスタート（コピーして貼り付け）

# 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 以降と、PATH 上の markitdown が必要です）
  • フォールバック： 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 の GUI が起動している → LibreOffice を終了して（または killall soffice を実行して）から再試行してください
    • サンドボックス化されたツールランナーで Abort trap: 6 / exit 134 が表示される場合 → サンドボックスの外で .doc を .docx に事前変換してから、.docx を変換してください
  • WMF/EMF の図が表示されない場合：サンドボックス環境では WMF/EMF → PNG の変換がスキップされることがあります。必要に応じて、サンドボックスの外でこれらの画像を PNG に変換してください
  • markitdown not found：./.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 対応