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

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

MarkFlowでは、これまで数多くのユーザーがMarkdownをWord、PDF、HTMLに変換してきました。その中でよく報告される変換トラブルを整理し、このガイドにまとめています。全15問、すべて実際に起きる問題と具体的な解決策です。

早見表：問題と対処法

---

テーブル関連の問題

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

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

原因：

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

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

<!-- NG: 先頭のパイプがない -->
Header 1 | Header 2
--- | ---
Cell 1 | Cell 2

<!-- NG: セパレータ行の列数が合っていない -->
| 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テーブルにおける列の区切り文字です。セルの内容にパイプがそのまま含まれていると、パーサーはそれを列境界と判断してしまいます。

解決策：

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

| コマンド | 説明 |
|:--------|:------------|
| `echo "a \| b"` | フィルタにパイプで出力 |
| `status: pass\|fail` | passまたはfailを表示 |

その他の特殊文字への対処法もまとめておきます。

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

---

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

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

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

原因：

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

1. 言語指定がない — トリプルバッククォートだけで言語名を書いていない
2. 変換ツールがハイライト未対応 — 基本的な変換ツールはWord/PDF出力時にシンタックスハイライトを削除してしまう

違いを見てみましょう。

<!-- ハイライトなし — 言語タグなし -->
```
function hello() {
  console.log("Hello");
}
```

<!-- ハイライトあり — 言語を指定 -->
```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つにまとめたりします。

解決策：

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

<!-- 推奨：フェンス方式のコードブロック -->
```python
def nested():
    if True:
        for i in range(10):
            print(i)
```

<!-- 非推奨：インデント方式のコードブロック（4スペース） -->
    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を使う方法です。

<!-- 最も確実：絶対URL -->
![アーキテクチャ図](https://your-domain.com/images/diagram.png)

<!-- こちらも確実：base64埋め込み（小さい画像向け） -->
![アイコン](data:image/png;base64,iVBORw0KGgo...)

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

---

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

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

原因：

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

解決策：

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

<!-- HTMLで画像サイズを制御 -->
<img src="./diagram.png" alt="システムアーキテクチャ図" width="600" />

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

• 元の画像を600-800pxの幅にリサイズしてから Markdownに配置する — これが最も確実です
• 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構文を処理しません。

解決策：

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

<!-- インライン数式：シングルドル記号 -->
式 $E = mc^2$ は質量とエネルギーの等価性を表します。

<!-- ブロック数式：ダブルドル記号 -->
$$
\frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

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

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

<!-- NG: $ の後にスペースがある -->
$ E = mc^2 $

<!-- OK: $ の直後に内容が始まる -->
$E = mc^2$

<!-- NG: 閉じデリミタがない -->
$$\int_{0}^{1} x^2 dx

<!-- OK: デリミタが対になっている -->
$$\int_{0}^{1} x^2 dx$$

---

問題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スタイルに異なる方法でマッピングしている。 最初の見出しをレベルに関係なくドキュメントタイトルとして扱うツールもあります

解決策：

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

# ドキュメントタイトル（H1 — 1回だけ使用）

## セクションタイトル（H2 — メインセクション）

### サブセクション（H3 — セクション内の区分）

#### 詳細（H4 — 必要な場合のみ）

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

---

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

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

原因：

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

解決策：

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

- 第1レベル
    - 第2レベル
        - 第3レベル
    - 第2レベルに戻る
- 第1レベルに戻る

1. 最初の項目
    1. サブ項目1
    2. サブ項目2
2. 2番目の項目
    - 番号付きの下に箇条書き

よくある間違い：

<!-- NG: インデントが不統一（2スペースと3スペースが混在） -->
- 項目A
  - サブA（2スペース）
   - サブB（3スペース — パーサーが混乱）

<!-- OK: 4スペースで統一 -->
- 項目A
    - サブA
    - サブB

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

---

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

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

原因：

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

解決策：

正しい脚注構文を確認しましょう。

この主張には出典が必要です[^1]。別のポイント[^note]。

[^1]: Smith, J. (2025). "Research Paper Title." Journal Name.
[^note]: これは複数文からなる長い脚注です。
    継続行は4スペースでインデントします。

確認すべきポイントは以下の通りです。

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

---

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

症状： チェックマークやロケット、警告サインなどの絵文字が、Word出力で空の四角や疑問符として表示されます。

原因：

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

解決策：

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

---

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

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

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

Markdownリンターで構文の問題を変換前にキャッチしましょう。

# markdownlint CLIをインストール
npm install -g markdownlint-cli

# ファイルをリント
markdownlint document.md

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

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

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

Markdownの書き方を統一する

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

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

Markdownの書き方に慣れていない方は、Markdown基本構文ガイドで各要素を詳しく解説しています。脚注やタスクリストなどの拡張機能については、拡張構文ガイドをご覧ください。

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

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

---

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

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

---

よくある質問

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

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

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

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

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

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

---

関連リソース

• Markdown → Word変換 — フル書式対応で変換
• Markdown → PDF変換 — 印刷品質のPDFを生成
• Markdown → HTML変換 — クリーンなセマンティックHTMLを出力
• Markdown基本構文ガイド — 基本をマスター
• Markdown拡張構文ガイド — 高度な機能とGFM拡張
• Markdown → Word完全ガイド — 変換ワークフローの全体像