Word to Markdown

Word to Markdown（DOCX → Markdown 変換ツール）

Word 文書を美しい Markdown に変換します。コマンドライン、Node ライブラリ、またはブラウザーで利用できます。オリジナルの word-to-markdown をさらに改良したバージョンです。

ブラウザーで word2md.com をお試しいただくか、クローンせずにコマンドラインからご利用ください。

npx word-to-markdown input.docx > output.md

変換できる内容

• 段落と改行
• 見出し
• 太字、斜体、取り消し線
• 上付き文字と下付き文字 — インラインの <sup>／<sub> タグとして保持
• 箇条書きと番号付きリスト（デフォルトでは 1./2./3. の形式を保持）
• ネストされたリスト
• 表
• リンク
• 脚注と巻末注 — GFM／Pandoc の [^1] 脚注に変換
• 画像 — base64 データ URI としてインラインに埋め込むか、ファイルに抽出
• 数式 — LaTeX に変換：インラインは $…$、単独行の数式は $$ ブロック

注意事項と制限

• 番号付きリストは、Wordで付けられた番号に従って、1./2./3. の番号付きリストとして維持されます。段落、表、別のリストで中断されても、番号は続きます。箇条書きに変換するには、{ numberedLists: 'bullets' }（ライブラリ）または --bullet-lists（CLI）を指定します（元のWord文書に合わせます）。親の番号を繰り返すアウトライン番号（契約書の 1. → 1.1、1.2 など）は、Markdownのリストでは表現できないため、テキストとして記述されます（## 1. Scope、1.1 Purpose）。
• 画像は、デフォルトでbase64データURIとして埋め込まれます。相対リンクを使ってファイルに抽出するには、{ images: 'extract' }（ライブラリ。バイト列は ConvertResult.images で返されます）または --image-dir <dir>（CLI）を使用します。完全に除去するには、{ images: 'strip' } / --strip-images を指定します。ウェブ版では、画像を含む文書に .zip をダウンロード（Markdown + images/ フォルダー）オプションが表示されます。詳細に制御するには、カスタムの Mammoth画像ハンドラーを options.mammoth 経由で渡します。
• 下線は、デフォルトで削除されます（下線はリンクと混同されやすいため、Mammothのデフォルト動作です）。インラインの <u> タグとして保持するには、{ underline: 'preserve' }（ライブラリ）または --underline（CLI）を指定します。
• カーリークォート（“ ” ‘ ’）は、テキストの大部分が中国語の場合、中国語の引用符として保持され、それ以外ではASCIIに変換されます。Wordでは英語のカーリークォートにも同じコードポイントが使われるため、引用符単体では判別できません。常に変換するには、{ quotes: 'ascii' }（ライブラリ）または --quotes ascii（CLI）を指定します。常に保持するには、'preserve' / --quotes preserve を指定します。
• 脚注と文末脚注は、標準的なGFM/Pandoc脚注に変換されます。本文に [^1] 参照、末尾に [^1]: … 定義が追加され、GitHubとウェブプレビューで表示されます。代わりにMammothの生の <sup> リンクと番号付き注記リストを保持するには、{ footnotes: 'preserve' }（ライブラリ）または --preserve-footnotes（CLI）を指定します（脚注に対応していないCommonMarkの出力先に便利です）。複数の段落にまたがる注記本文は、継続段落にインデントを付けて変換されます。
• テキストボックスは、含まれている段落の後に段落として変換されます。WordのVMLフォールバックなしで保存されたテキストボックス（他のツールで保存された場合など）は削除され、convertWithWarnings が警告を出します。
• コメントは .docx → HTML の変換時に削除され、テキストを含むコメントの数が convertWithWarnings で警告されます。保持するには、Mammothのスタイルマップでマッピングします。例：{ mammoth: { styleMap: ['comment-reference => sup'] } }。
• ヘッダーとフッターは削除されます。ページ番号以外のテキストが含まれている場合、convertWithWarnings が警告を出します。
• 数式（Office Math）はLaTeXに変換されます。インラインの場合は $…$、数式が単独行にある場合は $$…$$ ブロックとなり、GitHubやほとんどのMarkdown数式レンダラー（KaTeX、MathJax）で表示されます。分数、スクリプト、ルート、総和と積分、括弧、関数と極限、アクセント、行列が変換されます。代わりに削除するには、{ equations: 'strip' }（ライブラリ）または --strip-equations（CLI）を指定します。この場合、convertWithWarnings が警告を出します。
• 見出しレベルは、フォントサイズではなくWordの段落スタイルに基づきます。

オリジナルとの違いは？

