【VS Code初心者向け・続編】Markdown PDF が PDF を出力しない？Linuxユーザーがハマりやすい注意点

みなさん、こんにちは。

以前の記事で、VS Codeの拡張機能「Markdown PDF」を使って、MarkdownをサクッとPDFに変換する方法をご紹介しました。

【VS Code初心者向け】MarkdownをPDFにサクッと変換 – Markdown PDF拡張機能を使ってみよう

Windows環境ではそれほど大きなトラブルに遭遇しなかったのですが、Linux環境（Ubuntuやその派生ディストリビューションなど）で使ってみると……

  • PDFが出力されない
  • exportPdf() ERROR が発生する
  • Failed to launch the browser process と怒られる
  • ページ数が多いとタイムアウトしてしまう
  • ヘッダーのファイル名が消えてくれない

などなど、意外とハマりどころが多いことに気づきました。

Markdown PDFは「Chrome/Chromiumが必要」という依存関係があるのですが、軽量LinuxユーザーはブラウザにFirefoxをメインで使っているケースも多く、「急に動かなくなって理由が分からない……」と悩みがちです。

そこで今回は、Markdown PDFをLinux環境で安定して動作させるための「忘れがちな前提条件」と「実際に遭遇した問題＆解決策」を分かりやすくまとめました！

前提 – Chrome または Chromium が必須（Firefoxでは動かない）

Markdown PDFは、内部で Puppeteer（パペティア）というツールを使って Chrome や Chromium を裏で起動し、PDFをレンダリングしています。

つまり、Chrome または Chromium がインストールされていない環境では、確実にエラーになります。

軽量Linuxディストリビューションなどを愛用していると、ブラウザはFirefox一本に絞っていることも多いですよね。この前提を知らないまま「Markdown PDFが動かない！」と頭を抱えてしまうケースが本当に多いんです。

典型的なエラーメッセージ

Error: Failed to launch the browser process
exportPdf() ERROR

このエラーが出た場合は、システムにChromeかChromiumが入っていません。まずはGoogle Chrome（またはChromium）をインストールしましょう！

💡ワンポイントアドバイス

Markdown PDFには「Chromiumを自動ダウンロードする機能」も備わっていますが、Linux環境ではOS側の必要なシステムライブラリ（libnss3など）が不足していて起動に失敗することがよくあります。

自動ダウンロードに頼るよりも、apt コマンドや .deb パッケージからGoogle Chromeをシステムに直接インストールしてあげるのが、一番手軽で確実に動く近道です！

Ubuntu系の Chromium（snap版）は遅すぎてタイムアウトする

Ubuntu系ディストリビューションでは、標準で導入される Chromium が Snap版 になっていることが多く、起動が非常に重くなっています。

Markdown PDFはPDFを生成するたびにChromiumを起動するため、Snap版だとページ数の多いPDFを作ろうとしたときに、ほぼ確実にタイムアウト（Puppeteerの30秒制限）を起こしてしまいます。

私も「なぜこんなにタイムアウトするんだろう……」と原因究極にかなり悩まされました。

Snap版 Chromium が重い・タイムアウトする主な理由

  • AppArmorなどの厳格なセキュリティ制限（Confinement）のチェック処理が重い
  • 起動するたびにSnap独自の実行環境セットアップが挟まる
  • フォントキャッシュの構築や共有メモリ（/dev/shm）の制約により、Puppeteerとの相性が悪い

最も効果的な解決策

Google Chrome（deb版）を使う、または deb版のChromium（PPA等）を使う ことです！

インストール後は、VS Codeの settings.json に1行追加し、以下のようにパスを明示的に指定してあげます。

"markdown-pdf.executablePath": "/usr/bin/google-chrome"

実行ブラウザをGoogle Chromeに切り替えるだけで、PDFの生成速度が劇的にアップします。「えっ、こんなに速いの！？」と感動するレベルで変わるので、LinuxでMarkdown PDFを使うならChrome指定はほぼ必須と言ってもいいかもしれません。

ヘッダー／フッター設定は launch_options に書いても無視される

Markdown PDFの設定項目には、大きく分けて以下の2系統があります。

目的正しいキー間違ったキー
Chrome起動オプションmarkdown-pdf.launch_optionsー
PDFのヘッダー／フッターmarkdown-pdf.headerTemplate
markdown-pdf.footerTemplate		launch_options.headerTemplate
(※書く位置が違うので無視されます)

