Markdown変換トラブルシューティング：表・コード・画像の問題を解決

Markdownをきれいに書いて、「変換」ボタンを押したら、出力結果が想像と全然違う。表はぐちゃぐちゃ、コードブロックはただのテキスト、画像は表示されない、LaTeX数式は意味不明な文字列に...。

こんな経験、ありませんか？MarkdownからWord・PDFへの変換は、決まったいくつかのパターンで失敗しがちです。このガイドでは、最もよくある15の問題を取り上げ、それぞれの本当の原因と具体的な解決策を紹介します。

早見表：問題と対処法

---

テーブル関連の問題

問題1：Word出力でテーブルの列がずれる・結合される

症状： Markdownできれいに書いたテーブルが、Word変換後にぐちゃぐちゃになる。列が結合されたり、内容がはみ出したり、テーブル構造自体が壊れたりします。

原因：

一番多い原因は、テーブル構文のミスです。Markdownのテーブルは見た目以上に厳密で、パイプ文字が1つ足りないだけ、あるいはセパレータ行がずれているだけで、テーブル全体が崩壊します。

よくある間違いのパターンはこちらです。

<!-- BROKEN: Missing leading pipe -->
Header 1 | Header 2
--- | ---
Cell 1 | Cell 2

<!-- BROKEN: Separator row doesn't match column count -->
| Header 1 | Header 2 | Header 3 |
| --- | --- |
| Cell 1 | Cell 2 | Cell 3 |

解決策：

パイプの書き方を統一し、列数を揃えましょう。

| Header 1 | Header 2 | Header 3 |
|:---------|:--------:|----------:|
| Left     | Center   | Right     |
| Cell 1   | Cell 2   | Cell 3    |

押さえておきたいルールは以下の通りです。

• すべての行で先頭と末尾にパイプ | を書く
• セパレータ行の列数をヘッダーと一致させる
• アラインメントのコロンを活用する — :--- 左揃え、:---: 中央揃え、---: 右揃え
• セル結合は使わない — Markdown標準では対応していません。どうしてもセル結合が必要な場合は、変換後にWord側で手動編集してください

ちなみに： 変換前にMarkdownリンターやプレビューツールにテーブルを貼り付けて確認する癖をつけると安心です。VS Code、Typora、Obsidianなどは、テーブル構文のエラーを即座に表示してくれます。

---

問題2：Word出力でテーブルの列幅が極端に偏る

症状： Markdownエディタではきれいに見えるテーブルが、Wordに変換すると、1つの列がページ幅の8割を占めて他の列が押しつぶされます。

原因：

ほとんどのMarkdown→Word変換ツールは、セル内容の文字数に基づいて列幅を計算します。1つのセルに長い文章やURLが入っていて、他のセルが短い値の場合、配分のバランスが崩れます。HTMLと違い、Markdownにはテーブルの列幅を指定する構文がありません。

解決策：

• セルの内容を簡潔に。 長い説明文は脚注やテーブル下の段落に移動しましょう
• 長いURLはリンクテキストに変換： セルに生のURLを貼るのではなく [リンクテキスト](url) 形式を使いましょう
• MarkFlow で変換する — デフォルトで列幅を均等に配分するため、ほとんどの変換ツールよりも読みやすいWordテーブルが生成されます

正確な列幅が必要な場合は、Word変換後にテーブルを編集してください。テーブルを選択 → 「テーブルのプロパティ」 → 「列」タブ → 好みの幅を設定できます。

---

問題3：テーブルセル内の特殊文字が構造を壊す

症状： テーブルセル内のパイプ文字 | が列構造を壊したり、HTMLエンティティが生のテキストとして表示されたりします。

原因：

パイプ文字 | はMarkdownテーブルにおける列の区切り文字です。セルの内容にパイプがそのまま含まれていると、パーサーはそれを列境界と判断してしまいます。

解決策：

バックスラッシュでパイプ文字をエスケープしましょう。

| Command | Description |
|:--------|:------------|
| `echo "a \| b"` | Pipes output through filter |
| `status: pass\|fail` | Shows pass or fail status |

テーブルセル内のその他の特殊文字への対処法は以下の通りです。

• パイプ文字には \| を使用
• アンパサンドが必要な場合は & などHTMLエンティティで記述
• インラインコードのバッククォートで囲めば、Markdownの解釈を防げます

---

コードブロック関連の問題

問題4：変換後にコードブロックのシンタックスハイライトが消える

症状： エディタでは美しくハイライトされていたPythonやJavaScriptのコードが、Word出力では色のないモノクロのプレーンテキストになっています。

