Open-Graph-Bilder

Generierte 1200×630-Social-Cards für jede Seite — Branding, Card-Ebenen, Schriften für nicht-lateinische Schriftsysteme und Overrides pro Seite.

Blume kann für jede Seite zur Build-Zeit eine 1200×630-Social-Card rendern — dank Takumi ohne Headless-Browser, sodass deine Builds schnell bleiben. Standardmäßig aktiv, sobald deployment.site gesetzt oder automatisch erkannt wurde (die og:image-URL muss absolut sein, damit Crawler etwas damit anfangen können), ansonsten deaktiviert, ebenso wenn ein Standardbild die Cards ersetzt. Mit enabled überschreibst du das in beide Richtungen:

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

Standardbild

Setze seo.og.image, um statt einer generierten Card ein einziges Bild für alle Seiten zu verwenden, oder gib jeder Locale ihr eigenes:

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

Das seo.image einer Seite oder die ogImage-Prop einer benutzerdefinierten Seite hat Vorrang vor dem Standardbild. Eine Locale, die in der Map fehlt, bekommt das Bild der Standard-Locale. Das Standardbild gilt auch für benutzerdefinierte Seiten, die mit PageLayout gerendert werden, sowie für den generierten Changelog-Index. Sobald es gesetzt ist, generiert Blume daher keine Cards mehr, es sei denn, enabled ist true. Root-relative Pfade werden unterhalb der Deployment-Base aufgelöst. Blume gibt Bildabmessungen nur für generierte Cards an. Welches Bild eine Seite am Ende auch bekommt, es landet außerdem als image der Seite in ihrem JSON-LD.

Die generierte Card branden

Setze ein lokales SVG und eine Farbpalette, damit die generierte Card zu deiner Marke passt. Das Logo kann in public/ oder im Projektstammverzeichnis liegen. Lass einen Palettenwert weg, um den Standard beizubehalten.

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

Standardmäßig wird jede Card aus deinen Inhalten und deinem Theme abgeleitet — der Seitentitel als Überschrift, die Seitenbeschreibung als Untertitel (derselbe Text wie ihre og:description, seo.description sticht also description) und dein Theme-Accent für das Zeichen, das den Anfangsbuchstaben deines Site-Titels zeigt, wenn du kein Logo gesetzt hast. Die Bilder werden unter /og/<slug>.png ausgeliefert, spiegeln also jede Route, und werden selbst im Server-Modus als statische Dateien vorgerendert:

Seitenroute	Bild-URL
`/`	`/og/index.png`
`/quickstart`	`/og/quickstart.png`
`/guides/deploy`	`/og/guides/deploy.png`

Überschreibe die generierte Card für jede beliebige Seite mit seo.image — eine Datei in public/ oder eine externe URL. Sie hat Vorrang vor der generierten Card und funktioniert auch, wenn og deaktiviert ist, sodass du eigene Bilder mit generierten mischen kannst:

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

Emojis in einem Seitentitel oder Site-Titel werden als Twemoji-Glyphen gerendert und während des Card-Renderings von einem CDN geladen — ein Build, dessen Titel Emojis enthalten, braucht also Netzwerkzugriff. Jede Glyphe wird pro Build nur einmal geladen, egal wie viele Seiten sie verwenden.

Card-Ebenen anzeigen, ausblenden oder überschreiben

Neben der Überschrift trägt die Card drei optionale Ebenen: das Markenzeichen oben links (dein Logo oder eine Accent-Kachel mit dem Anfangsbuchstaben des Site-Titels), den Untertitel unter der Überschrift (die description der Seite oder deine Site-description für Seiten ohne eigene) und eine Fußzeile mit deinem Repo-Slug (aus github) und der URL der Site — dem Host der Deployment-Site plus deployment.base, sodass bei einer GitHub-Pages-Projektsite user.github.io/repo steht. Überschreibe eine davon mit einem eigenen String oder blende sie mit false aus:

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
  },
}

Card-Schriften

Standardmäßig wird die Card in Takumis eingebauter Schrift gerendert, die nur grundlegende lateinische Glyphen abdeckt — für sich allein würde ein Titel in einem anderen Schriftsystem (Japanisch, Chinesisch, Koreanisch, Arabisch, Hindi, Russisch, …) als Tofu erscheinen, also als leere Kästchen.

Jedes Schriftsystem ist standardmäßig abgedeckt. Hinter der eingebauten Schrift tragen Cards einen Fallback-Stack aus Google-Noto-Familien, eine pro Schriftsystem: Noto Sans für Kyrillisch, Griechisch, Vietnamesisch und Latein mit Akzenten, dann Noto Sans JP, Noto Sans Arabic, Noto Sans Devanagari und so weiter. Ein Titel auf Japanisch oder Hindi wird gerendert, ohne dass du etwas konfigurieren musst, selbst auf einer Site ohne Locales. Der Fallback greift pro Glyphe, lateinischer Text behält also die eingebaute Schrift. Eine Card lädt nur dann von Google Fonts, wenn ihr Text eine Glyphe enthält, die die eingebaute Schrift nicht zeichnen kann, und dann auch nur die Subsets, die diese Glyphen brauchen: Eine englische Card lädt gar nichts, eine rein lateinische Site lässt sich also weiterhin offline bauen. Der Stack gilt, solange og.fonts nicht gesetzt ist — das übernimmt dann die gesamte Liste.

