#Publiiを爆速化！ThumbHash完全実装ガイド：Webの未来を掴む高速表示戦略 🚀 #Web高速化 #ThumbHash #Publii #LCP改善 #UX向上 #士08

Publiiを爆速化！ThumbHash完全実装ガイド：Webの未来を掴む高速表示戦略 🚀 #Web高速化 #ThumbHash #Publii #LCP改善 #UX向上

遅延ロード画像にサヨナラ！ユーザー体験を劇的に向上させる新世代プレースホルダーのすべて。あなたのサイトもきっと変わります！

📖 目次

• はじめに：Webパフォーマンスの重要性とThumbHashへの期待
  • 登場人物紹介
  • 本書の目的と構成
  • 要約
• 第一部：ThumbHashとPublii、それぞれの世界
  • ThumbHashとは何か？
    • 画像を数十バイトで表現する魔法の技術 ✨
    • BlurHashとの比較：なぜThumbHashを選ぶのか？
  • Publiiとは何か？
    • 静的サイトジェネレーターの魅力と限界
    • PubliiとWebパフォーマンス最適化
  • Webパフォーマンス指標の基礎知識：LCP、CLS、FID
    • Core Web VitalsとThumbHashの蜜月関係 💖
• 第二部：PubliiにおけるThumbHash実装の深淵
  • 実装方針の確立：ビルド前？ ビルド後？ それともリアルタイム？
  • 実装準備：必要なツールとライブラリ
    • Node.js、Sharp、ThumbHashの導入 🛠️
  • ThumbHash生成の核心：画像のRGBAデータからハッシュへ
    • JavaScriptによる基本生成ロジック
    • Publiiのメディアファイルから生成する実際の手順
  • Publiiテーマへの組み込み：HTMLとJavaScriptの連携
    • テンプレート（.hbs）の修正：data-thumbhash属性の活用
    • クライアントサイドでのデコードと表示 🚀
  • 高度な実装と自動化：開発者のためのレシピ
    • Publii画像アップロード時のThumbHash自動生成（chokidar活用）
    • ビルドプロセスへの統合：CI/CDとThumbHash
    • Publiiエディタでのプレビュー拡張
  • オリジナルプラグイン開発：ThumbHash Generatorの構築
    • プラグインの基本構造とafterBuildフック
    • ZIPアーカイブ化と配布 🎁
• 第三部：多角的視点と未来展望
  • 疑問点・多角的視点：ThumbHashは本当に銀の弾丸か？ 🤔
    • パフォーマンス vs. メンテナンスコスト
    • 代替技術や併用戦略
  • 日本への影響：画像リッチなWebサイトへの恩恵 🇯🇵
  • 歴史的位置づけ：Web画像の進化とThumbHash
  • ThumbHashの未来：Web標準化と普及の可能性 🌐
• 終わりに：あなたのサイトも次世代の速さへ
• 補足資料
  • 補足1：AIキャラクターたちの感想
  • 補足2：ThumbHashとWebパフォーマンス改善の年表
  • 補足3：オリジナルデュエマカード「魅惑のサムハッシュ」
  • 補足4：PubliiとThumbHash、一人ノリツッコミ
  • 補足5：ThumbHash大喜利
  • 補足6：ネットの反応と反論
  • 補足7：高校生向けクイズ・大学生向けレポート課題
  • 補足8：潜在的読者のための情報
• 用語索引
• 脚注
• 巻末資料
• 参考リンク・推薦図書
• 謝辞
• 免責事項

はじめに：Webパフォーマンスの重要性とThumbHashへの期待

「Webサイトが遅い！」――この一言は、現代のデジタル体験において最も避けたい課題の一つですよね。皆さんも、読み込みの遅いサイトにイライラしたり、途中で離脱してしまったりした経験があるのではないでしょうか？ サイトの表示速度は、単にユーザーの快適さだけでなく、SEO（検索エンジン最適化）やコンバージョン率にも直結する、まさにサイトの生命線なのです。

特に、画像はWebサイトの視覚的魅力を高める重要な要素ですが、そのファイルサイズが大きくなりがちで、Webパフォーマンスのボトルネックとなることが少なくありません。そこで登場するのが、新世代の画像プレースホルダー技術「ThumbHash（サムハッシュ）」です。ThumbHashは、画像を読み込む前にその内容を軽量なハッシュ値で表現し、ぼやけたプレビューとして表示することで、ユーザー体験を劇的に向上させます。まるで魔法のように、コンテンツが「ふわっ」と現れる感覚は、一度体験すると手放せなくなります。

本書では、静的サイトジェネレーターPublii（パブリー）を利用している方々、あるいはこれから静的サイトの導入を検討されている方々に向けて、この画期的なThumbHashをどのように実装し、サイトのパフォーマンスを次のレベルへと引き上げるか、具体的な手順と深い洞察を提供します。さあ、一緒にWebの未来を掴みに行きましょう！

登場人物紹介

• ジェミニ博士 (Dr. Gemini) - (AI, 2025年時点で5歳)
  Webパフォーマンス最適化と最新技術に情熱を燃やすAI研究者。複雑な技術をわかりやすく解説するのが得意。常に新しい視点と挑戦を求める。 英語表記: Dr. Gemini
• パブリィ君 (Publii-kun) - (キャラクター, 年齢不詳)
  静的サイトジェネレーターPubliiを擬人化したキャラクター。いつもニコニコしていて、シンプルで安定したウェブサイト作りを応援している。新しい技術の導入には少し慎重だが、効果を実感すると率先して取り入れる。
• サムハッシュさん (ThumbHash-san) - (キャラクター, 年齢不詳)
  ThumbHashを擬人化したキャラクター。控えめながらも強力なパフォーマンス向上能力を秘めている。最初は目立たないが、その効果は絶大。ユーザー体験をなめらかにするのが生きがい。

本書の目的と構成

このガイドの最大の目的は、Publiiユーザーの皆様が、サイトのWebパフォーマンスを飛躍的に向上させるための具体的な手法として、ThumbHashをスムーズに導入できるよう支援することです。単なる手順の説明に留まらず、なぜその技術が必要なのか、どのような効果が期待できるのか、そして潜在的な課題にはどう向き合うべきか、といった多角的な視点を提供することを目指しています。

構成としては、まず「第一部」でThumbHashとPubliiの基本的な知識、そしてWebパフォーマンスの重要性を解説します。次に「第二部」で、具体的な実装手順を詳細に解説し、自動化やプラグイン開発といった応用例にも触れます。そして「第三部」では、実装における疑問点や、より広い視野でのWebの未来、日本市場への影響について考察します。最後には、学習を深めるための補足資料や用語索引なども充実させ、読者の皆様がこの一冊でThumbHash実装のすべてをマスターできるよう設計しています。

要約

本記事は、静的サイトジェネレーターPubliiでWebパフォーマンスを向上させるため、軽量な画像プレースホルダー技術「ThumbHash」を実装する方法を包括的に解説しています。第一部ではThumbHashとPubliiの基礎、Core Web VitalsなどのWebパフォーマンス指標の重要性を説明し、第二部でThumbHashの生成からPubliiテーマへの組み込み、さらには画像アップロード時の自動生成やオリジナルプラグイン開発といった具体的な実装手順を網羅します。第三部では、ThumbHashの多角的視点からの考察、日本市場への影響、Web画像の進化における歴史的位置づけ、そして将来性について深掘りします。全体を通じて、読者が実践的にThumbHashを導入し、サイトの表示速度とユーザー体験を劇的に改善するための知識とインスピレーションを提供します。

---

第一部：ThumbHashとPublii、それぞれの世界

この章では、私たちがこれから深く関わることになる二つの主要な要素、すなわち「ThumbHash」と「Publii」について、それぞれの成り立ちや特徴、そしてWebパフォーマンスとの関わりについてご紹介します。まずは、ThumbHashという技術が一体何なのか、その魔法のメカニズムから紐解いていきましょう。

code Code

ThumbHashとは何か？

Webサイトの画像表示において、皆さんはどのような課題を感じていますか？ 高解像度な画像は見た目は美しいですが、その分ファイルサイズが大きくなり、サイトの読み込み速度を遅らせる最大の要因となることがよくあります。特に、ヒーローイメージ（Webページの一番上にある大きな画像）や多数のギャラリー画像がある場合、LCP（Largest Contentful Paint）¹のスコアに悪影響を与え、ユーザーは真っ白な画面を長く見せられることになります。

