Markdown Word 変換：Pandoc コマンドライン完全ガイド

コマンドラインでMarkdownをWordに変換したいなら、答えはpandocです。そして作業全体は次の1行で済みます：

pandoc report.md -f gfm -o report.docx

このコマンドでほとんどの文書はカバーできます。しかし、よくある1行チュートリアルが教えてくれないのは「どこで動かなくなるか」です。しかも、pandocの限界について書かれた情報の一部は、単純に古くなっています。実際にPandoc 3.7で試したところ、意外な結果がいくつかありました。テストではpandoc 3.7.0.2を使い、表、タスクリスト、LaTeX数式、Mermaidダイアグラムを詰め込んだテスト文書を変換し、生成された .docx を解凍して中身を直接確認しています。

このガイドでは、インストール、知っておくべきコマンド、DOCXのスタイル設定、一括変換、そしてそのテストに基づいた正直な見取り図——pandocがどこで破綻し、いつオンライン変換ツールの方が良い選択になるのか——を順に解説します。

👉 テスト結果へジャンプ | コマンドラインとオンラインの比較へジャンプ

Pandoc のインストール

Pandocは単一バイナリで、主要なプラットフォームすべてにインストーラーが用意されています：

• macOS: brew install pandoc
• Windows: winget install --id JohnMacFarlane.Pandoc（またはMSIインストーラー）
• Debian/Ubuntu: sudo apt install pandoc

古いシステムパッケージを信用する前に、1つ注意点があります。ディストリビューションのリポジトリは、何年も前のバージョンのpandocを配布していることが少なくありません。Ubuntu LTSは長らく2.x系を提供してきましたが、現行のリリースラインは3.x系です。後述のとおり、バージョンの古さは「何がきれいに変換できるか」を左右します。手元のバージョンは pandoc --version で確認してください。

基本の変換コマンドを理解する

最小限のコマンドでも動きますが、実際のプロジェクトでは次のフラグが大部分の仕事をこなします：

pandoc report.md -f gfm -o report.docx --toc

なぜpandocデフォルトのMarkdown方言ではなく -f gfm を使うのか。今日多くの人が書いているMarkdown——GitHubのREADME、ChatGPTやClaudeの出力、Notionのエクスポート——はGFMだからです。pandocのデフォルト方言はより学術寄りで、脚注や引用文献が有効になっている一方、いくつかの構文の解釈が異なります。ソースがAIアシスタントや開発者ツール由来なら、gfm の方が安全なリーダーです。

数式についての補足：GFMリーダーでも、現行のpandocでは $...$ と $$...$$ の数式がそのまま機能します。数式は画像ではなく、Wordネイティブの数式になります。この点は後ほど詳しく取り上げます。Web上でもっとも誤って伝えられているpandocの挙動だからです。

リファレンスドキュメントで出力をスタイリングする

pandocが生成したDOCXをWordで開くと、スタイルは汎用的なものになっています。文書を会社のテンプレートに合わせる必要がある場合、フラグでは解決できません——**リファレンスドキュメント（reference-doc）**を使います。

ワークフローは3ステップです：

1. 出発点として、pandocのデフォルトテンプレートを生成します：

   pandoc -o custom-reference.docx --print-default-data-file reference.docx
   

2. custom-reference.docx をWordで開き、スタイル——見出し1、標準、表、コードブロック——を編集します。このファイルの本文の内容は無視され、スタイルとページ設定だけが引き継がれます。

3. テンプレートを適用して変換します：

   pandoc report.md -f gfm --reference-doc=custom-reference.docx -o report.docx
   

どのスタイル名が反映されるかはpandocマニュアルに記載されています。腑に落ちるメンタルモデルはこうです：文書を1つずつスタイリングしているのではなく、組織のWordスタイルを一度だけpandocに教え、以後すべての変換で再利用しているのです。

複数ファイルの一括変換

ここが、コマンドラインがどのWebツールにも本当に勝る領域です。フォルダ全体を変換するには：

Bash（macOS/Linux）：