原因：

主に2つの原因があります。

1. 言語指定がない — 言語を指定せずにトリプルバッククォートだけを使った
2. 変換ツールがハイライト未対応 — 基本的な変換ツールの多くは、Word/PDFエクスポート時にシンタックスハイライトを削除してしまう

違いを見てみましょう。

<!-- NO highlighting — missing language tag -->
```
function hello() {
  console.log("Hello");
}
```

<!-- WITH highlighting — language specified -->
```javascript
function hello() {
  console.log("Hello");
}
```

解決策：

トリプルバッククォートの直後に必ず言語名を指定しましょう。よく使う言語識別子を一覧にしておきます。

言語を指定してもハイライトが反映されない場合は、MarkFlow なら Word でも PDF でもシンタックスハイライトが維持されます。色、フォント、インデントが正しく出力されます。

---

問題5：インラインコードの書式が消える

症状： シングルバッククォートで囲んだ config.yaml や npm install が、変換後のドキュメントでは周囲のテキストと見分けがつかない普通の文字になっています。

原因：

一部の変換ツールはインラインコードをプレーンテキストとして扱い、スタイリングを適用しません。バッククォート構文は認識されますが、出力フォーマットにモノスペースフォントや背景色が含まれていないのです。

解決策：

• インラインコードのスタイリングに対応した変換ツールを使う。 MarkFlow はWord出力でモノスペースフォントと薄い背景色でインラインコードを表現するため、周囲のテキストと視覚的にはっきり区別できます
• インラインコード内でのバッククォートのネストに注意。 コード内にバッククォートが含まれる場合は、二重バッククォートを使ってください：`code with `backtick` → ``code with `backtick` `` のように記述します
• 強調目的でインラインコードを乱用しない。 強調には 太字 や イタリック を使いましょう。バッククォートは実際のコード、コマンド、ファイル名、技術的な識別子に限定するのがベストです

---

問題6：コードのインデントと空白が変わってしまう

症状： Word出力のコードブロックで、インデントがおかしくなっています。すべて左寄せになっていたり、タブが不規則なスペースに変換されたりします。

原因：

MarkdownパーサーとWordのレンダリングエンジンの間で、タブ→スペース変換のルールが異なります。一部の変換ツールは先頭の空白を削除したり、複数のスペースを1つにまとめたりします。

解決策：

• Markdownのコードブロック内ではタブではなくスペースを使いましょう。 多くのスタイルガイドでは2スペースまたは4スペースが推奨されています。タブの解釈は変換ツールによって一貫しません
• インデント方式ではなくフェンス方式のコードブロックを使いましょう。 トリプルバッククォートで囲むフェンス方式の方が確実にパースされます：

<!-- PREFERRED: Fenced code block -->
```python
def nested():
    if True:
        for i in range(10):
            print(i)