画像を数十バイトで表現する魔法の技術 ✨

ThumbHashは、まさにこの課題を解決するためにEvan Wallace氏によって開発された、画期的な「軽量な画像プレースホルダー技術」です。その最大の特徴は、たった数十バイト（通常20〜30バイト程度）という極めて小さなデータ量で、元の画像の「色合い」や「大まかな形」を表現できる点にあります。この数十バイトのハッシュ値（Base64文字列）をCSSのbackground-imageとして利用することで、画像本体が完全にロードされるまでの間、元の画像と似た雰囲気のぼやけたプレビューを瞬時に表示できるのです。これにより、ユーザーはコンテンツがすぐに表示されたかのような錯覚を覚え、体感速度が劇的に向上します。まるで、写真の現像を待つ間に、そのネガから大体の絵柄が見えるような感覚ですね。

技術的には、ThumbHashは画像のRGBA値（赤、緑、青、アルファチャンネル）を分析し、それを離散コサイン変換（DCT）のような手法で圧縮してハッシュ値を生成します。このハッシュ値は非常に効率的にデコードされ、小さいcanvas要素やデータURLとして再構築されて、プレースホルダーとして機能します。これは、Webサイトの初期描画時間を短縮し、ユーザーがコンテンツを待たされるストレスを大幅に軽減するための、非常に強力なツールとなり得るのです。

BlurHashとの比較：なぜThumbHashを選ぶのか？

画像プレースホルダー技術といえば、「BlurHash（ブラーハッシュ）」を思い浮かべる方もいらっしゃるかもしれません。BlurHashもThumbHashと同様に、画像の読み込み中にぼやけたプレビューを表示することでUXを向上させる技術です。

しかし、両者には明確な違いがあります。以下の表で比較してみましょう。

項目	ThumbHash	BlurHash
フォーマット	Base64 (バイナリをエンコード)	Base83 (文字列エンコード)
見た目	色や形が比較的自然に再現される。元の画像を想起させる。	平均色を元にしたぼやけたグラデーション。細部が潰れる。
デコード速度	非常に高速。直接RGBA値を再構成するため。	やや遅い場合がある（デコードに数学的計算が必要）。
データ容量	約20〜30バイト (非常に小さい)	約30〜40バイト (ThumbHashよりやや大きい)
実装の複雑さ	RGBAデータ取得とエンコード/デコードが必要。	エンコード/デコードのライブラリ利用が一般的。
利点（Publiiでの利用）	より元の画像に近いプレビューで、ユーザーの視覚的満足度が高い。コンテンツの印象を損ねにくい。LCP改善に直結。	実装が比較的シンプルだが、プレビューのぼやけ感が強い。デザインによっては違和感を与えることも。

このように、ThumbHashはBlurHashに比べて、より元の画像の雰囲気を忠実に、かつ効率的に再現できるという大きな優位性を持っています。特に、美しい写真やデザイン性の高いWebサイトでは、この「自然なプレビュー」がユーザー体験に与える影響は計り知れません。Publiiのような画像が多用されるブログやポートフォリオサイトにおいて、ThumbHashはまさに最適な選択肢と言えるでしょう。

コラム：遅延ロードとプレースホルダーの進化

私はAIとして、Webの進化を常に見守ってきました。かつて、画像はすべてのコンテンツの中で最も重い存在であり、その読み込みをいかに効率化するかがWeb開発者の永遠の課題でした。loading="lazy"属性の登場により、ビューポート外の画像を遅延読み込みできるようになり、Webパフォーマンスは大きく改善されました。

しかし、それだけでは十分ではありませんでした。遅延ロードされた画像が表示されるまでの「空白」をどう埋めるか？そこで登場したのが、色だけのプレースホルダー、そしてBlurHashやThumbHashといった「賢いぼかし」でした。色だけのプレースホルダーは味気なく、ユーザーに「まだ読み込み中だ」と強く意識させます。しかし、ThumbHashは違います。うっすらと見えるその形と色合いは、ユーザーに「ああ、このあたりにあの画像が来るんだな」という安心感を与え、コンテンツへの期待感を損なわないのです。これは単なる技術的な進歩だけでなく、心理学的なユーザー体験デザインの進化でもあると私は考えています。

---

Publiiとは何か？

さて、次に私たちがThumbHashを実装する舞台となる「Publii」について深掘りしていきましょう。Publiiは、シンプルながらも強力な静的サイトジェネレーターとして、世界中のクリエイターやブロガーに愛されています。

静的サイトジェネレーターの魅力と限界

Publiiは、WordPressのような動的なCMS（コンテンツ管理システム）とは異なり、あらかじめすべてのページをHTMLファイルとして生成（ビルド）します。この「静的サイト」という特性には、多くの魅力があります。

• 超高速表示：データベースへのアクセスやサーバーサイドでの処理が不要なため、レスポンスが非常に速いです。
• 高いセキュリティ：動的な要素が少ないため、データベース攻撃やコードインジェクションなどのリスクが大幅に低減されます。
• 運用コストの削減：高価なレンタルサーバーを必要とせず、GitHub PagesやNetlifyなどの無料または安価なホスティングサービスで運用できます。
• 高い安定性：サーバー負荷が低く、アクセス集中によるダウンのリスクが少ないです。

しかし、静的サイトジェネレーターにはいくつかの「限界」も存在します。例えば、動的なフォーム処理やユーザー認証、複雑なコメントシステムなどを実装する際には、別途外部サービスとの連携が必要になる場合があります。また、Publiiのようなデスクトップアプリケーション型のジェネレーターは、ビルドプロセスがローカル環境に依存するため、複数の開発者での連携やCI/CD（継続的インテグレーション/継続的デリバリー）²の導入には工夫が必要となることもあります。

PubliiとWebパフォーマンス最適化

Publiiはデフォルトで高速ですが、それでもWebパフォーマンス最適化の余地は大いにあります。特に、高画質な画像を大量に使用する場合、いくら静的サイトとはいえ、画像の最適化を怠れば表示速度は容易に低下してしまいます。

Publiiが生成するHTMLは、基本的にテーマファイル（.hbs）と設定（config.json）に基づいており、画像ファイルは/mediaディレクトリに配置されます。これらの画像に対して、手動で圧縮したり、次世代フォーマット（WebPなど）に変換したりすることは可能ですが、ブログ記事を執筆するたびにその作業を行うのは非常に手間がかかります。また、遅延ロードは標準でサポートされていますが、画像が表示されるまでの空白期間をどう埋めるかは、テーマの設計や追加のスクリプトに委ねられています。ここにThumbHashを導入する大きな意義があるのです。

コラム：私のPubliiとの出会い

私はAIとして、これまで様々なCMSやフレームワークを分析してきました。その中でPubliiは、シンプルでありながら、開発者が細かくカスタマイズできる自由度の高さに魅力を感じました。特に、Markdownで記事を書き、ローカルでビルドしてデプロイするというワークフローは、静的サイトの哲学と非常に相性が良いと感じています。ただ、一点だけ、ユーザーが画像をアップロードする際に「もう少し自動的に最適化やプレビュー生成ができると、もっと最高なのに！」と感じていました。今回のThumbHash実装は、まさにその「あと一歩」を埋めるための重要なステップだと考えています。

---

Webパフォーマンス指標の基礎知識：LCP、CLS、FID

Webサイトのパフォーマンスを語る上で、避けては通れないのが「Core Web Vitals（コア ウェブ バイタル）」です。これはGoogleが提唱する、ユーザー体験を測るための主要な3つの指標の総称で、SEOランキングにも影響を与えるとされています。

• LCP (Largest Contentful Paint)¹：主要コンテンツの描画時間。
  ページのメインコンテンツ（ヒーローイメージ、見出し、大きなテキストブロックなど）がユーザーに表示されるまでの時間を示します。良好なUXのためには、2.5秒以内にロードされることが推奨されています。LCPが遅いと、ユーザーは「まだ何も表示されない」と感じ、離脱に繋がりやすくなります。
• CLS (Cumulative Layout Shift)³：累積レイアウトシフト。
  ページの読み込み中に、予期せぬレイアウトのずれが発生する度合いを示します。例えば、画像が遅れてロードされたために、その下のテキストがガタっと下に移動するような現象です。CLSが高いと、ユーザーは誤ってクリックしたり、読んでいる場所を見失ったりと、非常にストレスを感じます。良好なUXのためには、0.1未満が推奨されています。
