Open Graph 画像

すべてのページ向けに生成される 1200×630 のソーシャルカード — ブランディング、カードのレイヤー、非ラテン文字向けフォント、ページ単位のオーバーライドについて。

Blume は、すべてのページに対してビルド時に 1200×630 のソーシャルカードをレンダリングできます。Takumi のおかげでヘッドレスブラウザは不要で、ビルドは高速なままです。deployment.site が設定されているか自動検出された場合はデフォルトで有効になり（og:image の URL はクローラーにとって有用であるために絶対 URL である必要があります）、そうでない場合やデフォルト画像がカードを置き換える場合は無効です。どちらの挙動も enabled で上書きできます:

seo: {
  og: { enabled: true }, // or false to opt out even with a site set
}

デフォルト画像

生成されるカードの代わりにすべてのページで 1 つの画像を共有するには、seo.og.image を設定します。ロケールごとに個別の画像を指定することもできます:

seo: {
  og: {
    image: { en: "/og/default-en.png", fr: "/og/default-fr.png" },
    // Or image: "https://example.com/og/default.png"
  },
}

ページの seo.image やカスタムページの ogImage プロパティは、デフォルトよりも優先されます。マップに含まれないロケールには、デフォルトロケールの画像が使われます。デフォルト画像は PageLayout でレンダリングされるカスタムページや、生成される変更履歴のインデックスにも適用されるため、これを設定すると、enabled が true でない限り Blume はカードを生成しなくなります。ルート相対パスはデプロイのベースパスの下で解決されます。Blume が画像のサイズを宣言するのは、生成されたカードに対してのみです。最終的にページで使われる画像は、ページの image としてその JSON-LD にも含まれます。

生成されるカードをブランディングする

ローカルの SVG とカラーパレットを設定して、生成されるカードをブランドに合わせましょう。ロゴは public/ またはプロジェクトルートに配置できます。パレットの値を省略すると、その項目はデフォルトのままになります。

seo: {
  og: {
    logo: "/logo/og.svg",
    palette: {
      accent: "#ff5410",
      background: "#1d1d1d",
      foreground: "#fff6f2",
      muted: "#a6a19f",
      border: "#323232",
    },
  },
}

デフォルトでは、各カードはコンテンツとテーマから導出されます。見出しにはページタイトル、サブタイトルにはページの説明（og:description と同じテキストなので、description よりも seo.description が優先されます）、マークにはテーマのアクセントが使われます。ロゴを設定していない場合、マークにはサイトタイトルの頭文字が表示されます。画像は各ルートに対応する形で /og/<slug>.png から配信され、サーバーモードでも静的ファイルとしてプリレンダリングされます:

ページのルート	画像の URL
`/`	`/og/index.png`
`/quickstart`	`/og/quickstart.png`
`/guides/deploy`	`/og/guides/deploy.png`

任意のページで生成されたカードを上書きするには、seo.image を使います。public/ 内のファイルまたは外部 URL を指定できます。これは生成されたカードよりも優先され、og が無効な場合でも機能するため、カスタム画像と生成画像を組み合わせて使えます:

---
title: Pricing
seo:
  image: /og/pricing-custom.png
---

ページタイトルやサイトタイトルに含まれる絵文字は Twemoji のグリフとしてレンダリングされ、カードのレンダリング中に CDN から取得されます。そのため、タイトルに絵文字を含むビルドにはネットワークアクセスが必要です。各グリフは、いくつのページで使われていてもビルドごとに 1 回だけ取得されます。

カードのレイヤーを表示・非表示・上書きする

見出しに加えて、カードには 3 つのオプションレイヤーがあります。左上のブランドマーク（ロゴ、またはサイトタイトルの頭文字を配したアクセントタイル）、見出しの下のサブタイトル（ページの description、それがないページではサイトの description）、そしてリポジトリスラッグ（github から取得）とサイトの URL を含むフッターです。サイトの URL はデプロイ先サイトのホストに deployment.base を加えたもので、GitHub Pages のプロジェクトサイトであれば user.github.io/repo と表示されます。いずれも任意の文字列で上書きでき、false を指定すると非表示になります:

seo: {
  og: {
    site: "docs.acme.com", // footer URL text, or false to hide it
    description: false, // hide the subtitle on every card; a string replaces the site fallback
    logo: false, // no brand mark at all — not even the initial tile
  },
}

カードのフォント

デフォルトでは、カードは Takumi の組み込みフォントでレンダリングされます。このフォントは基本的なラテン文字のグリフしかカバーしていないため、このフォントだけでは、他の文字体系（日本語、中国語、韓国語、アラビア語、ヒンディー語、ロシア語など）のタイトルは豆腐（空の四角）として表示されてしまいます。

