VS CodeでMarkdownをPDF出力できない場合、原因は1つとは限りません。
特に多いのは、PDF変換用の拡張機能、ChromeやEdgeなどのブラウザ、出力先フォルダ、権限、Markdown PDFの設定などに問題があるケースです。
また、VS CodeにはMarkdownをプレビューする機能がありますが、標準機能だけでMarkdownをPDFへ変換できるわけではありません。
PDFとして出力するには、Markdown PDFやMarkdown Preview Enhanced、Pandocなどの追加機能を利用するのが一般的です。
ここでは、VS CodeでMarkdownをPDF出力できない代表的な原因と対処方法を詳しく解説します。
PDF出力用の拡張機能をインストールしていない
MarkdownのプレビューとPDF出力は別の機能
VS Codeでは、Markdownファイルを開いて次のショートカットを押すと、標準機能でプレビューを表示できます。
Ctrl + Shift + V
ただし、Markdownをプレビューできるからといって、そのままPDFとして保存できるわけではありません。
PDFに変換したい場合は、一般的に次のような拡張機能やツールを利用します。
- Markdown PDF
- Markdown Preview Enhanced
- Pandoc
そのため、PDF出力の項目自体が見つからない場合は、まずPDF変換に対応した拡張機能がインストールされているか確認しましょう。
Markdown PDFが正常にインストールされていない
拡張機能の状態を確認する
Markdown PDFを使用する場合は、VS Code左側にある「拡張機能」を開き、「Markdown PDF」と検索します。
一般的に使用されている拡張機能は、yzane.markdown-pdfです。
Markdownファイルを開いた状態で、
Ctrl + Shift + P
を押してコマンドパレットを表示し、
markdown-pdf: Export (pdf)
を実行するとPDFを生成できます。
Markdownファイル上で右クリックし、同じコマンドを選択する方法もあります。
この項目自体が表示されない場合は、Markdown PDFがインストールされていない、無効化されている、または正常に読み込まれていない可能性があります。
Markdown PDFのバージョンが古い
古いバージョンではChromium関連の問題が発生する場合がある
Markdown PDFを長期間アップデートしていない場合は、古いバージョンがPDF出力エラーの原因になっている可能性があります。
Markdown PDFは2.x系でブラウザ関連の仕組みが大きく変更されています。
古い1.x系では、同梱または使用されていた古いChromiumに起因する問題が発生するケースがありました。
そのため、古いMarkdown PDFを使用している場合は、まず拡張機能を最新版へ更新することをおすすめします。
VS Codeの拡張機能画面からMarkdown PDFを選択し、「Update」などが表示されていれば更新してください。
ChromeやEdgeを正常に起動できない
Markdown PDFはChromium系ブラウザを利用する
Markdown PDFは、Markdownの内容を直接PDFファイルとして書き込んでいるわけではありません。
MarkdownをHTMLとしてレンダリングし、ChromeやEdge、Chromiumなどのブラウザエンジンを利用してPDFを生成します。
そのため、使用するブラウザを正常に起動できないと、PDF出力に失敗することがあります。
現在のMarkdown PDFでは、おおむね次の順序で利用するブラウザが決定されます。
markdown-pdf.executablePathで明示的に指定したブラウザ- PCにインストールされているChrome、Edge、Chromium
- Markdown PDFが管理するChromium
したがって、Markdown PDFの設定そのものだけでなく、ブラウザ側の状態も確認する必要があります。
Chromiumの自動ダウンロードに失敗している
初回のPDF出力時に問題が起こることがある
Markdown PDFでは、使用できるChromeやEdgeなどが見つからない場合、必要なChromiumを自動的にダウンロードできます。
代表的な設定は次のとおりです。
{
"markdown-pdf.chromium.autoDownload": true
}
通常はtrueになっているため、必要に応じて自動ダウンロードが行われます。
しかし、会社や学校などのネットワークでは、次のような要因によってダウンロードに失敗することがあります。
- プロキシ
- ファイアウォール
- セキュリティソフト
- ネットワークの通信制限
- 外部ファイルのダウンロード制限
初回のPDF出力時に処理が進まない場合は、ネットワーク環境も確認しましょう。
参考サイト
Markdown PDFで Error: Failed to launch the browser process! が発生した際の解消方法 #VSCode – Qiita
executablePathの設定が間違っている
Chromeなどのパスを手動指定している場合に注意する
Markdown PDFでは、markdown-pdf.executablePathを使ってChromeなどの実行ファイルを手動指定できます。
例えばWindowsでは、Chromeが次のような場所にインストールされていることがあります。
C:\Program Files\Google\Chrome\Application\chrome.exe
設定例は次のとおりです。
{
"markdown-pdf.executablePath": "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"
}
WindowsのJSONでは、\をそのまま記述せず、\\として記述する必要があります。
ただし、Chromeのインストール先はPCによって異なります。
他の記事に書かれているパスをそのままコピーするのではなく、自分のPCに実際に存在するパスを指定してください。
また、以前設定したパスにChromeが存在しなくなっている場合も、PDF出力に失敗する原因になります。
PDFの出力先に問題がある
outputDirectoryの設定を確認する
Markdown PDFでは、markdown-pdf.outputDirectoryを使ってPDFの出力先を指定できます。
例えば、次のような設定です。
{
"markdown-pdf.outputDirectory": "output"
}
相対パスを指定した場合は、必要に応じて出力先ディレクトリが作成されます。
一方、絶対パスを指定している場合は、指定先のディレクトリが存在しないとエラーになる場合があります。
例えば、
{
"markdown-pdf.outputDirectory": "C:\\work\\pdf"
}
と設定している場合、C:\work\pdfが実際に存在するか確認してください。
また、出力先に書き込み権限がない場合もPDFを作成できません。
既存のPDFファイルがロックされている
PDFビューアで開いたままになっている場合がある
すでに生成済みのPDFを開いたまま再出力すると、使用しているPDFビューアやWindowsの状態によってはファイルを上書きできないことがあります。
例えば、
sample.md
sample.pdf
が存在していて、sample.pdfを別のアプリで開いたままPDFを書き出そうとすると、ファイルロックや権限エラーが発生する可能性があります。
その場合は、一度PDFビューアを閉じてから再度出力してください。
ただし、すべてのPDFビューアで必ずファイルがロックされるわけではありません。
あくまで上書きに失敗する場合の確認ポイントの1つです。
Markdownファイルの保存場所に書き込み権限がない
Windowsの保護されたフォルダでは注意する
MarkdownファイルをWindowsの保護されたフォルダに保存している場合、PDFを書き込めないことがあります。
例えば、
C:\Program Files\
などは、通常のユーザー権限では自由にファイルを書き込めない場合があります。
原因を切り分けるときは、
C:\Users\ユーザー名\Documents\
など、通常のユーザーが書き込み可能なフォルダへMarkdownファイルを移して試すと分かりやすくなります。
ディスクの空き容量が不足している
PDF生成時には一時ファイルも使用される
MarkdownからPDFを生成するときは、ブラウザの起動やHTMLのレンダリング、一時ファイルの作成などが行われます。
そのため、ディスク容量が極端に不足している場合は、PDF出力に失敗する可能性があります。
Windowsの場合は、特にCドライブの空き容量を確認してみましょう。
セキュリティソフトがChromiumをブロックしている
会社PCではセキュリティポリシーの影響を受けることがある
Markdown PDFが管理するChromiumは、一般的なChromeとは異なる場所から起動されることがあります。
そのため、会社PCや学校PCでは、セキュリティソフトや端末管理ポリシーによって実行をブロックされる可能性があります。
通常のChromeやEdgeは起動できるのにMarkdown PDFだけ失敗する場合は、セキュリティソフトや管理ポリシーも疑ってみましょう。
VS Codeを再起動していない
設定変更後に再起動が必要になる場合がある
markdown-pdf.executablePathなどの設定を変更したあと、状態によってはVS Codeを再起動したほうが確実です。
設定を変更した場合は、
VS Codeを終了
↓
VS Codeを起動
↓
Markdownファイルを開く
↓
PDFを再出力
という順番で確認してみましょう。
ワークスペース設定に問題がある
ユーザー設定とプロジェクト設定は別に確認する
VS Codeには、ユーザー全体に適用される設定と、プロジェクト単位のワークスペース設定があります。
例えば、プロジェクト内の、
.vscode/settings.json
にMarkdown PDF用の設定が記述されていることがあります。
ユーザー設定が正常でも、ワークスペース設定に誤った出力先やブラウザパスが指定されていると、そのプロジェクトだけPDF出力に失敗する可能性があります。
特定のプロジェクトでだけPDF出力できない場合は、.vscode/settings.jsonも確認しましょう。
settings.jsonの記述に問題がある
JSONやJSONCの構文エラーを確認する
Markdown PDFの設定を書き換えたあとに動作しなくなった場合は、settings.jsonの記述ミスも確認してください。
例えば、次のコードでは設定項目の間にカンマがありません。
{
"markdown-pdf.convertOnSave": true
"markdown-pdf.outputDirectory": "pdf"
}
正しくは次のように記述します。
{
"markdown-pdf.convertOnSave": true,
"markdown-pdf.outputDirectory": "pdf"
}
VS Code上でエラーが表示されている場合は、設定内容を修正しましょう。
拡張機能の影響を切り分ける
他のMarkdown関連拡張機能を一時的に無効化する
Markdown関連の拡張機能を複数インストールしている場合、それらが必ず競合するとは限りません。
ただし、原因が分からない場合の切り分け方法として、Markdown PDF以外の関連拡張機能を一時的に無効化する方法は有効です。
例えば、
- Markdown Preview Enhanced
- Markdown All in One
- Markdownlint
などを一時的に無効化し、Markdown PDFだけでPDFを出力できるか確認します。
正常に動作する場合は、他の設定や拡張機能が影響している可能性をさらに調査できます。
PDFは生成されるが画像が表示されない原因
Markdownの画像パスを確認する
PDF自体は生成できるものの、画像だけ表示されない場合は画像パスを確認しましょう。
例えば、
と記述している場合、
article.md
images/
└─ sample.png
のようなファイル構成になっている必要があります。
画像が存在しなかったり、相対パスが間違っていたりすると、PDF内に画像が表示されません。
この問題は、「PDFそのものを生成できない」というより、「PDFは生成できるが内容が正しく表示されない」トラブルとして考えるのが適切です。
PDFは生成されるがCSSが反映されない原因
オンラインCSSに問題がある場合がある
Markdown PDFでは、外部のCSSを読み込んでデザインを調整できます。
ただし、オンライン上のCSSについては、PDF出力時に正常に適用されないケースがあります。
そのため、デザインが反映されない場合は、Web上のCSSではなくローカルCSSを使用すると改善する可能性があります。
PDFが生成できない問題と、CSSが反映されない問題は分けて考えることが重要です。
Raw HTMLが反映されない
Markdown PDFのサニタイズ設定が影響している場合がある
Markdownの中にHTMLを書いている場合、Markdown PDFのバージョンやサニタイズ設定によって、一部のHTMLが削除されたり無効化されたりすることがあります。
例えば、
<style>
.example {
color: red;
}
</style>
や、
<script>
...
</script>
などをMarkdown本文に記述している場合、期待どおりに処理されないことがあります。
この場合も、多くはPDF自体が作成できないというより、PDFの見た目や内容が意図した状態にならない問題として現れます。
以前は正常に表示されていたHTMLがMarkdown PDFの更新後に表示されなくなった場合は、サニタイズ仕様の変更を確認するとよいでしょう。
Front Matterに問題がある
YAMLの記述を確認する
Markdownの先頭にFront Matterを使用している場合は、その記述内容も確認しましょう。
一般的な書き方は次のとおりです。
---
title: Test
author: Taro
---
Markdown PDF 2.xではFront Matterの解析が以前より厳密になっています。
不正なYAMLや、想定されていない構造のFront Matterが含まれている場合は、正常に処理されない可能性があります。
原因を切り分けるときは、一度Front Matterを削除してPDF出力を試す方法も有効です。
Markdown PDFのログを確認する
Outputパネルからエラーを確認する
原因が分からない場合は、推測だけで設定を変更するのではなく、Markdown PDFのログを確認するのが効率的です。
VS Codeで、
表示
↓
出力
を開き、出力パネルから「Markdown PDF」を選択します。
ここには、PDF生成時に発生したエラーや処理状況が表示されます。
例えば、
- Chromiumの起動失敗
- 出力ファイルのロック
- 権限エラー
- ディスク容量不足
- 不正な出力ディレクトリ
などを確認できる場合があります。
Output Diagnosticsを利用する
Markdown PDFの環境情報をまとめて確認できる
現在のMarkdown PDFでは、コマンドパレットから、
Markdown PDF: Output Diagnostics
を実行できます。
これにより、Markdown PDFのトラブルシューティングに必要な情報をまとめて確認できます。
例えば、
- Markdown PDFのバージョン
- VS Codeのバージョン
- OS情報
- 使用しているChromiumのパス
- Chromiumがどの方法で選択されたか
- Markdown PDF関連の設定
などを確認できます。
PDFが生成されない場合は、最初の確認項目として非常に有効です。
原因が分からない場合の確認手順
最小構成のMarkdownでテストする
どこに問題があるか分からない場合は、複雑なMarkdownファイルをそのまま調査するより、単純なテストファイルを作成するほうが効率的です。
例えば、次の内容だけを記述したMarkdownファイルを作成します。
# PDFテスト
これはMarkdown PDFのテストです。
## 見出し
- 項目1
- 項目2
- 項目3
**太字テスト**
このファイルをPDFへ変換します。
正常にPDFを作成できる場合は、VS CodeやMarkdown PDFそのものではなく、元のMarkdownファイルに含まれる画像、HTML、CSS、Front Matterなどに原因がある可能性が高くなります。
逆に、単純なMarkdownでもPDFを作成できない場合は、ブラウザ、権限、出力先、Markdown PDF本体などを優先して確認しましょう。
Windowsで優先的に確認したいポイント
Markdown PDFのバージョンを確認する
まず、Markdown PDFが古い場合は最新版へ更新します。
古いChromium関連の問題を避けるためにも、最初に確認したい項目です。
ChromeやEdgeが正常に認識されているか確認する
Markdown PDFが使用できるChromium系ブラウザを見つけられないと、PDFを生成できません。
Markdown PDF: Output Diagnosticsを利用すると、どのブラウザが選択されているか確認できます。
出力先の権限を確認する
Windowsでは、書き込み権限のないフォルダや保護されたフォルダを出力先にしているとエラーになることがあります。
まずはDocumentsなどの一般的なフォルダでテストすると原因を切り分けやすくなります。
Markdown PDFのOutputログを確認する
原因を特定するときは、Outputログが非常に重要です。
設定を何度も変更する前に、エラーメッセージを確認することで解決が早くなる可能性があります。
VS CodeでMarkdownをPDF出力できないときは原因を順番に切り分けよう
VS CodeでMarkdownをPDF出力できない場合は、まずMarkdown PDFなどのPDF変換用拡張機能が正常に動作しているか確認しましょう。
特に重要なのは、Markdown PDFのバージョン、ChromeやEdgeなどのブラウザ、出力先フォルダ、書き込み権限です。
原因が分からない場合は、
Markdown PDFを最新版へ更新
↓
VS Codeを再起動
↓
単純なMarkdownでPDF出力をテスト
↓
Outputパネルを確認
↓
Markdown PDF: Output Diagnosticsを実行
↓
ブラウザ・出力先・権限を確認
という順番で確認すると効率的です。
また、PDFそのものが作成できない問題と、画像やCSS、HTMLが正常に反映されない問題は分けて考えることが重要です。
この2つを切り分けることで、VS CodeでMarkdownをPDF出力できない原因を特定しやすくなります。
以上、VS CodeでMarkdownをPDF出力できない主な原因についてでした。
最後までお読みいただき、ありがとうございました。