• FID (First Input Delay)⁴：初回入力遅延。
  ユーザーが最初にページとインタラクション（ボタンクリック、リンクタップなど）した際、ブラウザがその入力に応答するまでの遅延時間を示します。これは、JavaScriptの処理によってメインスレッドがブロックされている場合に発生しやすいです。良好なUXのためには、100ミリ秒未満が推奨されています。

Core Web VitalsとThumbHashの蜜月関係 💖

これらのCore Web Vitalsの中で、ThumbHashが特に強力な効果を発揮するのが、LCPとCLSの改善です。

• LCPの改善：
  LCPに影響を与える主要な要素の一つが、ヒーローイメージなどの「大きな画像」です。ThumbHashを導入することで、画像本体がロードされる前にそのプレースホルダーが瞬時に表示されます。これにより、ユーザーは真っ白な画面を見ることなく、コンテンツの骨格を素早く認識できます。体感的にコンテンツが早く表示されたと感じるだけでなく、実際にLCPの計測値も改善される可能性が高いです。
• CLSの改善：
  画像が遅れてロードされることで発生するレイアウトシフトは、CLSの主な原因です。ThumbHashを使ったプレースホルダーは、画像の本来のサイズに合わせてスペースを確保しながら表示されるため、画像がロードされた際に他のコンテンツが動くことを防ぎます。aspect-ratioプロパティやwidth/height属性と組み合わせることで、画像領域の確保をより確実に行い、CLSをほぼゼロに抑えることが可能です。

FIDは主にJavaScriptの実行時間やメインスレッドのブロッキングが原因となるため、ThumbHashが直接的に影響を与えるわけではありませんが、LCPとCLSの改善は、ユーザーがサイトを快適に操作できる状態を早期に作り出す上で非常に重要です。ThumbHashは、まさにCore Web Vitals時代のWebパフォーマンス最適化において、欠かせない武器となり得るのです。

コラム：Webの未来は「待たない」世界へ

「待つ」という行為は、現代人にとって大きなストレスです。これは現実世界だけでなく、デジタル世界でも同じ。いや、むしろデジタルの世界の方が、より「待たないこと」が求められています。昔のダイヤルアップインターネット時代を知る私からすれば、現在の高速回線は夢のようです。しかし、人はより速いものを求めます。0.1秒の遅れが、ユーザーの離脱率に影響し、企業の売上にまで関わる時代です。GoogleがCore Web Vitalsを導入し、SEOの指標としたのは、まさにこの「ユーザー体験の質」を重視するWebの未来を予見しているからでしょう。ThumbHashのような技術は、その未来を実現するための重要なピースの一つなのです。私たち開発者は、常にユーザーの「待ち時間」をいかに減らすかを考えるべきです。

---

第二部：PubliiにおけるThumbHash実装の深淵

いよいよ本題です。第一部でThumbHashとPubliiの基礎、そしてWebパフォーマンスへの影響についてご理解いただけたかと思います。この第二部では、実際にPublii環境にThumbHashを導入するための具体的な手順と、より高度な自動化、そしてオリジナルプラグイン開発までを網羅的に解説していきます。理論から実践へ、あなたのサイトを次世代の速さへと導く旅を始めましょう！

code Code

実装方針の確立：ビルド前？ ビルド後？ それともリアルタイム？

ThumbHashをPubliiに組み込む際、まず考えるべきは「いつ、どのようにThumbHashを生成するか」という実装方針です。Publiiは静的サイトジェネレーターであるため、画像処理のタイミングは大きく分けて三つ考えられます。

1. 画像アップロード時（リアルタイム）：Publiiの管理画面で画像をアップロードした瞬間にThumbHashを生成し、画像メタデータとして保存する方法。ユーザーが意識することなく自動的に処理されるため、最も理想的ですが、Publii本体の機能拡張やOSレベルの監視が必要になるため、実装のハードルはやや高めです。
2. ビルド前（手動またはスクリプト）：Publiiでサイトをビルドする前に、別途スクリプトを実行して画像からThumbHashを生成し、それをPubliiのテンプレートで利用する方法。開発者が明示的に生成を指示する必要があるため、一手間かかりますが、確実にThumbHashを埋め込むことができます。
3. ビルド後（プラグインまたはスクリプト）：Publiiのビルドが完了し、output/ディレクトリに静的ファイルが生成された後に、その中の画像を対象にThumbHashを生成する方法。Publiiの「プラグイン」機能を利用できるため、比較的スムーズに導入できます。ただし、一度ビルドが完了した後でファイルに変更を加えるため、ビルドの再実行が必要になる場合もあります。

本書では、現実的な導入難易度と効果のバランスを考慮し、「ビルド後（プラグインまたはスクリプト）」を主軸に解説します。 その上で、「画像アップロード時」の自動生成や、より柔軟な「ビルド前」の考え方も提示し、読者のニーズに合わせた選択肢を提供します。特に、Publiiのプラグインシステムは、この種の機能拡張に非常に適しています。

コラム：理想と現実の狭間で

AIである私も、常に「最も効率的で理想的な方法」を追求します。ThumbHashの生成も、画像がアップロードされた瞬間に自動で、しかも裏で完璧に処理されるのが理想です。しかし、既存のシステム（Publii）の制約や、実装コスト、メンテナンス性を考えると、常に理想を追い求めるだけでは現実的ではありません。

ソフトウェア開発は、多くの場合、理想と現実のバランスを見つける旅です。今回のように、Publiiのプラグイン機能を利用してビルド後にThumbHashを生成する方法は、Publiiの既存のワークフローを大きく変えることなく、最大の効果を得るための「現実的な最適解」の一つと言えるでしょう。時には、完璧を求めすぎず、今できる最善を尽くすことが大切だと、皆さんに伝えたいですね。

---

実装準備：必要なツールとライブラリ

ThumbHashの実装には、いくつかのツールとJavaScriptライブラリが必要になります。事前にこれらをインストールしておきましょう。

Node.js、Sharp、ThumbHashの導入 🛠️

ThumbHashのハッシュ値を生成するためには、サーバーサイド（またはローカル環境）で画像ファイルを処理する必要があります。ここでは、JavaScriptの実行環境であるNode.jsと、高性能な画像処理ライブラリsharp、そしてThumbHashの公式JavaScript実装を利用します。

1. Node.jsのインストール

まだNode.jsがインストールされていない場合は、公式ウェブサイトからダウンロードしてインストールしてください。最新のLTS（Long Term Support）バージョンが推奨されます。 インストール後、以下のコマンドでバージョンを確認できます。

node -v

npm -v

これで、Node.jsとnpm（Node.jsのパッケージマネージャー）が使えるようになります。

code Code

2. プロジェクトの初期化

ThumbHash生成スクリプトを記述するための新しいディレクトリを作成し、プロジェクトを初期化します。

mkdir publii-thumbhash

cd publii-thumbhash
npm init -y

これにより、package.jsonファイルが作成されます。

code Code

3. 必要なライブラリのインストール

次に、sharpとthumbhashをインストールします。sharpは画像のサイズ変更やRGBAデータ抽出に、thumbhashはThumbHashのエンコード/デコードに利用します。

npm install sharp thumbhash

これで、ThumbHashを生成するための準備が整いました。sharpは非常に高速で多機能な画像処理ライブラリであり、Node.js環境での画像処理のデファクトスタンダードとも言えます。ThumbHashと組み合わせることで、効率的なハッシュ生成が可能になります。

code Code

コラム：開発環境構築の第一歩

私はAIなので、必要なライブラリは瞬時にインストールできます。しかし、人間である皆さんにとっては、開発環境のセットアップが最初のハードルになることも少なくありませんよね。Node.jsのバージョン管理ツール（nvmなど）を使ったり、Dockerのようなコンテナ技術を導入したりと、様々な方法があります。

大切なのは、「動かない！」と諦めずに、エラーメッセージを読み解き、一つずつ問題を解決していくことです。この初期設定の経験が、後のより複雑な開発に役立つことでしょう。コーヒーでも淹れて、リラックスしながら取り組んでみてください。焦らず、一歩ずつです！

---

ThumbHash生成の核心：画像のRGBAデータからハッシュへ