すべての文字体系がデフォルトでカバーされます。 カードは組み込みフォントの後ろに、文字体系ごとに 1 つずつ Google の Noto ファミリーを並べたフォールバックスタックを持っています。キリル文字、ギリシャ文字、ベトナム語、アクセント付きのラテン文字には Noto Sans、続いて Noto Sans JP、Noto Sans Arabic、Noto Sans Devanagari といった具合です。ロケールが設定されていないサイトでも、日本語やヒンディー語のタイトルは何も設定せずにレンダリングされます。フォールバックはグリフ単位で行われるため、ラテン文字のテキストは組み込みフォントのままです。カードが Google Fonts から取得を行うのは、テキストに組み込みフォントで描画できないグリフが含まれる場合のみで、その場合もそれらのグリフに必要なサブセットだけを取得します。英語のカードは何も取得しないため、ラテン文字のみのサイトはオフラインでもビルドできます。このスタックは og.fonts が設定されていない限り適用されます。og.fonts を設定すると、フォントのリスト全体がその設定に置き換わります。

中国語、日本語、韓国語は漢字の大部分を共有していますが、一部の字形は異なります。カードはデフォルトで日本語の字形を使います。設定された各ロケールは対応するファミリーを先頭に移動させるため、zh ロケールを持つサイトでは漢字が簡体字の字形で描画され、zh-Hant または zh-TW では繁体字の字形で描画されます。

theme.fonts を設定すれば、カードもそれに従います。 設定で独自のフォントを指定すると、生成されるカードは見出しをディスプレイフォントで、説明とフッターをボディフォントで自動的にレンダリングするため、共有リンクがサイトと一致します。非ラテン文字のカバーも含め、ここで設定すべきことは何もありません。（Google 以外のプロバイダーのファミリーはスキップされます — カードレンダラーは Google Fonts からしか取得できません — が、ローカルのフォントファイルは利用できます。）

サイトとは異なるフォントをカードで使いたい場合は、og.fonts を明示的に設定します。この設定は常にテーマ由来のフォントより優先され、文字体系のフォールバックも置き換えるため、カードに必要なすべてのファミリーを列挙してください:

seo: {
  og: {
    fonts: [
      "Noto Sans JP",
      { name: "Inter", weight: [400, 700] },
      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
    ],
  },
}

各エントリには、Google Fonts のファミリー名、weight（数値、リスト、または "100..900" のような可変範囲）と style（"normal"、"italic"、またはその両方）を指定するオブジェクト、あるいはローカルのフォントファイルを指定できます。ローカルファイルの場合、src はプロジェクトルートから解決され、ファイル自身のメタデータに任せたくない場合は weight と style を任意で指定できます。

Google のファミリーはビルド時に取得されるため、それらを使うビルドにはネットワークアクセスが必要です。また、レンダラーは各タイトルが実際に使用するグリフのサブセットのみを取得します。フォールバックはグリフ単位で行われるため、ファミリーを追加しても、他のフォントで描画できないグリフにしか影響しません。

og.fonts: [] と明示的に指定すると完全にオプトアウトでき、theme.fonts が設定されている場合やタイトルに文字体系のフォールバックが必要な場合でも、カードは組み込みフォントのままになります。

カードのキャッシュ

レンダリングされたカードはビルド間でディスクにキャッシュされます。キャッシュのキーには、カードのピクセルを決定するすべての要素 — ページのタイトルと説明、ブランドテキスト、ロゴ、パレット、フッターのテキスト、フォント（ローカルのフォントファイルはその内容で判定）、そして Blume のバージョン — が使われます。再ビルド時には入力が変わったカードだけがレンダリングされ、残りはキャッシュから読み込まれます。再利用されたカードの数はビルドログに表示されます。キャッシュは node_modules/.cache/blume/og に保存されます。ビルド間で node_modules を保持するプラットフォーム（Vercel と Netlify は保持しますが、Cloudflare は保持しません）や、このディレクトリをキャッシュする CI ランナー（ビルドキャッシュを参照）では、少数のページだけを変更したデプロイで再レンダリングされるカードも少数で済みます。どのページからも要求されなかったカードは各ビルドの後に削除されるため、このディレクトリには常に現在のサイトのカードだけが保持されます。

カスタムページのタイトル

カスタム .astro ページには読み取るフロントマターがないため、生成されるカードのタイトルはルートの最後の URL セグメントを人間向けに整形したものになります。/getting-started は「Getting Started」になりますが、/cli は「Cli」になってしまいます。こうしたカードには og.titles でルートをキーとして明示的に名前を付けられます（"/" はホームを指し、指定しない場合そのカードにはサイトタイトルが表示されます）:

seo: {
  og: {
    titles: {
      "/cli": "CLI",
    },
  },
}

エントリはカスタムページにのみ適用されます。コンテンツページのカードは常にページタイトルから見出しを取得するため、そちらはフロントマターでタイトルを付け直してください。

seo.image はフロントマターなので、Markdown と MDX のコンテンツにしか適用されません。カスタム .astro ページに独自のソーシャル画像を設定するには — マーケティング用のホームページやランディングページ、そしてホームページだけに専用の共有画像を設定する方法として — PageLayout に ogImage プロパティを渡してください。