for f in docs/*.md; do
  pandoc "$f" -f gfm -o "${f%.md}.docx"
done

PowerShell（Windows）：

Get-ChildItem docs -Filter *.md | ForEach-Object {
  pandoc $_.FullName -f gfm -o ($_.FullName -replace '\.md$', '.docx')
}

さらに、pandocは依存関係が1つで済むため、CIにも手間なく組み込めます。プッシュのたびにドキュメントのWord版を再生成するGitHub Actionsのステップは次のようになります：

- uses: pandoc/actions/setup@v1
- run: |
    for f in docs/*.md; do
      pandoc "$f" -f gfm --reference-doc=brand.docx -o "out/$(basename "${f%.md}").docx"
    done

チームはこのパターンを使い、コンプライアンスレビューやクライアント納品物のために、MarkdownウィキのWordミラーを維持しています。同じファイル一式を3回以上変換するなら、このスクリプトはすぐに元が取れます。

Pandoc の限界はどこにあるか（3.7 で検証）

実施したテストの内容はこうです。表、タスクリスト、インライン数式（$E = mc^2$）、複数行のディスプレイ数式、Mermaidのフローチャート、GFMアラートブロックを含む1つのMarkdownファイル。これをpandoc 3.7.0.2で変換し、.docx を解凍して word/document.xml を直接読みました。得られた知見は3つです。

数式は言われているよりうまく動く

文書XMLには <m:oMath> ブロックが2つ——数式1つにつき1つ——含まれていました。これはOMML、つまりWordネイティブの数式フォーマットです。どちらの数式もWordの数式エディタで完全に編集でき、印刷品質でレンダリングされ、他のOffice文書へのコピー＆ペーストにも耐えます。

これは、古いチュートリアル（そして最近まで当サイトのガイドの1つ）に今も残る「複雑なLaTeXは画像にラスタライズされる」という主張と矛盾します。現行のpandocでは、そうはなりません。標準的なLaTeX数式——分数、総和、ギリシャ文字、下付き文字——は、そのままネイティブ数式に変換されます。

正直な境界線はこうです：pandocが解決するのは標準的なLaTeX数式構文であって、任意のLaTeXではありません。カスタムの \newcommand マクロ、TikZ図、パッケージ依存の環境は変換されません。また、ディストリビューションがpandoc 2.xを配布している場合は挙動が異なります——ツールを責める前に pandoc --version を確認してください。

本当の分岐点は Mermaid

Mermaidのフローチャートは、図にはなりませんでした。生の flowchart LR ソースが、コードブロックとしてスタイリングされた等幅テキストのまま出力されたのです。文書XMLに描画オブジェクトは1つもありません。

この問題は5年前よりも今の方が重要です。AIアシスタントはMermaidを多用するからです。ChatGPTやClaudeにアーキテクチャ概要を頼めば、応答に mermaid コードブロックが含まれる可能性は十分にあります。その会話をpandocで変換すると、Word文書には消し忘れたソースコードのようなものが残ります。それがあなたのワークフローなら、ChatGPTの出力をWordにエクスポートするガイドでAI特有の詳細を扱っています。

CLIでの解決策はあります：mermaid-filterという、変換中に図をレンダリングするpandocフィルタです。動作はしますが、セットアップのコストは正直に見積もってください。これはPuppeteer経由でヘッドレスChromiumを取り込むnpmパッケージで、pandocの呼び出しは pandoc -F mermaid-filter ... になります。図を毎日変換するドキュメントパイプラインなら、そのセットアップコストは償却できます。今日の午後が締め切りのレポート1本のためなら、回り道です。

端のほうでの小さな忠実度の損失

同じテストから、目立たない発見が2つありました。GFMアラートブロック（> [!NOTE]）はテキストこそ残るものの、色付きコールアウトの装飾は失われます——Wordでは普通の引用ブロックとして表示されます。また、タスクリストの項目はWordのチェックボックスコントロールではなく、プレーンなリストテキストとして出力されます。どちらも文書を壊すものではありませんが、著者が意図的に選んだであろう書式が平坦化されます。変換が別の形で崩れる場合は、Markdown変換のよくある問題で頻出の失敗パターンをまとめています。

コマンドラインとオンライン変換ツールの使い分け

このテストを踏まえて、実際に使える判断基準はこうなります：

どちらのルートも正当です。Pandocは、繰り返し実行されるパイプラインには確実に居場所があります。一度きりの「5分以内に .docx が必要」というケース——特にMermaidが絡む場合——なら、無料のオンラインMarkdown Word変換ツールを使えば、数式とレンダリング済みの図の両方を含むきれいな文書が、何もインストールせずに手に入ります。

よくある質問

Q: 何もインストールせずにMarkdownをWordに変換できますか？
A: コマンドラインからはできません——pandocはインストールが必要です。ソフトウェアのインストールが選択肢にない場合は、ブラウザベースの変換ツールが現実的な方法です。変換はサーバー側で行われ、完成した .docx をダウンロードするだけです。

Q: pandocはLaTeX数式を本物のWord数式に変換しますか？
A: はい。pandoc 3.7.0.2でのテストでは、インライン数式もディスプレイ数式もネイティブのOMML数式になり、Wordの数式エディタで編集できました。例外は、非常に古いpandocバージョンとカスタムLaTeXマクロです。

Q: なぜMermaid図がWordでコードとして表示されるのですか？
A: pandocは mermaid コードブロックをただのコードとして扱い、図をレンダリングしません。mermaid-filterをパイプラインに追加する（Node.jsが必要）か、Mermaidレンダリングを内蔵した変換ツールを使ってください。

Q: 会社のフォントと見出しスタイルを維持するには？
A: --reference-doc=template.docx を使います。テンプレートのスタイルをWordで一度編集すれば、pandocは毎回の変換でそれを適用します。テンプレートの本文内容は無視され、スタイルだけが引き継がれます。

Q: -f markdown と -f gfm の違いは何ですか？
A: markdown はpandoc独自の拡張方言（脚注、引用文献）です。gfm は、GitHub、ChatGPT、そして最近のほとんどのツールが生成するもの——表、タスクリスト、取り消し線——に一致します。AI生成や開発者が書いたMarkdownなら、gfm の方が想定外の挙動が少なくなります。

Q: pandocでWordからMarkdownへ逆変換できますか？
A: はい——引数を逆にするだけです：pandoc report.docx -o report.md。往復変換ではWord固有の書式（テキストボックス、コメント）が一部失われるため、ロスレスな往復ではなくコンテンツの移行として扱ってください。

関連リソース

• Markdown から Word への完全ガイド：コマンドライン以外も含めた変換手段の全体像
• ChatGPT から Word へ：AI生成ドキュメントのためのMarkdownワークフロー
• Markdown から PDF へ：成果物がPDFの場合はこちら
• Markdown変換のよくある問題：表の崩れ、エンコーディング問題、書式ずれの修正方法

まとめ

「コマンドラインでMarkdownをWordに変換する」という問いへの正解は、今もpandocです。単一ファイルならコマンド1つ、フォルダなら短いスクリプト、会社スタイルなら --reference-doc。テストの結果、数式サポートは評判以上であることが分かりました：標準的なLaTeXは、本物の編集可能なWord数式になります。

本当の弱点はビジュアルです。Nodeベースのフィルタチェーンを組み込まない限り、Mermaid図はソースコードのまま出力されます。だからワークフローで選んでください。プレーンテキスト文書を扱う定期的なパイプラインなら、pandocでスクリプト化を。図と締め切りを抱えた単発の文書なら、ブラウザで変換して数式もフローチャートもそのまま保ちましょう。

参考資料

• Pandoc User's Guide — 公式マニュアル：リーダー、ライター、--reference-doc、数式の扱い
• Installing pandoc — 全プラットフォーム向けの公式インストーラー
• mermaid-filter — Mermaid図をレンダリングするコミュニティ製pandocフィルタ
• pandoc/actions — CIでpandocを使うための公式GitHub Actions