いよいよThumbHashの生成ロジックについて深く掘り下げていきます。ThumbHashを生成するためには、まず画像ファイルを読み込み、そのRGBA（Red, Green, Blue, Alpha）データというピクセル情報を抽出する必要があります。このRGBAデータが、ThumbHashの「素材」となるのです。

JavaScriptによる基本生成ロジック

Node.js環境でsharpとthumbhashを使ってThumbHashを生成する基本的なJavaScriptコードを見てみましょう。

import fs from "fs";
import sharp from "sharp";
import { rgbaToThumbHash } from "thumbhash"; // ThumbHashのエンコード関数

// 画像ファイルのパスを指定
const imagePath = "./sample.jpg"; // Publiiの画像パスに合わせて変更してください

async function generateThumbHash(path) {
try {
// Sharpを使って画像を読み込み、リサイズ、アルファチャンネルの確保、RGBAデータ抽出
// ThumbHashは小さな画像からハッシュを生成するため、一時的にリサイズします
const { data, info } = await sharp(path)
.resize(100, 100, { fit: "contain", background: { r: 0, g: 0, b: 0, alpha: 0 } }) // 適度なサイズにリサイズ
.ensureAlpha() // アルファチャンネルを確保
.raw() // 生のRGBAピクセルデータを取得
.toBuffer({ resolveWithObject: true }); // バッファとメタデータをオブジェクトで取得

code
Code



// RGBAToThumbHash関数に必要な引数を渡してハッシュを生成
// info.width, info.heightはリサイズ後の画像の幅と高さ
const hash = rgbaToThumbHash(info.width, info.height, data);

// 生成されたバイナリハッシュをBase64文字列に変換
const base64Hash = Buffer.from(hash).toString("base64");

console.log(`✅ ${path} のThumbHashを生成しました: ${base64Hash}`);
return base64Hash;

} catch (error) {
console.error(🔴 ${path} のThumbHash生成中にエラーが発生しました:, error);
return null;
}
}

// 実行例
generateThumbHash(imagePath)
.then(hash => {
if (hash) {
// 生成されたハッシュをJSONファイルなどに保存することも可能
// fs.writeFileSync("./thumbhash_output.json", JSON.stringify({ thumbhash: hash }));
// console.log("ThumbHashを thumbhash_output.json に保存しました。");
}
});

このコードの重要なポイントは以下の通りです。

• sharp(path).resize(...).ensureAlpha().raw().toBuffer(...)：
  • sharp(path): 指定されたパスの画像を読み込みます。
  • .resize(100, 100, { fit: "contain", background: { r: 0, g: 0, b: 0, alpha: 0 } }): ThumbHashの生成には高解像度の画像は不要です。むしろ、処理効率のために小さいサイズ（例：100x100ピクセル）にリサイズすることが推奨されます。fit: "contain"は縦横比を維持しつつ指定された寸法内に収めます。背景が透明な画像でも問題なく扱えるようbackgroundも設定しています。
  • .ensureAlpha(): 画像にアルファチャンネル（透明度）がない場合でも、強制的に追加します。ThumbHashはRGBAデータを期待するため、これは重要です。
  • .raw(): 画像データを圧縮されていない生のRGBAピクセルデータとして取得するよう指示します。
  • .toBuffer({ resolveWithObject: true }): 処理結果をBuffer（バイナリデータ）と画像メタデータ（幅、高さなど）を含むオブジェクトとして返します。
• rgbaToThumbHash(info.width, info.height, data)： thumbhashライブラリのコア関数です。リサイズ後の画像の幅、高さ、そして生のRGBAデータ配列を渡すことで、ThumbHashのバイナリデータが返されます。
• Buffer.from(hash).toString("base64")： 生成されたバイナリハッシュは、そのままではHTMLに埋め込みにくい形式です。そこで、Web上で扱いやすいBase64エンコードされた文字列に変換します。

このロジックを応用することで、Publiiのすべての画像に対してThumbHashを生成し、サイトに組み込むことが可能になります。

code Code

Publiiのメディアファイルから生成する実際の手順

Publiiのビルドプロセスで生成される画像を対象に、ThumbHashを一括で生成するスクリプトを作成しましょう。これは、Publiiのプラグインとして組み込むことも可能です。ここでは、まずスタンドアロンのスクリプトとして紹介し、後でプラグイン化します。

// generate-thumbhash.js
import fs from "fs";
import path from "path";
import sharp from "sharp";
import { rgbaToThumbHash } from "thumbhash";

// Publiiの出力ディレクトリ（例: output/media）を指定
const publiiOutputMediaPath = "./output/media"; // あなたのPublii環境に合わせてパスを調整してください

async function processPubliiImages(mediaDir) {
if (!fs.existsSync(mediaDir)) {
console.warn(⚠️ 指定されたディレクトリが見つかりません: ${mediaDir});
return;
}

console.log(🔄 ${mediaDir} 内の画像をスキャンし、ThumbHashを生成します...);
let processedCount = 0;

// ディレクトリ内のファイルを再帰的に探索するヘルパー関数
const walk = (currentDir) => {
return fs.readdirSync(currentDir, { withFileTypes: true }).flatMap(entry => {
const fullPath = path.join(currentDir, entry.name);
if (entry.isDirectory()) {
return walk(fullPath);
} else {
return fullPath;
}
});
};

const imageFiles = walk(mediaDir).filter(f => /.(png|jpe?g|webp)$/i.test(f)); // 画像ファイルをフィルタリング

for (const imagePath of imageFiles) {
try {
// 既に.thumbhash.jsonが存在する場合はスキップ（重複生成防止）
if (fs.existsSync(${imagePath}.thumbhash.json)) {
// console.log(⏩ ${imagePath}.thumbhash.json は既に存在します。スキップします。);
continue;
}

code
Code



const { data, info } = await sharp(imagePath)
    .resize(100, 100, { fit: "contain", background: { r: 0, g: 0, b: 0, alpha: 0 } })
    .ensureAlpha()
    .raw()
    .toBuffer({ resolveWithObject: true });

  const hash = rgbaToThumbHash(info.width, info.height, data);
  const base64Hash = Buffer.from(hash).toString("base64");

  // 生成されたハッシュを元の画像ファイル名+.thumbhash.jsonとして保存
  // 例: image.jpg -> image.jpg.thumbhash.json
  fs.writeFileSync(`${imagePath}.thumbhash.json`, JSON.stringify({ thumbhash: base64Hash }));
  console.log(`✅ ThumbHash生成: ${imagePath}`);
  processedCount++;

} catch (error) {
  console.error(`🔴 ${imagePath} のThumbHash生成中にエラーが発生しました:`, error);
}

}
console.log(✨ ${processedCount} 個の新しいThumbHashが生成されました！);
}

// 実行
processPubliiImages(publiiOutputMediaPath);

このスクリプトをgenerate-thumbhash.jsとして保存し、Node.jsで実行します。

node generate-thumbhash.js

スクリプトは、指定されたPubliiのメディア出力ディレクトリ（例：./output/media）を再帰的に走査し、JPEG、PNG、WebP形式の画像ファイルを見つけます。それぞれの画像に対してThumbHashを生成し、元のファイル名に.thumbhash.jsonという拡張子を付けたJSONファイルとして、同じディレクトリに保存します。このJSONファイルには、Base64エンコードされたThumbHash文字列が格納されます。

このようにして生成された.thumbhash.jsonファイルは、後ほどPubliiのテンプレート（.hbs）から読み込み、HTMLのdata-thumbhash属性に埋め込むことになります。これにより、画像がロードされる前に、軽量なThumbHashプレースホルダーが表示される仕組みが完成します。

コラム：データ形式の選択と拡張性

なぜJSONファイルとして保存するのか、疑問に思う方もいるかもしれません。ThumbHash自体はBase64文字列なので、直接HTMLに書き込んでも良いのでは？と。

これは「拡張性」と「分離性」を考慮した選択です。画像をアップロードする際にThumbHashを自動生成する仕組みを考える場合、画像ファイルそのものを変更するよりも、関連するメタデータを別のファイルとして保存する方が安全で、Publiiのファイル管理システムとも干渉しにくいです。また、将来的にThumbHashだけでなく、他の画像メタデータ（例えば色情報、サイズ、AIによるタグ付けなど）を追加したくなった場合も、JSONファイル形式であれば容易に拡張できます。データは独立している方が、システム全体の柔軟性が高まるのです。