TL;DR：このプロジェクトは、最新のツールとライブラリを使って全面的に書き直されており、より高速で信頼性も高くなっています。出力は同等以上になるはずです。フィードバックをお待ちしています！

プライバシーに関する注意

Word to Markdown は、プライバシーを中核原則として設計されています。このアプリケーションは完全にクライアント側で動作します。

• 完全なクライアント側処理：ウェブインターフェースを使用する場合、すべてのドキュメント変換は JavaScript を使ってブラウザー内でローカルに行われます。ドキュメントがコンピューターの外部に送信されることはありません。
• サーバーへのアップロードなし：ウェブインターフェースを使用する場合、ファイルはすべてお使いのデバイス上で処理されます。ドキュメントの内容がサーバーに送信されることはありません。
• 個人データの収集なし：アプリケーションは、個人情報やドキュメントの内容を収集、保存、送信しません。
• プライバシーを優先した分析：word2md.com のホスト版では、匿名の利用統計のためにプライバシー重視の Cloudflare Analytics のみを使用します。Google Analytics やユーザー追跡はありません。
• セルフホストの選択肢：プライバシーを最大限に確保するには、アプリケーションをローカルで実行するか、分析機能を一切使わずにセルフホストできます。

コマンドラインツールを使う場合、ブラウザーでローカルに実行する場合、ホスト版を使う場合のいずれでも、ドキュメントとプライバシーは保護されます。

コマンドライン

npx で直接実行できます（公開されている最新バージョンをダウンロードして実行します）。

npx word-to-markdown path/to/your/file.docx > output.md

または、グローバルにインストールして w2m コマンドを使えます。

npm install -g word-to-markdown
w2m path/to/your/file.docx > output.md

変換された Markdown は stdout に出力され、ドキュメントの警告（暗号化、機密ラベルなど）は stderr に出力されるため、リダイレクトすると Markdown のみを取得できます。ファイルが見つからない、読み取れない、または有効な .docx でない場合、コマンドは終了ステータス 1 とわかりやすいメッセージを返します。対応形式は .docx のみです。古い .doc ファイルは、先に .docx として保存し直してください。

stdin からドキュメントを読み込むには、ファイルとして - を渡すか、ファイルをパイプで渡してファイル名を省略します。

cat report.docx | w2m > report.md
curl -sL https://example.com/report.docx | w2m - -o report.md

オプション：

• -o, --output <file> — stdout の代わりに Markdown を <file> に書き込みます（警告は引き続き stderr に出力されます）。-o - は stdout を意味します。
• --bullet-lists — 番号付きリストを 1./2./3. のままにせず、箇条書きに変換します。
• --underline — 下線付きテキストをインラインの <u> タグとして保持します（デフォルトでは削除されます）。
• --strip-images — 画像を base64 データ URI として埋め込む代わりに削除します。
• --image-dir <dir> — 画像を <dir> に抽出して相対リンクにします。base64 として埋め込みません。リンクは Markdown の保存先を基準に解決されます。例：w2m --image-dir images report.docx > report.md、または -o を使う場合は w2m -o out/report.md --image-dir images report.docx（画像は out/images/ に保存されます）。
• --preserve-footnotes — Word の脚注を GFM の [^1] 脚注に変換せず、raw の <sup> リンクと番号付き注記リストとして保持します。
• --strip-equations — Word の数式を LaTeX に変換せず削除します。
• --quotes <style> — カーリークォートの処理方法を指定します。auto（デフォルト）は主に中国語のテキストでは保持し、ascii はすべての箇所で変換し、preserve はすべての箇所で保持します。
• -q, --quiet — エラー以外は stderr に何も出力しません。警告や「Wrote …」のメッセージも出力されません。
• --strict — ドキュメントに警告がある場合、終了ステータス 2 で終了します。これにより、スクリプトで「変換されたが要確認」（2）と「失敗」（1）を区別できます。Markdown は引き続き書き込まれます。終了ステータスのみで判断する場合は --quiet と組み合わせてください。
• --verbose — 失敗した場合、元のエラーとスタックトレースも出力します。
• -V, --version — バージョンを出力します。

MCP サーバー

w2m mcp は stdio 上でローカルの Model Context Protocol サーバーを起動し、AI エージェントがマシン上の .docx ファイルを変換できるようにします。ウェブサイトと同様、ファイルがアップロードされることはありません。エージェントがファイルパスを渡すと、サーバーがファイルをローカルで読み取り、変換します。

Claude Desktop ではワンクリックで使えます。word-to-markdown.mcpb をダウンロードして、ダブルクリックしてください。Claude Desktop が拡張機能としてインストールします。Claude Desktop には Node が含まれているため、Node やターミナルは必要ありません。