Chinesisch, Japanisch und Koreanisch teilen sich die meisten Han-Schriftzeichen, zeichnen einige davon aber unterschiedlich, und Cards verwenden standardmäßig die japanischen Formen. Jede konfigurierte Locale rückt ihre eigene Familie nach vorne, sodass eine Site mit einer zh-Locale Han-Zeichen in vereinfachten chinesischen Formen zeichnet und mit zh-Hant oder zh-TW in traditionellen.

Setze theme.fonts, und die Card folgt dem. Wenn deine Config eigene Schriften wählt, rendern die generierten Cards die Überschrift automatisch in deiner Display-Schrift und Beschreibung sowie Fußzeile in deiner Body-Schrift, sodass geteilte Links zur Site passen — inklusive nicht-lateinischer Abdeckung, ganz ohne hier etwas zu konfigurieren. (Familien von anderen Anbietern als Google werden übersprungen — der Card-Renderer kann nur von Google Fonts laden — lokale Schriftdateien funktionieren aber.)

Um auf Cards andere Schriften als auf der Site zu verwenden, setze og.fonts explizit. Es sticht immer die aus dem Theme abgeleiteten Schriften und ersetzt die Schriftsystem-Fallbacks, führe also jede Familie auf, die deine Cards brauchen:

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

Jeder Eintrag ist ein Google-Fonts-Familienname, ein Objekt, das dessen weight (eine Zahl, eine Liste oder ein variabler Bereich wie "100..900") und style ("normal", "italic" oder beides) festlegt, oder eine lokale Schriftdatei — src wird relativ zum Projektstammverzeichnis aufgelöst, mit optionalen weight und style, falls die Metadaten der Datei selbst nicht entscheiden sollen.

Google-Familien werden beim Build geladen — ein Build, der sie verwendet, braucht also Netzwerkzugriff — und der Renderer holt nur die Glyphen-Subsets, die jeder Titel tatsächlich verwendet. Der Fallback greift pro Glyphe, das Hinzufügen einer Familie betrifft also nur Glyphen, die die anderen Schriften nicht zeichnen können.

Ein explizites og.fonts: [] deaktiviert das komplett: Cards behalten die eingebaute Schrift, selbst wenn theme.fonts gesetzt ist oder ein Titel einen Schriftsystem-Fallback bräuchte.

Card-Cache

Gerenderte Cards werden zwischen Builds auf der Festplatte zwischengespeichert, mit einem Schlüssel aus allem, was ihre Pixel bestimmt: Seitentitel und -beschreibung, Markentext, Logo, Palette, Fußzeilentext und Schriften (eine lokale Schriftdatei anhand ihres Inhalts) sowie die Blume-Version. Ein Rebuild rendert nur die Cards, deren Eingaben sich geändert haben, und liest den Rest aus dem Cache; das Build-Log meldet, wie viele wiederverwendet wurden. Der Cache liegt in node_modules/.cache/blume/og; auf einer Plattform, die node_modules zwischen Builds behält (Vercel und Netlify tun das, Cloudflare nicht), oder mit einem CI-Runner, der dieses Verzeichnis cacht (siehe Build-Cache), rendert ein Deploy, der eine Handvoll Seiten ändert, auch nur eine Handvoll Cards neu. Cards, die keine Seite angefordert hat, werden nach jedem Build entfernt, sodass das Verzeichnis immer nur die Cards der aktuellen Site enthält.

Eigene Seitentitel

Eine benutzerdefinierte .astro-Seite hat kein Frontmatter zum Auslesen, daher wird ihre generierte Card betitelt, indem das letzte URL-Segment ihrer Route lesbar gemacht wird — aus /getting-started wird „Getting Started”, aus /cli aber „Cli”. Benenne solche Cards explizit mit og.titles, nach Route indiziert ("/" adressiert die Startseite, deren Card sonst den Site-Titel trägt):

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

Einträge gelten nur für benutzerdefinierte Seiten — die Card einer Inhaltsseite übernimmt ihre Überschrift immer aus dem Seitentitel, ändere diese also stattdessen im Frontmatter.

seo.image ist Frontmatter und deckt daher nur Markdown- und MDX-Inhalte ab. Um einer benutzerdefinierten .astro-Seite ein eigenes Social-Bild zu geben — einer Marketing-Startseite oder Landingpage, und das ist auch der Weg, um allein der Startseite ein maßgeschneidertes Share-Bild zu geben — übergib die ogImage-Prop an PageLayout.