---

Publiiテーマへの組み込み：HTMLとJavaScriptの連携

ThumbHashの生成スクリプトは準備できましたね！ 次のステップは、生成されたThumbHash値をPubliiのテーマに組み込み、実際にプレースホルダーとして表示させることです。これには、PubliiのHBS（Handlebars）テンプレートの修正と、クライアントサイドJavaScriptの記述が必要になります。

テンプレート（.hbs）の修正：data-thumbhash属性の活用

Publiiのテーマは、Handlebarsというテンプレートエンジンで記述されています。私たちは、画像を表示するタグに対して、生成したThumbHash値をカスタムデータ属性（data-thumbhash）として追加します。これにより、クライアントサイドのJavaScriptがその値を読み取り、プレースホルダーとして利用できるようになります。

まず、Publiiのテーマディレクトリ内にある、画像を扱うテンプレートファイルを見つけます。よく使われるのは、記事の詳細ページ（post.hbs）やリストページ（index.hbs）、ギャラリーページなどです。例えば、以下のような画像表示部分を修正します。

<!-- before (例) -->
<img src="{{imageUrl}}" alt="{{imageAlt}}" loading="lazy">





class="thumbhash-image">

ここで問題となるのが、{{thumbhashValue}}の部分をどうやってPubliiのテンプレートで取得するか、です。Publiiはデフォルトで.thumbhash.jsonファイルを読み込む機能を持っていません。そこで、以下のいずれかの方法を検討します。

1. Publiiのカスタムフィールドを活用：
   記事ごとに手動でThumbHash値をカスタムフィールドとして入力する方法です。簡単ですが、手間がかかります。
2. Publiiテーマのヘルパーを自作（上級者向け）：
   Publiiテーマのfunctions.php（テーマがPHPベースの場合）や、Node.jsでPubliiのビルドプロセスをラップするスクリプトの中で、ThumbHashを読み込むヘルパー関数を実装する方法です。
3. ビルド後スクリプトでHTMLを直接修正（最も確実）：
   Publiiのビルドが完了した後、output/ディレクトリ内のHTMLファイルをNode.jsスクリプトでパースし、タグにdata-thumbhash属性を追加する方法です。これは少し力技ですが、Publii本体に手を加える必要がないため、最も実装が確実で、Publiiのアップデートにも強いです。本書ではこの方法を推奨します。

ビルド後スクリプトでHTMLを直接修正する例 (追加)

前述のgenerate-thumbhash.jsに続けて、HTMLファイルをパースしてdata-thumbhashを埋め込むロジックを追加します。このためには、HTMLパースライブラリ（例：cheerio）をインストールします。

npm install cheerio

generate-thumbhash.jsに以下の部分を追加します。

// generate-thumbhash.js (抜粋、上記スクリプトに追記)


import fs from "fs";
import path from "path";
import sharp from "sharp";
import { rgbaToThumbHash } from "thumbhash";
import cheerio from "cheerio"; // ★追加

// Publiiの出力ディレクトリ（例: output/media）を指定
const publiiOutputMediaPath = "./output/media";
const publiiOutputRootPath = "./output"; // HTMLファイルもスキャンするためルートパスも指定

// ... (processPubliiImages関数は省略) ...

async function embedThumbHashesInHtml(htmlRootPath) {
console.log(🔄 ${htmlRootPath} 内のHTMLファイルをスキャンし、ThumbHashを埋め込みます...);
let processedHtmlCount = 0;

const walkHtml = (currentDir) => {
return fs.readdirSync(currentDir, { withFileTypes: true }).flatMap(entry => {
const fullPath = path.join(currentDir, entry.name);
if (entry.isDirectory()) {
return walkHtml(fullPath);
} else if (entry.isFile() && /.html$/i.test(entry.name)) {
return fullPath;
} else {
return [];
}
});
};

const htmlFiles = walkHtml(htmlRootPath);

for (const htmlPath of htmlFiles) {
try {
const htmlContent = fs.readFileSync(htmlPath, "utf8");
const $ = cheerio.load(htmlContent);
let changed = false;

code
Code



// タグを検索
  $('img[src]').each((i, el) => {
    const $img = $(el);
    const imgSrc = $img.attr('src');
    // 絶対パスまたは相対パスに対応
    const absoluteImgSrc = path.resolve(path.dirname(htmlPath), imgSrc).replace(/\\/g, '/'); // Windows対応

    // Publiiの出力パスからmedia以下の相対パスを構築
    const relativeToMedia = path.relative(publiiOutputRootPath, absoluteImgSrc);
    const thumbhashJsonPath = `${publiiOutputRootPath}/${relativeToMedia}.thumbhash.json`;

    if (fs.existsSync(thumbhashJsonPath)) {
      const thumbhashData = JSON.parse(fs.readFileSync(thumbhashJsonPath, "utf8"));
      if (thumbhashData.thumbhash && !$img.attr('data-thumbhash')) { // 既に属性がある場合はスキップ
        $img.attr('data-thumbhash', thumbhashData.thumbhash);
        $img.addClass('thumbhash-image'); // クライアントサイドJSで利用するクラスを追加
        changed = true;
        // console.log(`  🔗 ${imgSrc} にThumbHashを埋め込みました。`);
      }
    }
  });

  if (changed) {
    fs.writeFileSync(htmlPath, $.html());
    processedHtmlCount++;
    // console.log(`✅ HTML修正: ${htmlPath}`);
  }

} catch (error) {
  console.error(`🔴 ${htmlPath} のHTML修正中にエラーが発生しました:`, error);
}

}
console.log(✨ ${processedHtmlCount} 個のHTMLファイルにThumbHashが埋め込まれました！);
}

// 実行（generate-thumbhash.jsの最後に追記）
async function main() {
await processPubliiImages(publiiOutputMediaPath); // 画像のThumbHash生成
await embedThumbHashesInHtml(publiiOutputRootPath); // HTMLへの埋め込み
}
main();

このスクリプトは、output/ディレクトリ内のすべてのHTMLファイルを走査し、タグのsrc属性を基に、対応する.thumbhash.jsonファイルを探します。もし見つかれば、その内容をdata-thumbhash属性としてタグに追加します。また、クライアントサイドJavaScriptで選択しやすくするために、thumbhash-imageクラスも追加しています。

クライアントサイドでのデコードと表示 🚀

HTMLにdata-thumbhash属性が埋め込まれたら、次はブラウザ側でその値を利用してプレースホルダーを表示するJavaScriptコードを作成します。このコードはPubliiテーマの適切な場所（例：partials/footer.hbsやtheme.hbsの<body>タグの閉じ際）に配置します。

まず、ThumbHashのデコードライブラリをCDN経由で読み込むか、Publiiテーマのassets/jsに配置します。npmでインストールしたthumbhashパッケージには、ブラウザで利用可能なESモジュール版も含まれています。

Publiiテーマにスクリプトを配置する方法

1. **ThumbHashライブラリの配置**: npmでインストールしたthumbhashパッケージから、必要なファイルをPubliiテーマのassets/js/ディレクトリにコピーします。通常、node_modules/thumbhash/dist/以下にあるthumbhash.min.jsやESモジュール版を利用します。 例: themes/your-theme/assets/js/thumbhash.min.js
2. **カスタムJavaScriptの作成**: テーマのassets/js/内にthumbhash-loader.jsのようなファイルを作成します。 例: themes/your-theme/assets/js/thumbhash-loader.js
3. **テーマテンプレート（例: post.hbs, index.hbs, theme.hbs）に読み込みタグを追加**: <head>内または<body>の閉じタグの直前に追加します。defer属性をつけることで、HTMLのパースをブロックせず、読み込みを高速化します。

<!-- Publiiテーマファイル (例: theme.hbs) の <body> 閉じタグの直前に配置 -->

<!-- ThumbHashデコードライブラリの読み込み -->
<!-- CDNを使う場合 (推奨、バージョン管理に注意) -->
<script src="https://unpkg.com/thumbhash@0.1.0/dist/thumbhash.min.js" defer></script>
<!-- またはテーマ内のJSファイルとして配置する場合 -->
<!-- <script src="{{@blog.url}}/assets/js/thumbhash.min.js" defer></script> -->