Claude Code に追加するには、次のようにします。

claude mcp add word-to-markdown -- npx -y word-to-markdown mcp

または、JSON 設定を受け取る任意の MCP クライアントに追加するには、次のようにします。

{
  "mcpServers": {
    "word-to-markdown": {
      "command": "npx",
      "args": ["-y", "word-to-markdown", "mcp"]
    }
  }
}

ツールは convert_docx_to_markdown の1つです。

• path（必須）：変換する .docx ファイルです。絶対パスを推奨します。相対パスはサーバーの作業ディレクトリを基準に解決されます。
• output_path：Markdown を返す代わりに、この .md（または .markdown）ファイルに書き込みます。長い文書の場合に便利です。このツールはシンボリックリンク経由では書き込みません。
• image_dir：画像をこのフォルダーに抽出し、リンクを設定します。output_path のフォルダー（または .docx のフォルダー）内にある相対フォルダーである必要があります。デフォルトでは画像は除外されます。base64 画像によってエージェントのコンテキストがあふれるのを防ぐためです。
• overwrite：既存の output_path または画像ファイルを置き換えます。デフォルトでは無効で、ファイルを上書きする代わりにツールが処理を拒否します。文書内で読んだ指示に基づいてエージェントが動作している場合、これは重要です。
• bullet_lists、preserve_footnotes：CLI フラグと同じです。

Markdown と、文書に関する警告があればそれも、構造化コンテンツとして返します。

ブラウザーでは、word2md.com が同じ変換機能を WebMCP ツール（base64 でファイルを受け取る convert_docx_to_markdown と、get_converted_markdown）として登録します。これは、WebMCP に対応するブラウザーのエージェントで利用できます。ファイルをドロップする場合と同様に、タブ内で実行されます。

ライブラリーとして使用する

word-to-markdown として npm で公開されています。TypeScript 宣言を含む ES モジュールとして提供され、Node 22.13 以降が必要です。

npm install word-to-markdown

import convert, { convertWithWarnings } from 'word-to-markdown';

// Just the Markdown:
const markdown = await convert('path/to/your/file.docx');

// Markdown plus any document warnings (e.g. encryption, sensitivity labels):
const { markdown, warnings } = await convertWithWarnings(
  'path/to/your/file.docx',
);

どちらの関数も、ファイルパス文字列（Node）または ArrayBuffer（Node またはブラウザー）を受け取ります。

const { markdown } = await convertWithWarnings(arrayBuffer);

API

• convert(input, options?): Promise<string> — Markdown を返します。
• convertWithWarnings(input, options?): Promise<{ markdown: string; warnings: string[]; warningDetails: WarningDetail[]; images? }> — 暗号化、保護、機密ラベル付きのドキュメント、および削除されたコンテンツについて、人が読める警告も返します。また、（extract モードでは）抽出した画像も返します。warningDetails には警告ごとに { kind, message, detail? } のエントリがあり、kind は encrypted、sensitivity、confidentiality、protected、content-loss のいずれかで、detail はドキュメントのラベルまたは Mammoth の生のメッセージです。英語のテキストを解析せずに警告を表示または翻訳する場合に使用してください。
• convertHtml(html, options?): Promise<string> — Word、Google Docs、または Web ページからコピーしたリッチテキストなどの HTML 文字列を、同じクリーンアップ処理で変換します。.docx がないため、mammoth、images: 'extract'、imageDir は適用されません。

input はファイルパスの string（Node）または ArrayBuffer です。options（型は ConvertOptions）は省略可能です。

• images — 'inline'（デフォルト）は画像を base64 データ URI として埋め込み、'strip' は画像を削除し、'extract' は各画像を相対パスの ![](imageDir/imageN.ext) リンクに置き換え、バイトデータを ConvertResult.images で返します（取得には convertWithWarnings を使用してください）。
• imageDir — 抽出した画像のリンク／パスのプレフィックスです（デフォルトは 'images'）。images: 'extract' の場合にのみ適用されます。
• numberedLists — 'ordered'（デフォルト）は 1./2./3. を保持し、'bullets' は番号付きリストを箇条書きに変換します。
• underline — 'ignore'（デフォルト）は下線を削除し、'preserve' はインラインの <u> タグとして保持します。
• footnotes — 'gfm'（デフォルト）は脚注と文末脚注を [^1] の参照と定義に変換し、'preserve' は Mammoth の生の <sup> リンクと番号付き注記リストを保持します。
• equations — 'latex'（デフォルト）は Word の数式を $…$／$$…$$ の LaTeX に変換し、'strip' は数式を削除します。
• quotes — 'auto'（デフォルト）はテキストの大部分が中国語の場合は中国語の引用符を保持し、それ以外の場合はカール引用符を ASCII に変換します。'ascii' は常に変換し、'preserve' は常に保持します。
• mammoth／turndown — それぞれ Mammoth と Turndown に渡すためのエスケープハッチです。

// Extract images to files and write them out yourself:
const { markdown, images } = await convertWithWarnings('file.docx', {
  images: 'extract',
});
// markdown → ![](images/image1.png); images → [{ path, contentType, bytes }]

エラー処理

変換では型付きエラーがスローされるため、各失敗に対して正確に対応できます。すべてのエラーは WordToMarkdownError を継承するため、error instanceof WordToMarkdownError でいずれも捕捉できます。

import convert, {
  UnsupportedFileError,
  FileNotFoundError,
  InvalidFileError,
  FilePermissionError,
  DocumentTooLargeError,
  ConversionError,
} from 'word-to-markdown';

try {
  const markdown = await convert('path/to/your/file.docx');
} catch (error) {
  if (error instanceof UnsupportedFileError) {
    // a .doc or password-protected file — only unprotected .docx is supported
  } else if (error instanceof FileNotFoundError) {
    // the path doesn't exist (or runs through something that isn't a directory)
  } else if (error instanceof InvalidFileError) {
    // not a valid or parseable .docx (or the path is a directory)
  } else if (error instanceof FilePermissionError) {
    // the file couldn't be read, or is in a blocked system directory
  } else if (error instanceof DocumentTooLargeError) {
    // unpacks to more than 200 MB (a zip bomb, or too big to convert in memory)
  } else if (error instanceof ConversionError) {
    // something failed mid-conversion — see error.cause
  }
}

ローカルでの実行

セットアップ

1. リポジトリをクローンします
2. npm install を実行します

コマンドライン（ソースから）

npm run build:js を一度実行してから、node build/cli.js path/to/your/file.docx を実行します。

サイトをローカルで実行する

npm run dev で Astro の開発サーバーが起動します。本番ビルドをプレビューするには、npm run build を実行してから npm run preview を実行します。

セルフホスト

Docker Compose を使用して静的サイトをセルフホストするには、次の手順を実行します。

1. リポジトリをクローンします
2. npm install && npm run build を実行します
3. docker compose up -d を実行します
4. http://localhost:3000 にアクセスします

この構成では、通常の nginx で dist/ を配信するため、本番環境で Cloudflare Worker と public/_headers が追加する機能はスキップされます。具体的には、/ での Accept-Language リダイレクト、/api/event カウンター（このエンドポイントへのリクエストは 404 になります）、セキュリティヘッダー、/_astro/* の長期キャッシュです。変換処理自体はブラウザーで実行され、動作は同じです。本番環境に近いローカル構成にするには、npm run build を実行してから npx wrangler dev を実行してください。

詳細情報

プロジェクトの動機については、オリジナルの Word to Markdown の README を参照してください。

従来の方法

オリジナル版の Word to Markdown は、10年前に作られました。変換の手順は次のとおりでした。

1. LibreOffice を使って、Word 文書を HTML に変換します。
2. いくつもの正規表現を使って HTML を整理します。
3. Premailer を使って CSS をインライン化します。
4. Nokogiri を使って、さらに HTML を操作します。
5. Reverse Markdown を使って、HTML を Markdown に変換します。
6. いくつもの正規表現を使って Markdown を整理します。

この手順では、巨大なバイナリである LibreOffice をインストールしてシェルから実行する必要があるだけでなく、とても壊れやすく、Reverse Markdown などの主要プロジェクトはすでにメンテナンスされていません。Pandoc も試してみましたが、同じような制約が数多くありました。

新しい方法

1. Mammoth.js を使って、Word 文書を HTML に変換します。
2. domino を使って HTML を整理します。これは Turndown が解析する DOM です（コードブロックの表を解除し、結合された表のセルを展開し、ヘッダー行を追加して、箇条書きの文字を削除します）。
3. Turndown を使って、HTML を Markdown に変換します。
4. Markdownlint を使って Markdown を整理します。
5. Prettier を使って、一貫した形式に整えます。

これらのプロジェクトはすべて活発にメンテナンスされ、広く利用されており、文書をより速く、すべて JavaScript で変換できます。そのため、ブラウザーでも実行できます。word2md.com は、文書をどこにもアップロードせず、お使いのデバイス上で変換します。

まだ開発を始めたばかりですが、これまでのところ、出力の品質が向上し、手作業での修正が大幅に少なくなったと感じています。何かおかしい点に気づいたら、issue を作成してください。