【ITニュース解説】5 Pitfalls I Hit Rendering Markdown Tables to PNG with Headless Chrome
2026年09月09日に「Dev.to」が公開したITニュース「5 Pitfalls I Hit Rendering Markdown Tables to PNG with Headless Chrome」について初心者にもわかりやすく解説しています。
ITニュース概要
プログラムでブラウザを動かすHeadless Chromeを使い、Markdownの表をPNG画像に変換する際、注意すべき5つの落とし穴についてまとめている。
ITニュース解説
システムエンジニアの仕事では、Webページやデータを目に見える形に変換する場面がよくある。例えば、Markdown形式で書かれた表を、画像ファイル（PNG）として出力するようなケースだ。Markdownとは、文章を簡単に記述できる軽量なマークアップ言語で、開発者の間で広く利用されている。しかし、この一見単純そうな作業も、いざ自動化しようとすると様々な落とし穴に直面することがある。この記事では、Markdownで記述された表を「Headless Chrome」という技術を使ってPNG画像に変換する際に経験した5つの具体的な問題点と、それらをどのように解決したかを解説する。
まず、Headless Chromeとは、画面表示なしで動作するWebブラウザのことで、WebページのテストやPDF変換、画像生成など、自動化処理によく使われる。そして、「Puppeteer」は、このHeadless ChromeをJavaScriptなどのプログラムから操作するためのライブラリだ。Webブラウザをコードで制御できるため、人が手作業で行うようなブラウザ操作を自動化できるのが大きな利点となる。
最初の問題は、画像生成のタイムアウトだ。Webページの内容は一瞬で完全に表示されるわけではない。特にJavaScriptによって動的に生成される部分は、読み込みや処理に時間がかかる。もし、必要なコンテンツが完全にレンダリングされる前にスクリーンショットを撮ってしまうと、画像が一部欠けていたり、空白の部分が含まれてしまったりする。これを解決するには、次の処理に進む前に、特定の要素が完全に表示されるまで「待つ」ことが重要だ。例えば、Puppeteerにはpage.waitForSelectorというメソッドがあり、特定のHTML要素（CSSセレクターで指定）がページに表示されるまで待機できる。より高度なケースでは、page.waitForFunctionを使って、JavaScriptの関数を実行し、その結果が特定の条件を満たすまで待つことも可能だ。記事の筆者は、表内のすべての<td>要素（表のデータセル）がレンダリングされるまで待つことで、この問題を解決した。
二つ目の問題は、レスポンシブデザインの悪影響だ。Webサイトは通常、画面表示用と印刷用で異なるスタイル（CSS）を持つことがある。CSSとは、Webページの見た目を定義する言語のことだ。例えば、印刷時には背景画像や特定の要素を表示しないようにする設定がされている場合がある。Headless Chromeがデフォルトで印刷用のスタイルを適用しようとすると、画面で見ていた通りの画像にならない場合がある。これを避けるためには、Headless Chromeに対して「画面表示用のスタイルを使ってレンダリングしてほしい」と明示的に指示する必要がある。Puppeteerのpage.emulateMediaType('screen')というメソッドを使うことで、Headless Chromeが印刷用ではなく、通常の画面表示用のCSSルールを適用するように強制できるため、ブラウザで見たそのままの見た目を画像として出力できる。
三つ目の問題は、HTMLとCSSのインジェクションの問題だ。Markdownのレンダリング結果は、単一の<table>要素（表を定義するHTMLタグ）だけになる場合もあれば、それをさらに<div>要素（汎用的なブロック要素）で囲む場合もある。page.setContentというメソッドは、指定したHTML文字列をブラウザの現在のページに読み込ませる機能だが、単にテーブルのHTMLだけを渡すのではなく、<html>, <head>, <body>といった基本的なHTML構造の中にスタイルシート（CSS）とテーブルのHTMLを正しく配置することが、意図した通りの表示を実現するために不可欠になる。CSSは通常<head>タグ内に配置され、ページの見た目を定義する。筆者は、<html><head>${styles}</head><body>${html}</body></html> のようなテンプレートで、レンダリングしたいHTMLとCSSを明示的に適切な位置に挿入することで、スタイルが正しく適用されるようにした。
四つ目の問題は、ページサイズの制御と余白だ。デフォルトでHeadless Chromeがスクリーンショットを撮ると、ページ全体の大きな画像が生成され、意図しない余白が含まれてしまうことが多い。これを解決するには、ブラウザの「表示領域」のサイズと、スクリーンショットを撮る「範囲」を正確に制御する必要がある。page.setViewportというメソッドは、ブラウザがどのくらいの画面サイズでページをレンダリングするかを制御する。これにより、コンテンツのレイアウトが適切に調整される。さらに、page.screenshotメソッドのclipオプションを使うと、ページ全体のスクリーンショットを撮るのではなく、指定した座標と幅、高さの範囲だけを切り取って画像にできる。筆者は、出力したいテーブルの実際のサイズを測定し、そのサイズに合わせてclipオプションを設定することで、不要な余白を一切含まない、目的のテーブル部分だけの画像を生成した。また、omitBackground: trueというオプションを使うことで、背景を透明にして出力することも可能だ。
最後の五つ目の問題は、フォントのレンダリングの一貫性だ。Headless Chromeが動作するサーバー環境では、通常のPCに比べて利用できるフォントが限られている場合がある。そのため、画像にしたときにフォントが期待通りに表示されない、あるいは文字がつぶれて見えるといった問題が起きやすい。フォントとは、文字の書体のことだ。これを解決する最も効果的な方法は、「Webフォント」を利用することだ。Webフォントとは、インターネット上からダウンロードして利用するフォントのことで、CSSでWebフォントを指定しておけば、どの環境でも同じフォントで表示されるようになる。筆者はGoogle Fontsのようなサービスからフォントを読み込み、CSSで明示的に指定した。さらに、フォントのアンチエイリアス（文字のギザギザを目立たなくする処理）を調整するためのCSSプロパティである-webkit-font-smoothing: antialiased; と -moz-osx-font-smoothing: grayscale; を適用することで、フォントの表示品質を向上させ、より滑らかで鮮明な見た目を実現した。
これらの問題を一つ一つ丁寧に解決していくことで、システムエンジニアはHeadless Chromeを使ったWebコンテンツの画像生成を、より信頼性が高く、期待通りの結果が得られるように自動化できる。Webブラウザの挙動やWeb技術の知識が不可欠だが、それぞれの課題に対応する適切なツールや設定を理解することで、複雑な要件にも対応できるようになる。