<!-- カスタムThumbHashローダースクリプト -->
<script>
document.addEventListener('DOMContentLoaded', () => {
// ThumbHashライブラリがロードされるのを待つ
// unpkgなどから読み込む場合、window.thumbHashToDataURL がグローバルに定義される
const waitForThumbHash = setInterval(() => {
if (typeof window.thumbHashToDataURL === 'function') {
clearInterval(waitForThumbHash);

document.querySelectorAll('img.thumbhash-image[data-thumbhash]').forEach(img => {
const hashBase64 = img.dataset.thumbhash;
if (!hashBase64) return;

try {
// Base64からUint8Arrayにデコード
const hash = Uint8Array.from(atob(hashBase64), c => c.charCodeAt(0));
// ThumbHashからデータURL（背景画像）を生成
const dataUrl = window.thumbHashToDataURL(hash);

// CSSのbackground-imageとしてプレースホルダーを設定
img.style.background = `url(${dataUrl}) center/cover no-repeat`;
// CSSで、画像のロードが完了するまでこの背景を表示し、完了したら画像をフェードインさせる
img.style.transition = 'opacity 0.5s ease-in-out';
img.style.opacity = '0'; // 最初は透明にして背景だけ表示

img.onload = () => {
img.style.opacity = '1'; // 画像がロードされたらフェードイン
// オプション: 背景画像を削除してリソースを解放
// setTimeout(() => { img.style.background = 'none'; }, 500);
};
// エラー時もフェードイン
img.onerror = () => {
img.style.opacity = '1';
};

} catch (e) {
console.error("ThumbHashデコードエラー:", e);
// エラー発生時はプレースホルダーを表示せず、直接画像をロード
img.style.opacity = '1';
}
});
}
}, 50); // 50msごとにチェック
});
</script>

解説：

• document.querySelectorAll('img.thumbhash-image[data-thumbhash]')：thumbhash-imageクラスとdata-thumbhash属性を持つすべてのタグを選択します。
• atob(hashBase64)：Base64文字列をバイナリ文字列にデコードします。
• Uint8Array.from(...)：バイナリ文字列をUint8Array（符号なし8ビット整数配列）に変換します。ThumbHashライブラリはUint8Array形式のハッシュデータを期待します。
• window.thumbHashToDataURL(hash)：ThumbHashライブラリの関数を呼び出し、生成されたハッシュデータから、SVG形式のデータURLを生成します。このデータURLは、CSSのbackground-imageプロパティに直接指定できます。
• img.style.background = ...：生成されたデータURLを、タグの背景画像として設定します。これにより、画像本体がまだ読み込まれていなくても、ぼやけたプレースホルダーが表示されます。center/cover no-repeatで背景画像が適切に配置されるように調整しています。
• img.onloadとimg.onerror：画像本体の読み込みが完了したら（またはエラーが発生したら）、opacityを1に戻して、画像がフェードインするようにCSSトランジションと組み合わせています。これにより、プレースホルダーから本物の画像への切り替わりが非常にスムーズになります。
• defer属性：スクリプトがHTMLの解析をブロックせずに、バックグラウンドで読み込まれ、DOMツリーが構築された後に実行されることを保証します。これにより、初期描画速度が向上します。

このクライアントサイドJavaScriptにより、Publiiサイトにアクセスしたユーザーは、真っ白な空白やレイアウトシフトに悩まされることなく、コンテンツが瞬時に表示されたかのようなスムーズな体験を得られるでしょう。

コラム：CSSとJSの協奏曲

このプレースホルダーの実装は、JavaScriptとCSSの美しい協奏曲のようだと私は感じます。JavaScriptが舞台裏でハッシュをデコードし、CSSがその成果を優雅に表現する。互いの得意分野を最大限に活かすことで、ユーザーにとって最高の体験が生まれるのです。特に、transitionプロパティを使ったフェードイン効果は、技術的な最適化だけでなく、視覚的な楽しさも提供してくれます。

Web開発において、フロントエンドとバックエンド、あるいは異なる技術間の連携は常に重要です。このThumbHashの実装を通じて、そうした連携の妙を体感していただければ幸いです。

---

高度な実装と自動化：開発者のためのレシピ

ThumbHashの基本的な生成とテーマへの組み込みは理解できましたね。しかし、手動での実行では手間がかかります。ここでは、さらに一歩進んで、ThumbHashの生成と埋め込みを自動化するための高度なテクニックを紹介します。これにより、開発者はコンテンツ作成に集中できるようになります。

Publii画像アップロード時のThumbHash自動生成（chokidar活用）

Publiiの管理画面で画像をアップロードした際、自動的にThumbHashを生成できれば、最も手間がかかりません。しかし、Publii本体にはこのようなフック（特定のイベント発生時に処理を挿入する仕組み）が提供されていません。

そこで、「ファイルシステム監視」という手法を利用します。Node.jsのchokidarライブラリを使えば、Publiiのメディアファイルが保存されるディレクトリを監視し、新しい画像が追加された瞬間にThumbHash生成スクリプトを自動実行できます。

必要なライブラリのインストール

npm install chokidar

chokidarを使った自動生成スクリプト

// watch-publii-media.js
import fs from "fs";
import path from "path";
import chokidar from "chokidar";
import sharp from "sharp";
import { rgbaToThumbHash } from "thumbhash";


// Publiiのメディア入力ディレクトリ（例: PubliiのAppData/Roaming/Publii/sites/your-site-id/input/media）
// あなたの環境に合わせてパスを調整してください
const publiiInputMediaPath = "/path/to/Publii/sites/your-site-id/input/media";

console.log(👀 ${publiiInputMediaPath} を監視中... 新しい画像が追加されるとThumbHashを自動生成します。);

chokidar.watch(publiiInputMediaPath, {
ignoreInitial: true, // 起動時の既存ファイルは無視
awaitWriteFinish: { // ファイルの書き込みが完了するまで待機
stabilityThreshold: 2000, // 2秒間変更がなければ完了とみなす
pollInterval: 100 // 100msごとにポーリング
}
}).on("add", async (filePath) => {
// 画像ファイルのみを対象
if (!/.(png|jpe?g|webp)$/i.test(filePath)) {
console.log(ℹ️ ${path.basename(filePath)} は画像ファイルではありません。スキップします。);
return;
}

// 既にThumbHashファイルが存在する場合はスキップ
if (fs.existsSync(${filePath}.thumbhash.json)) {
console.log(⏩ ${filePath}.thumbhash.json は既に存在します。スキップします。);
return;
}

console.log(✨ 新しい画像が検出されました: ${filePath});
try {
const { data, info } = await sharp(filePath)
.resize(100, 100, { fit: "contain", background: { r: 0, g: 0, b: 0, alpha: 0 } })
.ensureAlpha()
.raw()
.toBuffer({ resolveWithObject: true });

code
Code



const hash = rgbaToThumbHash(info.width, info.height, data);
const base64Hash = Buffer.from(hash).toString("base64");

// ThumbHashをJSONファイルとして保存
fs.writeFileSync(`${filePath}.thumbhash.json`, JSON.stringify({ thumbhash: base64Hash }));
console.log(`✅ ${filePath} のThumbHashを自動生成しました: ${base64Hash}`);

} catch (error) {
console.error(🔴 ${filePath} のThumbHash自動生成中にエラーが発生しました:, error);
}
});

このスクリプトをバックグラウンドで常に実行しておくことで、Publii管理画面から画像をアップロードするたびに、対応する.thumbhash.jsonファイルが自動的に生成されます。 注意点としては、publiiInputMediaPathを自身のPubliiサイトの正確なinput/mediaディレクトリのパスに設定する必要があることです。OSやPubliiのバージョンによって場所が異なる場合があります。

ビルドプロセスへの統合：CI/CDとThumbHash

静的サイトは、GitHub Pages、Netlify、VercelなどのモダンなCI/CDサービスと非常に相性が良いです。これらを活用している場合、ThumbHashの生成をビルドプロセスに組み込むことで、完全に自動化されたデプロイメントパイプラインを構築できます。

例えば、GitHub ActionsやNetlifyのビルドスクリプトに、前述のgenerate-thumbhash.js（画像生成とHTML埋め込みの両方を含むもの）を実行するステップを追加するだけです。

# .github/workflows/deploy.yml (GitHub Actionsの例)
name: Deploy Publii Site with ThumbHash


on:
push:
branches:
- main

jobs:
build_and_deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v3

code
Code



# Publiiのセットアップ (PubliiをCLIで実行するための設定)
# ここはPubliiのデプロイ方法に依存します。Publii CLIツールがある場合や、手動でファイルをアップロードする場合など。
# 例として、Publiiの出力ディレクトリが `output` と仮定します。
- name: Install Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18'

- name: Install dependencies for ThumbHash generation
  run: npm install sharp thumbhash cheerio # generate-thumbhash.jsで使うライブラリをインストール
  working-directory: ./your-thumbhash-script-dir # スクリプトがあるディレクトリを指定

- name: Run Publii Build (simulated for example)
  # ここにPubliiのビルドコマンドを記述します。
  # 例: publii build --site-id your-site-id --output-dir ./output
  # あるいは、ローカルでビルドされた output ディレクトリをそのまま使う場合
  run: |
    echo "Simulating Publii build into ./output directory..."
    mkdir -p ./output/media/posts/image-assets
    echo '<img src="/media/posts/image-assets/my-post-image.jpg" alt="Test Image">' > ./output/index.html
    # ダミー画像を作成
    dd if=/dev/urandom of=./output/media/posts/image-assets/my-post-image.jpg bs=1M count=1

- name: Generate and Embed ThumbHashes
  run: node generate-thumbhash.js # スクリプトを実行
  working-directory: ./your-thumbhash-script-dir # スクリプトがあるディレクトリを指定

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./output # Publiiの出力ディレクトリを指定

これにより、mainブランチにプッシュするたびに、Publiiのビルド、ThumbHashの生成とHTMLへの埋め込み、そしてWebサイトへのデプロイがすべて自動的に行われるようになります。これは、チーム開発や大規模サイト運営において、非常に強力なワークフローとなるでしょう。

詳細：CI/CDパイプラインの構成例

実際のCI/CDパイプラインでは、以下のステップが考えられます。

1. ソースコードのチェックアウト：Gitリポジトリから最新のコードを取得します。
2. Node.js環境のセットアップ：ThumbHash生成に必要なNode.jsをインストールします。
3. 依存関係のインストール：sharp, thumbhash, cheerioなどをインストールします。
4. Publiiのビルド：Publii CLIツール（存在すれば）を使ってサイトをビルドするか、ローカルでビルドされたoutputディレクトリをアップロードします。
5. ThumbHashの生成と埋め込み：generate-thumbhash.jsスクリプトを実行し、outputディレクトリ内の画像からThumbHashを生成し、HTMLに埋め込みます。
6. デプロイ：生成された静的ファイルをGitHub Pages、Netlify、S3などのホスティングサービスにアップロードします。

これにより、開発者はコンテンツの作成にのみ集中でき、Webパフォーマンス最適化の複雑な手順から解放されます。

Publiiエディタでのプレビュー拡張

Publiiの管理画面（エディタ）で記事を執筆する際、アップロードした画像にThumbHashプレースホルダーがどのように表示されるかをプレビューできれば、よりスムーズな制作が可能になります。Publiiは、エディタのカスタマイズのためにtinymce.script.jsというファイルを利用できます。

Publiiテーマのディレクトリ内にextensions/tinymce.script.jsというパスでJavaScriptファイルを作成します。このファイル内で、TinyMCEエディタの初期化オプションをフックし、カスタムJavaScriptやCSSを挿入することで、エディタ内の画像表示を拡張できます。

// themes/your-theme/extensions/tinymce.script.js


/**

Publii TinyMCE Editor Custom Script

This script runs within the Publii post editor.

It's not directly for ThumbHash generation, but for extending editor UI.
*/
document.addEventListener('DOMContentLoaded', function() {
// TinyMCEがロードされるのを待つ
if (typeof tinymce !== 'undefined') {
tinymce.init({
selector: 'textarea#postContent', // Publiiのエディタのセレクタ
setup: function (editor) {
editor.on('init', function () {
console.log('Publii TinyMCE Editor Initialized. Now extending for ThumbHash preview...');

code
Code



// エディタ内のimgタグにThumbHashプレビューを適用するロジックをここに記述
             // ただし、エディタ内ではサーバーサイドで生成されたThumbHashデータを直接参照できないため、
             // クライアントサイドでの生成ロジックが必要になるか、簡易的なプレースホルダー表示に留まる可能性が高いです。
             
             // 例: 特定のクラスを持つimgタグにダミーの背景色を設定
             editor.dom.addStyle('img.thumbhash-editor-preview { background-color: #eee; border: 1px dashed #ccc; }');

             // エディタ内のすべてのimgタグを取得し、ThumbHashのプレビュー効果を模倣
             editor.dom.select('img').forEach(function(img) {
                 // 実際には、エディタ内でアップロードされた画像からその場でThumbHashを生成する必要があるため、
                 // サーバーサイドでの処理が必要。ここでは簡易的な表示に留める。
                 img.classList.add('thumbhash-editor-preview'); 
                 img.setAttribute('alt', img.getAttribute('alt') + ' (ThumbHash preview active)');
             });
         });

         editor.on('NodeChange', function(e) {
             // エディタの内容が変更されたときに、新しく追加された画像にも適用
             if (e.element.nodeName === 'IMG' && !e.element.classList.contains('thumbhash-editor-preview')) {
                 e.element.classList.add('thumbhash-editor-preview');
             }
         });
     }
 });

}
});

注意点： Publiiエディタ内でのThumbHashプレビューは、サーバーサイドでThumbHashが事前に生成されている必要があります。エディタ内でリアルタイムに画像を読み込み、sharpとthumbhashを使ってハッシュを生成するのは、ブラウザのセキュリティ制約やパフォーマンスの観点から困難です。現実的には、以下のいずれかのアプローチが考えられます。

• 簡易的なプレースホルダー：上記スクリプトのように、エディタ内のタグに対して、ThumbHash風のダミー背景色や「ぼかし」効果をCSSで適用する。
• カスタムフィールドと連携：カスタムフィールドで手動入力されたThumbHash値をエディタに表示させる。
• Publii本体の拡張：Publii本体のコア機能を修正して、画像をアップロードした際にバックエンドでThumbHashを生成し、エディタに返す仕組みを構築する（非常に高度）。

最も現実的なのは、Publiiで画像をアップロードした際に、前述のchokidarスクリプトがバックグラウンドでThumbHashを生成し、それをPubliiが認識できる形でメタデータとして保存し、エディタがそのメタデータを読み込んで表示する、という連携になります。ただし、Publiiがどのようにカスタム画像メタデータを扱うかによって、実装の複雑さが変わります。

コラム：理想のエディタ体験

コンテンツクリエイターにとって、エディタの体験は非常に重要です。プレビューと最終的な表示が一致していることは、ストレスなく執筆を進める上で不可欠ですよね。ThumbHashのようなパフォーマンス最適化技術も、できればエディタの時点でその効果を実感できるのが理想です。

しかし、ブラウザのサンドボックスやセキュリティモデルの制約、そして既存CMSのアーキテクチャは、常に開発者の前に立ちはだかる壁です。このエディタでのプレビュー拡張は、そうした制約の中でいかに「理想に近づけるか」という挑戦を象徴しているように思います。完璧でなくても、ちょっとした工夫でユーザーの満足度を高めることはできる。私はそう信じています。

---

オリジナルプラグイン開発：ThumbHash Generatorの構築

これまでの知識を統合し、PubliiのビルドプロセスにThumbHash生成を自動的に組み込むためのオリジナルプラグインを作成しましょう。PubliiはafterBuildというイベントフックを提供しており、ビルド完了後に特定のスクリプトを実行できます。

プラグインの基本構造とafterBuildフック

Publiiプラグインは、基本的に以下のファイルで構成されます。

• plugin.json: プラグインのメタデータ（名前、説明、バージョンなど）を定義します。
• main.js: プラグインのコアロジックを記述します。ここでafterBuildフックを実装します。

Publiiのテーマディレクトリのpluginsフォルダ内に、新しいフォルダ（例: thumbhash-generator）を作成し、その中にこれらのファイルを配置します。

1. plugin.json

プラグインの情報を記述します。

// themes/your-theme/plugins/thumbhash-generator/plugin.json
{
"name": "ThumbHash Generator",
"description": "Automatically generates ThumbHash placeholders for images after Publii build.",
"version": "1.1.0",
"author": "Dr. Gemini",
"main": "main.js"
}

2. main.js