つまり、ヘッダーやフッターのカスタマイズを launch_options の中に書いても絶対に反映されません。

ここもかなりハマりやすいポイントです。私も「設定を書いているのになんで変わらないの！？」と試行錯誤して、半日ほど時間を溶かしてしまいました……。

ヘッダーを完全に消す方法（最もシンプル）

デフォルトで出力されるヘッダー（ファイル名と日付など）を消したい場合も多いですよね？そんな時は、settings.json に1行追加するだけです。

"markdown-pdf.headerTemplate": " "

ダブルクォーテーションで囲われた部分にスペースを一つ入力します。（空だと無視される可能性があるので）

これだけで、

  • ヘッダー → 完全に空（非表示）
  • フッター → デフォルトのページ番号だけが残る

というキレイな状態になってくれます！

「ヘッダーの右側に日付だけ残したい」場合の注意点

「ヘッダーは消したいけれど、右端に作成日付だけはおしゃれに残したい」という場合もありますよね。

ですが、Chrome HeadlessのPDFレンダリングは普通のWebページとCSSの挙動が少し異なり、text-align: right や小さな margin-right が効きにくい特徴があります。

正しく右寄せされるテンプレート

"markdown-pdf.headerTemplate": "<div style='width:100%; font-size:8px;'><span style='float:right; margin-right:60px;'>%%ISO-DATE%%</span></div>"

なぜ margin-right が 60px も必要なの？

Chrome Headlessが描画するヘッダー・フッター領域には、左右に消せない内部パディング（約40〜60px程度）が存在しています。

そのため、margin-right: 10px などの小さな値だと本文の右余白とずれてしまうのです。大きめの数値（60px前後）を指定してあげると、キレイに右寄せされた状態で揃って見えます。

(※お使いの用紙サイズや余白設定によってベストなpx数値は変わりますので、みはみ出さないよう微調整してみてくださいね！)

最終的な推奨設定（軽量Linux環境向け）

これらを踏まえた、settings.json の最終的なおすすめ設定例がこちらです！

{
    "markdown-pdf.executablePath": "/usr/bin/google-chrome",
    "markdown-pdf.headerTemplate": "<div style='width:100%; font-size:8px;'><span style='float:right; margin-right:60px;'>%%ISO-DATE%%</span></div>",
    "editor.fontSize": 18
}

よくあるハマりポイントまとめ

  • Chrome/Chromiumが入っていない → 100%エラーになります
  • Snap版 Chromiumを使っている → 起動が重くタイムアウトの原因に
  • launch_options.headerTemplate に書いている → 完全に無視されます
  • text-align: right だけで右寄せしようとする → 意図通りに動かないことがあります
  • margin-right が小さすぎる → 内部パディングの影響で右揃えになりません

Linux環境で Markdown PDF を快適に使うためのポイント

ポイントは、以下の4つです！

  1. Google Chrome または Chromium（deb版）を用意する
  2. Snap版 Chromium は避けて、executablePath を明示する
  3. ヘッダー・フッターは markdown-pdf.* 系のキーで正しく設定する
  4. 右寄せしたい時は float: right ＋ 大きめの margin-right で調整する

このコツさえ押さえておけば、Linux上の VS Code でのPDF生成がびっくりするほど安定して爆速になりますよ。

「Markdown PDFが動かなくて困っていた……」という方の参考になれば幸いです！

「VS Codeを使うのなら、何か開発してみたい」と思われた方、まずは基本から学んでみるのも一つの手です。

プログラマーのためのVisual Studio Codeの教科書 (Compass Booksシリーズ)

AIの力を借りたとしても、ソフトだけでなくハードがからむ試作だとなかなか思うようには進まないものです。

でも、そのアイデア、頭の中で寝かせておくのはもったいないかもしれません。

ビューローみかみでは、構想段階の壁打ちからPoC・実装・現場導入まで、現場で「使い続けられる」ものづくりを支援しています。

サービス

アイデアを短期間で「動くもの」にし、PoCで終わらせず、実運用まで伴走します。まずは「これ、作る価値ありますか？」という壁打ちからでも大歓迎です。

▶ PoC・MVP開発サービスの詳細はこちら

PoC・MVP開発支援

気になることがあればお気軽にご相談ください。

本日も最後までお読みいただき、ありがとうございました。

それでは、よいLinuxライフを！

カテゴリ: Tips
タグ: ,

関連投稿

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール