share-cards は何をしますか?
プレビュークローラー(チャットアプリ、SNSサイト、検索エンジン)はサーバーが送信するHTMLを読み、JavaScriptは実行しません。シングルページアプリケーションはすべてのアドレスに同じHTMLを送信するため、すべてのリンクで同じプレビューが表示されます。share-cards はこの両方の問題を解決します。
- render: 1つのHTMLテンプレート + ページリスト → 各ページごとに1枚の1200x630 JPEGを、ヘッドレスブラウザで描画します。
- inject: ビルド済みの
index.html→ 各ページごとに1つのHTMLファイルへ。それぞれに独自の<title>、description、正規URL、og:*およびtwitter:*タグを埋め込みます。
スキルフォルダ: ~/.claude/skills/share-cards/(以下 $S と表記)。すべてのコマンドは $S/cards <command> [dir] で、[dir] には cards.config.json が格納されています。$S/cards help で一覧表示されます。
$S/cards コマンドラインインターフェース
$S/lib/ 設定、タグ注入、レンダリング、検証、プレビュー、リライト
$S/templates/ editorial.html、minimal.html、technical.html、runtime.js
$S/vite-plugin.mjs `vite build` 後に inject を実行するプラグイン
$S/references/templates.md スロット、変数、および独自テンプレートの作成方法
$S/examples/site/ 4ページのサンプルサイトとそのカード、注入済みページ
$S/README.md 設定リファレンス、フレームワーク別注意点、制限事項
ワークフロー
- マシンを確認:
$S/cards check。ブラウザが必要なのはrenderとpreviewのみです。 - ページを特定する: プロジェクトのルーターまたはコンテンツフォルダを読み取り、すべての公開アドレスをリストアップします。静的ファイルが提供されている場所(
public/、static/)と、ビルドの出力先(dist/、build/、out/)を見つけます。 - スキャフォールド:
$S/cards init <project>(ページリストをプロジェクトのルートやコンテンツデータから動的に生成する必要があり、ずれが生じないようにする場合は--mjsを追加します)。siteUrl(実際のhttps://オリジン)、siteName、imageDir(静的フォルダ内、例:public/og)、imageUrlPath(そのフォルダが提供されるパス、例:/og)、distを設定します。 - 各ページのエントリを作成する:
title: プレビューに表示される完全なページタイトル。description: 一文、最大160文字。cardTitle: カードに描画される単語。短く(約2〜6単語)。*stars*で囲むとアクセントカラーで描画されます。cardDescription(オプション、カード用の短い行)、kicker(小さなラベル)、art(プロジェクト内の画像ファイル)、template(ページごとの上書き)。- 事実、数値、引用をでっち上げないでください。言葉はページ自体から取ってください。
- テンプレートとテーマを選ぶ:
editorial(紙、太いセリフ体)、minimal(白、控えめ)、technical(ダーク、等幅フォント)。themeはプロジェクト自身の色に設定します。それ以外の場合は$S/cards eject <name> card.htmlを実行し、編集して"template": "./card.html"を設定します。references/templates.mdを参照してください。 - レンダリング:
$S/cards render <project>。すべての警告を読んでください:タイトルや説明が切れている場合は、テキストを短くする必要があります。 - 結果を確認する:
$S/cards preview <project>でcards-preview/contact-sheet.pngとchat-preview.pngが書き出されます。両方のPNGを読んでください。各カードで、文字の切れ、混雑、コントラストの弱さ、テキストを隠すアートワークがないか確認します。修正して再レンダリングします。自分で確認しない限り、カードが正しいとユーザーに伝えないでください。 - ページシェルを準備する:
injectは既存のタグを埋め、タグがない場合は失敗します。$S/cards tags <project>を実行し、ブロックをソースindex.htmlの<head>に貼り付け、古い共有タグと置き換えます(または--add-missingを渡します)。 - ビルドに組み込む:
- Vite:
$S/vite-plugin.mjsからshareCards()をpluginsに追加します(README参照)。 - それ以外: ビルドコマンドの後に
$S/cards inject <project>を実行します。
- Vite:
- ホストのルール: ホストが
/index.htmlへのキャッチオールリライトを持っている場合、$S/cards rewrites vercel|netlify|netlify-toml <project>でページルールを出力し、それらを キャッチオールの前に 配置します。ルールをユーザーに表示します。明示せずにホスト設定を編集しないでください。 - 検証: サイトをビルドし、
$S/cards verify <project>を実行します。All good.で終了する必要があります。 - ユーザーに残っている作業を伝える: デプロイし、実際のリンクを1つチャットアプリに貼り付けます。プレビューは各アプリによってキャッシュされ、場合によっては数日間保持されます。
"versionImages": trueを設定すると、カードが変更されるたびに画像アドレスが変わります。
ルール
siteUrlはプロダクションオリジンである必要があります。プレビュー画像には絶対的なhttps://アドレスが必要です。- カードはビルドの前にレンダリングし、ビルドがそれらをコピーするようにし、カードと
cards.lock.jsonをコミットします。これによりCIではブラウザが不要になります。 - 設定で
"allowNetwork": trueが設定されていない限り、レンダリング中にネットワークから何も取得されません。Webフォントはfontsの下にリストされたローカルファイルである必要があります。 - フォントはデフォルトでシステムスタックにフォールバックするため、別のマシンで描画されたカードは異なる場合があります。どこでも同一の出力を得るには、フォントファイルをプロジェクトに追加し(ライセンスを確認)、
fontsの下にリストします。 - 確認されなかったことを明確に伝えます: 各アプリの実際のクローラー、およびデプロイ後のホストのルーティング。