#author("2026-03-13T02:38:19+09:00","default:kanateko","kanateko")
#author("2026-03-13T18:58:00+09:00","default:kanateko","kanateko")
&tag(プラグイン,自作,追加);

#ref(linkcard.webp,center,wrap,560x)

#contentsx

* 外部リンクカード表示プラグイン [#summary]

#infobox(plugin,except=ライセンス){{
#infobox(plugin){{
name = linkcard
ver = 1.2.4
pukiwiki = 1.5.4
update = 2026-03-13
}}

外部リンクからOGP（Open Graph Protocol）情報を非同期で取得し、リッチなリンクカードとして表示するプラグイン。ブログやニュースサイトのような洗練された外部リンク表示を手軽に実現できる。

* プラグインの特徴 [#features]
- 🔗 ''OGP非同期取得''：URLを指定するだけでタイトル・説明文・画像を自動取得
- ⚡ ''高速なページロード''：スケルトンUI（Shimmerアニメーション）を採用。非同期ロードによりページ本体の読み込みを妨げない
- 💾 ''インテリジェント・キャッシュ''：OGPデータをサーバー側に7日間保存。外部サイトへの重複リクエストを防止し、表示を高速化
- ⚙️ ''キャッシュ管理画面''：管理者パスワードによる認証付き管理画面 (`?cmd=linkcard`) で、キャッシュの統計確認、詳細情報の閲覧、個別・一括削除が可能
- 🖼 ''画像最適化''：取得した画像をWebP形式に変換・リサイズ（240x126px）。通信量を削減しつつ、カードに最適なサイズで表示
- 🌙 ''ダークモード対応''：ダークモード用スタイル実装済み
- 📱 ''レスポンシブ設計''：PCだけでなく、モバイル端末の狭い画面でも美しくレイアウトを維持
- 🛡 ''セキュリティ配慮''：CSRF保護、POSTリクエストによる取得、適切なエスケープ、および画像配信用の`.htaccess`自動生成

* 動作環境 [#requirements]
- PukiWiki 1.5.4 以降
- PHP 8.2 以降
- PHP GD拡張 (WebP対応)
- PHP cURL拡張
- モダンブラウザ（ES2022対応）

#clear

* ダウンロード [#download]
https://github.com/kanateko/pukiwiki-linkcard

|~日付|~バージョン|~備考|h
|CENTER:120|CENTER:60|590|c
|2026-03-13|1.2.4|#ul(管理画面へのダークテーマ適用,管理画面のファイル数カウントをJSONのみに修正)|
|~|1.2.3|#ul(OGP取得時のUser-Agentフォールバック実装)|
|2026-03-12|1.2.2|#ul(セッションロックの早期解放による並列処理の改善,一部サイトでのUser-Agent制限による取得エラーの修正)|
|~|1.2.1|#ul(キャッシュ管理画面の機能拡張（詳細表示・プレビュー・個別削除）,PRGパターンの導入)|
|~|1.2.0|#ul(キャッシュ管理画面の追加,スタイル読み込みの最適化)|
|~|1.1.0|#ul(SSRF対策追加,cURLのリソース制限追加,キャッシュGC機能の追加,UAを一般的なブラウザに近いものに変更)|
|~|1.0.2|#ul(ワンタイムトークンによるPOST認証を追加)|
|~|1.0.1|#ul(カードホバー時のアウトラインエフェクトを調整)|
|~|1.0.0|#ul(初版作成)|

*インストール [#install]

+ GitHub の Release から最新のファイルをダウンロードする。
+ ダウンロードした「`linkcard.inc.php`」を `plugin/` ディレクトリに配置する。

* 使用方法 [#usage]

ブロック型プラグインとして、表示したいURLを引数に指定する。

 #linkcard(URL)

** 引数一覧 [#args]

|~引数名|~説明|~例|h
|150|250|150|c
|`URL`|リンク先のURL|`&nop(#linkcard(https://google.com));`|

* 使用例 [#example]

 基本構成
 #linkcard(https://example.com/)

#linkcard(https://jpngamerswiki.com/borderlands4/?マッド・エリーと忌まわしのヴォルト)
#linkcard(https://store.steampowered.com/app/440/Team_Fortress_2/)
#linkcard(https://github.com/kanateko)
#linkcard(https://pukiwiki.sourceforge.io)

`?cmd=linkcard` からキャッシュの管理画面にアクセス可能。(要管理者パスワード)

#fig(linkcard_manage.webp,center,cap=管理画面)

* 技術的メモ [#tech]

- ''非同期通信'':
-- ページ読み込み時に、各カード要素が `data-url` 属性を持って生成される。
-- クライアント側の JavaScriptがこれらの要素を検出し、PukiWiki のアクション型プラグイン (`?plugin=linkcard`) に対して POST リクエストを送信して OGP データを一括ではなく順次取得する。
- ''キャッシュサーバー'':
-- PHP 側で `CACHE_DIR/linkcard/` ディレクトリ内にデータをキャッシュ。
-- OGP 情報はブラウザに返す JSON 形式で保存。
-- 画像は GD ライブリを使用して、元のアスペクト比を維持しつつ `240x126` に中央トリミングし、WebP 形式で保存（品質 80）。
- ''スタイリング'':
-- SCSS で記述。グラスモフィズム風の背景や、ホバー時のスムーズなアウトラインアニメーションを実装。
-- セーフティとして、OGP取得失敗時や画像がない場合は、ドメイン名のみを表示するシンプルなカード構造にフォールバックする。
-- `pukiwiki.ini.php` 内やプラグイン内で `PKWK_SKIN_DARK_THEME` を `1` に設定すると、ダークテーマで表示される。
--- CSS をいじればユーザー設定に合わせたテーマの切り替えも可能 (`.plugin-linkcard--dark` を `prefers-color-scheme: dark` に書き換えるなど)

* コメント [#comment]
#mcomment