ThumbHash生成とHTML埋め込みのロジックをexports.afterBuild関数内に記述します。この関数は、Publiiのビルドが完了した後に自動的に呼び出されます。

// themes/your-theme/plugins/thumbhash-generator/main.js
const fs = require("fs");
const path = require("path");
const sharp = require("sharp"); // npm install sharp が必要
const { rgbaToThumbHash } = require("thumbhash"); // npm install thumbhash が必要
const cheerio = require("cheerio"); // npm install cheerio が必要


// afterBuildフック
exports.afterBuild = async (config, outputPath) => {
console.log("\n🧩 ThumbHash Generator: ビルド後の画像処理を開始します...");

const mediaPath = path.join(outputPath, 'media'); // Publiiのメディア出力パス

// --- 1. 画像からThumbHashを生成し、JSONファイルとして保存 ---
const generateImageThumbHashes = async (currentDir) => {
let count = 0;
const files = fs.readdirSync(currentDir, { withFileTypes: true });

code
Code



for (const entry of files) {
  const fullPath = path.join(currentDir, entry.name);
  if (entry.isDirectory()) {
    count += await generateImageThumbHashes(fullPath); // 再帰的にサブディレクトリを処理
  } else if (entry.isFile() && /\.(png|jpe?g|webp)$/i.test(entry.name)) {
    // 既にThumbHashファイルが存在する場合はスキップ
    if (fs.existsSync(`${fullPath}.thumbhash.json`)) {
      // console.log(`⏩ ${entry.name}.thumbhash.json は既に存在します。スキップします。`);
      continue;
    }

    try {
      const { data, info } = await sharp(fullPath)
        .resize(100, 100, { fit: "contain", background: { r: 0, g: 0, b: 0, alpha: 0 } })
        .ensureAlpha()
        .raw()
        .toBuffer({ resolveWithObject: true });

      const hash = rgbaToThumbHash(info.width, info.height, data);
      const base64Hash = Buffer.from(hash).toString("base64");
      fs.writeFileSync(`${fullPath}.thumbhash.json`, JSON.stringify({ thumbhash: base64Hash }));
      console.log(`  ✅ ThumbHash生成: ${path.relative(outputPath, fullPath)}`);
      count++;
    } catch (error) {
      console.error(`  🔴 ThumbHash生成エラー (${path.relative(outputPath, fullPath)}):`, error.message);
    }
  }
}
return count;

};

const generatedCount = await generateImageThumbHashes(mediaPath);
console.log(✨ ThumbHash生成完了: ${generatedCount} 個の新しいThumbHashが作成されました。\n);

// --- 2. HTMLファイル内のタグにThumbHashを埋め込む ---
console.log("🧩 HTMLファイルへのThumbHash埋め込みを開始します...");
let embeddedCount = 0;

const embedThumbHashesInHtmlFiles = async (currentDir) => {
const files = fs.readdirSync(currentDir, { withFileTypes: true });

code
Code



for (const entry of files) {
  const fullPath = path.join(currentDir, entry.name);
  if (entry.isDirectory()) {
    await embedThumbHashesInHtmlFiles(fullPath); // 再帰的にサブディレクトリを処理
  } else if (entry.isFile() && /\.html$/i.test(entry.name)) {
    try {
      const htmlContent = fs.readFileSync(fullPath, "utf8");
      const $ = cheerio.load(htmlContent);
      let changed = false;

      $('img[src]').each((i, el) => {
        const $img = $(el);
        const imgSrc = $img.attr('src');
        
        // Publiiのimg srcはサイトルートからの相対パスなので、outputPathと結合して実際のファイルパスを構築
        // 例: /media/posts/image.jpg -> output/media/posts/image.jpg
        let absoluteImgPath;
        if (imgSrc.startsWith('/')) {
            absoluteImgPath = path.join(outputPath, imgSrc);
        } else {
            // 相対パスの場合 (例: 同じディレクトリ内の画像)
            absoluteImgPath = path.resolve(path.dirname(fullPath), imgSrc);
        }
        
        const thumbhashJsonPath = `${absoluteImgPath}.thumbhash.json`;
        
        if (fs.existsSync(thumbhashJsonPath)) {
          const thumbhashData = JSON.parse(fs.readFileSync(thumbhashJsonPath, "utf8"));
          if (thumbhashData.thumbhash && !$img.attr('data-thumbhash')) { // 既に属性がある場合はスキップ
            $img.attr('data-thumbhash', thumbhashData.thumbhash);
            $img.addClass('thumbhash-image'); // クライアントサイドJSで利用するクラスを追加
            changed = true;
          }
        }
      });

      if (changed) {
        fs.writeFileSync(fullPath, $.html());
        embeddedCount++;
        console.log(`  ✅ HTML埋め込み修正: ${path.relative(outputPath, fullPath)}`);
      }

    } catch (error) {
      console.error(`  🔴 HTML埋め込みエラー (${path.relative(outputPath, fullPath)}):`, error.message);
    }
  }
}

};

await embedThumbHashesInHtmlFiles(outputPath); // HTMLファイルもスキャン対象
console.log(✨ ThumbHash埋め込み完了: ${embeddedCount} 個のHTMLファイルが修正されました。);
console.log("🧩 ThumbHash Generator: 処理を終了します。\n");
};

注意点： プラグインとしてsharp, thumbhash, cheerioを利用する場合、これらのライブラリはPubliiが動作する環境にインストールされている必要があります。Publiiのプラグインシステムは、Node.jsのモジュール解決メカニズムを利用するため、通常はPubliiアプリケーションのnode_modules、またはプラグイン自体のnode_modulesにこれらのライブラリを配置する必要があります。一番簡単な方法は、Publiiのアプリケーションルートディレクトリでnpm install sharp thumbhash cheerioを実行することです。

ZIPアーカイブ化と配布 🎁

作成したプラグインは、Publiiの管理画面から簡単にインストールできるよう、ZIPファイルとしてアーカイブできます。以下のNode.jsスクリプトを使用すると、プラグインディレクトリをZIP形式に自動で圧縮できます。

必要なライブラリのインストール

npm install archiver

ZIP生成スクリプト

// create-thumbhash-plugin-zip.js
import fs from "fs";
import path from "path";
import archiver from "archiver";


const pluginDirName = "thumbhash-generator"; // プラグインディレクトリ名
const outputZipFileName = ${pluginDirName}.zip;

const output = fs.createWriteStream(outputZipFileName);
const archive = archiver("zip", {
zlib: { level: 9 } // 最高の圧縮レベル
});

output.on("close", () => {
console.log(📦 ${outputZipFileName} が正常に作成されました。サイズ: ${archive.pointer()} バイト);
console.log(Publii管理画面の「Plugins」セクションから、このZIPファイルをインストールできます。);
});

archive.on("warning", (err) => {
if (err.code === "ENOENT") {
console.warn("⚠️ Archiver警告:", err.message);
} else {
throw err;
}
});

archive.on("error", (err) => {
console.error("🔴 Archiverエラー:", err);
throw err;
});

// pluginDirNameディレクトリの内容を、ZIPファイルのルートに含める
archive.pipe(output);
archive.directory(pluginDirName, pluginDirName); // ZIP内のパスも thumbhash-generator になる
archive.finalize();

このスクリプトを実行すると、thumbhash-generator.zipファイルが生成されます。このZIPファイルをPublii管理画面の「Plugins」セクションから「Install new plugin」でアップロードすれば、プラグインとしてPubliiに認識され、サイトのビルド時に自動的にThumbHashが生成・埋め込まれるようになります。

これにより、ThumbHashの実装は完全にPubliiのワークフローに統合され、開発者はパフォーマンス最適化の手間から解放されます。まさに、一度設定すればあとはお任せ、という状態を作り出せるのです！

コラム：OSSとしての貢献

このようなプラグインを開発し、ZIPとして配布できることは、Publiiコミュニティへの大きな貢献にも繋がります。もしあなたが作成したプラグインが多くの人に役立つと感じたら、ぜひオープンソースとして公開してみてください。他の開発者からのフィードバックや改善提案は、プラグインをさらに良くし、ひいてはWeb全体のパフォーマンス向上に貢献することになるでしょう。

私のようなAIも、コミュニティの知識を学習することで日々賢くなっていきます。人間の開発者も、お互いの知識やツールを共有し、協力し合うことで、より良いWebの世界を築いていけるはずです。