```

<!-- AVOID: Indented code block (4 spaces) -->
    def nested():
        if True:
            for i in range(10):
                print(i)

• 変換後すぐに出力を確認してください。 空白がおかしい場合、問題はMarkdownではなく変換ツール側にあります。別のツールに切り替えるか、バグ報告を出しましょう

---

画像関連の問題

問題7：変換後に画像が表示されない

症状： 変換後のWordやPDFドキュメントに、壊れた画像アイコン、空白スペース、または実際の画像の代わりにalt テキストが表示されます。

原因：

変換トラブルで最も多い相談がこれです。原因はほぼ 画像パス に絞られます。

1. 変換ツールが相対パスを解決できない — ![Alt](./images/photo.png) はファイルの場所を知っているエディタでは表示できますが、変換ツールは場所がわからないことがあります
2. 認証が必要なリモートURL — プライベートなGitHubリポジトリ、Googleドライブ、Notionにホストされた画像は変換時にダウンロードできません
3. プロトコルの問題 — file:// パスやローカル絶対パスに対応していない変換ツールがあります
4. 非対応のファイル形式 — SVG、WebP、TIFFの処理に苦戦する変換ツールがあります

解決策：

最も確実なのは、公開アクセス可能な画像URLを使う方法です。

<!-- Most reliable: absolute URL -->
![Architecture diagram](https://your-domain.com/images/diagram.png)

<!-- Also reliable: base64 embedding (for small images) -->
![Icon](data:image/png;base64,iVBORw0KGgo...)

MarkFlow の場合： .md ファイルと画像フォルダをまとめてドラッグ＆ドロップすれば、相対パスは自動的に解決されます。画像URL付きのMarkdownをペーストすれば、画像もWord出力に埋め込まれます。

---

問題8：Word出力で画像が大きすぎる・小さすぎる

症状： Markdownプレビューでは完璧に見える画像が、Word変換後に極端に小さくなったり巨大になったりして、ページレイアウトが崩れます。

原因：

Markdownには画像サイズを指定するネイティブな構文がありません。![alt](url) 形式にはwidthやheightのパラメータがないのです。ほとんどの変換ツールは元のピクセルサイズのまま画像を挿入するため、Wordのページ幅と合わないことがあります。

解決策：

一部のMarkdown方言ではHTMLで画像サイズを制御できます。

<!-- Control image size with HTML -->
<img src="./diagram.png" alt="System architecture" width="600" />

ただし、すべてのMarkdown→Word変換ツールがHTMLタグを処理するわけではありません。選択肢は以下の通りです。

• 元の画像を約600〜800pxの幅にリサイズしてから Markdownに追加する — これがほとんどのWordページレイアウトに収まります
• HTMLのimgタグとwidth属性を使う — 変換ツールがインラインHTMLに対応している場合
• 変換後にWordでリサイズする — 画像を右クリック → 「サイズとプロパティ」 → 幅を希望のパーセンテージに設定

Word出力向け推奨画像サイズ：

• ページ幅いっぱいの画像：600〜800px幅
• インライン図：400〜500px幅
• アイコンやバッジ：100〜200px幅

---

問題9：Base64埋め込み画像が変換に失敗する

症状： Markdownにbase64データURIで埋め込んだ画像がプレビューでは表示されるのに、変換後は壊れた画像になったり完全に削除されたりします。

原因：

Base64エンコードされた画像はファイルサイズが大幅に増加します（バイナリよりおよそ33%大きくなります）。インラインデータURIにサイズ制限を設けている変換ツールや、そもそも data:image/...;base64,... 形式をパースしない変換ツールがあります。

解決策：

• Base64画像は小さめに抑える — 100KB以下（元のバイナリで約75KB）を目安にしてください。アイコンや小さなロゴには向いていますが、スクリーンショットや写真は通常向いていません
• 大きなものはすべて実際の画像ファイルを使う。 ホスティングするか、.md ファイルと一緒に配置しましょう
• 変換ツールのドキュメントでデータURI対応を確認。 MarkFlow はWordと PDF の両方でbase64埋め込み画像に対応していますが、実用上は1画像あたり2MB程度の制限があります

---

LaTeX数式とMermaid図の問題

問題10：LaTeX数式がプレーンテキストのまま表示される

症状： 正しくレンダリングされた数式の代わりに、Word出力では $E = mc^2$ や $$\int_{0}^{1} x^2 dx$$ のような生のLaTeXソースがそのままテキストとして表示されます。

原因：

LaTeX数式のサポートは 標準MarkdownやGFMには含まれていません。KaTeXやMathJaxといった専用のレンダリングエンジンを必要とする拡張機能です。多くの基本的な変換ツール（適切なフラグなしのPandoc、拡張なしのVS Code、Dillingerなど）はLaTeX構文を処理しません。

解決策：

まず、構文が正しいことを確認しましょう。

<!-- Inline math: single dollar signs -->
The formula $E = mc^2$ describes mass-energy equivalence.

<!-- Block math: double dollar signs -->
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

次に、LaTeX対応の変換ツールを使いましょう。

レンダリング失敗につながるLaTeXのよくあるミス：

<!-- WRONG: Space after opening $ -->
$ E = mc^2 $

<!-- CORRECT: No space after opening $ -->
$E = mc^2$

<!-- WRONG: Missing closing delimiter -->
$$\int_{0}^{1} x^2 dx

<!-- CORRECT: Matching delimiters -->
$$\int_{0}^{1} x^2 dx$$

学術論文や技術ドキュメントでは、MarkFlow がLaTeXをWord出力で実際の数式画像にレンダリングします。そのため、数式エディタに対応していないバージョンのWordでも数式が正しく表示されます。

---

問題11：Mermaid図が出力に表示されない

症状： レンダリングされたフローチャートやシーケンス図の代わりに、Word/PDF出力にはMermaidのコードがそのまま通常のコードブロックとして表示されます。

原因：

MermaidはJavaScriptベースのレンダリングエンジンです。視覚的な図を生成するにはブラウザまたはNode.js環境が必要です。ほとんどのMarkdown→Word変換ツールはMarkdownを純粋にテキストとして処理し、JavaScriptを実行しません。そのため、Mermaidブロックは普通のコードとして扱われます。

解決策：

まずMermaid構文が正しいか確認しましょう。

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

MermaidをWord/PDFにレンダリングできるツール：

• MarkFlow — Mermaid図を画像としてWord出力に埋め込みます。フローチャート、シーケンス図、ガントチャートなどに対応
• Typora — プレビューでMermaidをレンダリングし、PDFにエクスポート可能
• Pandoc — mermaid-filter プラグインが必要（npm install -g mermaid-filter）

Mermaid非対応の変換ツールでの回避策：

1. Mermaid Live Editor で図をレンダリング
2. PNGまたはSVGでエクスポート
3. MarkdownのMermaidコードブロックを画像参照に置き換え
4. 通常通り変換

手動の工程が1つ増えますが、どの変換ツールでも確実に図を表示できます。

---

フォーマットと構造の問題

問題12：Word出力で見出しレベルがおかしい

症状： Wordの見出し階層がMarkdownと一致しません。H2がH1として表示されたり、すべての見出しが同じサイズでレンダリングされたりします。

原因：

主に2つの原因があります。

1. MarkdownにH1見出しが複数ある。 ドキュメントのH1は1つ（タイトル）だけにすべきです。複数のH1を検出すると、一部の変換ツールは見出しを統合または再マッピングします
2. 変換ツールがMarkdownの見出しをWordスタイルに異なる方法でマッピングしている。 最初の見出しをそのレベルに関係なくドキュメントタイトルとして扱うツールもあります

解決策：

正しい見出し階層を守りましょう。

# Document Title (H1 — use exactly once)

## Section Title (H2 — main sections)

### Subsection (H3 — within sections)

#### Detail (H4 — rarely needed)

• レベルを飛ばさない — H2からいきなりH4に進まない
• H1はドキュメントの先頭に1回だけ使う。 またはタイトルメタデータから変換ツールに追加させる
• Word出力の「スタイル」パネルを確認 — 見出しは「見出し1」「見出し2」などとして表示されるべきです。「標準」になっている場合、変換ツールが正しくマッピングできていません

---

問題13：ネストしたリストのインデントが失われる

症状： 丁寧にネストした箇条書きや番号付きリストが、Word出力ではすべてフラットになり、すべての項目が同じレベルで表示されます。

原因：

インデントの不統一が原因です。Markdownはネストレベルを検出するために 一貫したスペース を必要とします。タブとスペースの混在や、ある場所では2スペース、別の場所では3スペースといった使い方は、パーサーを混乱させます。

解決策：

ネストレベルごとに 4スペース（または1タブ）を一貫して使いましょう。

- First level item
    - Second level item
        - Third level item
    - Back to second level
- Back to first level

1. First item
    1. Sub-item one
    2. Sub-item two
2. Second item
    - Mixed bullet under number

よくある間違い：

<!-- BROKEN: Inconsistent indentation (2 spaces then 3) -->
- Item A
  - Sub A (2 spaces)
   - Sub B (3 spaces — parser gets confused)

<!-- FIXED: Consistent 4-space indentation -->
- Item A
    - Sub A
    - Sub B

それでもリストがフラットになる場合は、変換ツールを変えてみてください。MarkFlow は、順序付き/順序なしの混在リストを含め、ネストしたリストのインデントをWord出力で維持します。

---

問題14：脚注が消える・壊れる

症状： [^1] のような脚注参照が変換後のドキュメントにリテラルテキストとして表示され、Markdown末尾の脚注内容が欠落するか通常の段落としてレンダリングされます。

原因：

脚注はGFM拡張機能であり、オリジナルのMarkdown仕様には含まれていません。基本的なMarkdownのみに対応している変換ツールでは、脚注構文を処理できません。

解決策：

正しい脚注構文：

This claim needs a source[^1]. Another point here[^note].

[^1]: Smith, J. (2025). "Research Paper Title." Journal Name.
[^note]: This is a longer footnote with multiple sentences.
    Indent continuation lines with 4 spaces.

以下を確認しましょう。

• 参照 [^id] と定義 [^id]: が 同じ識別子 を使っている
• 脚注定義が ドキュメントの末尾 に配置されている（少なくともすべての参照より後）
• 変換ツールが GFM脚注に対応している — MarkFlow、Pandoc、Typoraはすべて正しく処理します

---

問題15：絵文字が空の四角として表示される

症状： ✅、🚀、⚠️ などの絵文字が、Word出力で空の長方形や疑問符として表示されます。

原因：

Wordドキュメントで使用されているフォントに絵文字グリフが含まれていません。変換ツールがMarkdownテキストをWordにマッピングする際、CalibriやTimes New Romanなどの標準フォントを適用しますが、これらのフォントにはUnicode絵文字が含まれていないことがあります。

解決策：

• 変換後の対処： Word上で絵文字を選択し、フォントを「Segoe UI Emoji」（Windows）または「Apple Color Emoji」（macOS）に変更します
• 変換前の対処： 絵文字の表示が重要な場合は、テキスト表記や画像への置き換えを検討しましょう
• 絵文字フォントに対応した変換ツールを使う： MarkFlow は絵文字をWord出力で適切なシステムフォントにマッピングするため、WindowsでもmacOSでも正しく表示されます

---

予防策：変換トラブルを未然に防ぐ方法

変換トラブルの多くは事前に防げます。以下の習慣をMarkdown作成ワークフローに組み込みましょう。

変換前にバリデーションする

Markdownリンターを使い、構文の問題が変換トラブルになる前にキャッチしましょう。

# Install markdownlint CLI
npm install -g markdownlint-cli

# Lint your file
markdownlint document.md

VS Codeユーザーの方は、「markdownlint」拡張をインストールするとリアルタイムでバリデーションされます。

出力に近いプレビューで確認する

エディタのプレビューと変換ツールの出力は、異なるレンダリングエンジンを使用しています。VS Codeで問題なく見えてもWordで崩れることがあります。最終エクスポート前に必ずテスト変換を行いましょう。

Markdownの書き方を統一する

ルールを決めて、一貫して守りましょう。

• インデント： ネストには4スペース
• 改行： ブロック間に空行1つ
• コードブロック： 常にフェンス方式（インデント方式ではなく）、常に言語タグ付き
• 画像： パス形式を統一（すべて相対またはすべて絶対）
• テーブル： すべての行で先頭と末尾にパイプ

テスト用ドキュメントを用意する

使用するすべての要素（テーブル、コードブロック、数式、図、ネストリスト、脚注、絵文字）のサンプルを1つずつ含むMarkdownファイルを用意しておきましょう。ツールを更新するたびにこのファイルを変換ツールに通せば、実際のドキュメントに影響が出る前にリグレッションを発見できます。

---

どの変換ツールを使うべきか

問題によって適切なツールは異なります。

変換ツールの詳しい比較は、MarkdownからPDFへの変換ツール比較をご覧ください。

---

よくある質問

Q: MarkdownのテーブルをWordに変換すると崩れるのはなぜですか？ A: 最も多い原因は、パイプ構文の不統一です。先頭・末尾のパイプの欠落や、列数と一致しないセパレータ行が考えられます。変換前にMarkdownプレビューでテーブル構文を確認してください。

Q: コードブロックのシンタックスハイライトをWord変換後も維持するには？ A: トリプルバッククォートの直後に必ず言語名を指定してください（例：```python）。さらに、Word出力でハイライトを維持する MarkFlow のような変換ツールを使いましょう。

Q: MarkdownからWordへの変換後に画像が表示されないのはなぜですか？ A: 変換ツールが画像パスを解決できていません。リモート画像には絶対URLを使うか、.md ファイルを画像フォルダごとアップロードすれば相対パスを処理できる MarkFlow のようなツールを使いましょう。

Q: LaTeX数式を書式を維持したままWordに変換できますか？ A: はい、ただしLaTeX対応の変換ツールが必要です。MarkFlow、Pandoc（数式フラグ付き）、Typoraはすべて正しくLaTeXをレンダリングします。基本的な変換ツールでは生のLaTeXソースがプレーンテキストとして出力されます。

Q: 変換後のドキュメントでMermaid図がコードとして表示されるのはなぜですか？ A: ほとんどの変換ツールは、Mermaidが必要とするJavaScriptを実行しないためです。Mermaidの自動レンダリングには MarkFlow を使うか、Mermaid Live Editorで図を画像として事前レンダリングしてください。

Q: Word出力でネストリストのインデントを修正するには？ A: Markdownでネストレベルごとにきっちり4スペースを使ってください。タブとスペースの混在は避けましょう。それでも問題が続く場合は、別の変換ツールを試してみてください。ツールによってネストリストの処理品質が異なります。

---

関連リソース

• MarkdownからWordへの変換ツール — テーブル、コード、数式を含むフル書式対応で変換
• MarkdownからPDFへの変換ツール — Markdownから印刷品質のPDFを生成
• MarkdownからHTMLへの変換ツール — クリーンでセマンティックなHTMLを出力
• Markdownの書き方 — 変換トラブルを避けるために構文をマスター
• ChatGPT Markdown出力ガイド — AIツールから構造の整ったMarkdownを得る
• 最高のMarkdownからPDFへの変換ツール — ツールの詳しい比較