blume 2.2.2 → 2.2.3

package/src/ai/relative-links.ts

@@ -11,12 +11,15 @@ import { localePrefix } from "../core/i18n.ts";
 import {
   buildFileRouteIndex,
   isIndexFileName,
+  resolveRawRelativeHref,
   resolveRelativeHref,
   resolveRootFileHref,
+  routeOfLinkedEntry,
   routeOfLinkedFile,
 } from "../core/links.ts";
-import type { RelativeLinkBase } from "../core/links.ts";
+import type { FileRouteIndex, RelativeLinkBase } from "../core/links.ts";
 import { localizeHref, servesRoute } from "../core/locale-links.ts";
+import type { LocalizeHrefOptions } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { resolveDocsCollection } from "../core/sources/collection.ts";
 import { extractLinks } from "../core/sources/normalize.ts";
@@ -28,7 +31,9 @@ import { extractLinks } from "../core/sources/normalize.ts";
  * link lands on `/install`; the rendered page rewrites it to the route it
  * means (`markdown/relative-links.ts`), and the Markdown an agent reads gets
  * the same rewrite from the same resolver (`resolveRelativeHref`), so both
- * point at one page. Root-relative links (`[x](/guide)`,
+ * point at one page. A raw HTML `<a href>` ships as written, so a relative
+ * one lands where the browser takes it from the page's URL
+ * (`resolveRawRelativeHref`). Root-relative links (`[x](/guide)`,
  * `<Card href="/guide">`, `![logo](/logo.png)`) get what the rendered page
  * gives them too (`markdown/base-links.ts`,
  * `components/content/base-href.ts`): a page link the `deployment.base` +
@@ -40,10 +45,17 @@ import { extractLinks } from "../core/sources/normalize.ts";
  * (`resolveRootFileHref`). Inline links, images, component
  * `href`s, and reference definitions are rewritten; fenced and inline code,
  * relative images and asset links, and external URLs are left as written.
+ * The assistant's snapshot takes the links that name a page by its path or
+ * file alone, as the routes it keys pages by (`assistant`).
  */
 
 /** The page a Markdown text was written for. */
 export interface LinkedPage {
+  /**
+   * A staged page's path under its staging dir, which its links resolve from
+   * when it has no `sourcePath` (a remote or CMS source).
+   */
+  entryId?: string;
   route: string;
   sourcePath?: string;
 }
@@ -51,6 +63,20 @@ export interface LinkedPage {
 /** Rewrite a page's relative page links to the routes they mean. */
 export type RelativeLinkRewriter = (text: string, page: LinkedPage) => string;
 
+/** Who reads the rewritten links. */
+export interface RelativeLinkOptions {
+  /**
+   * The assistant's snapshot, rather than a page an agent fetches by URL.
+   * Only a link that names a page by its relative path or its content file
+   * changes, to the route the snapshot keys that page by: without the
+   * `deployment.base`, since the chat panel mounts every link it renders
+   * under it, and a locale's fallback copy as the page it renders, since the
+   * snapshot holds that page instead. Root page links and images stay as
+   * written.
+   */
+  assistant?: boolean;
+}
+
 /**
  * Whether a text could hold a relative page link at all: an inline link, a
  * reference definition, or a component `href` whose target isn't a URL with
@@ -123,16 +149,79 @@ const collectSplices = (
   return splices;
 };
 
+/** What a project's links resolve through, whoever reads them. */
+interface LinkIndex {
+  fileRoutes: FileRouteIndex;
+  localeByRoute: Map<string, string>;
+  navPathBySource: Map<string | undefined, string>;
+  routes: Set<string>;
+}
+
+// The mirrors, llms-full.txt and the assistant's snapshot each build a
+// rewriter for the same project, so the lookups behind them are built once.
+const linkIndexes = new WeakMap<BlumeProject, LinkIndex>();
+
+/**
+ * The file → route lookup a `.md`/`.mdx` link resolves through, and the
+ * routes a link can land on. A file shared by every locale publishes once
+ * per locale, and the default locale's route stands for it; fallback copies
+ * render another locale's file, so they never stand for one.
+ */
+const linkIndex = (project: BlumeProject): LinkIndex => {
+  let index = linkIndexes.get(project);
+  if (!index) {
+    const { config, graph, manifest } = project;
+    index = {
+      fileRoutes: buildFileRouteIndex(graph.pages, config.i18n ?? null),
+      localeByRoute: new Map(
+        manifest.routes.map((route) => [route.path, route.locale])
+      ),
+      navPathBySource: new Map(
+        graph.pages.map((page) => [page.sourcePath, page.navPath])
+      ),
+      routes: new Set(manifest.routes.map((route) => route.path)),
+    };
+    linkIndexes.set(project, index);
+  }
+  return index;
+};
+
+/**
+ * A resolved route as the assistant's snapshot keys it. A locale's fallback
+ * copy (`/fr/guides/install` with no French page there) renders another
+ * locale's page, which the snapshot holds in its place, so the route becomes
+ * that page's; every other route is kept, `?query#hash` and all.
+ */
+const snapshotRoute = (project: BlumeProject): ((route: string) => string) => {
+  const pageRoutes = new Map(
+    project.graph.pages.map((page) => [page.id, page.route])
+  );
+  const rendered = new Map<string, string>();
+  for (const route of project.manifest.routes) {
+    const page = route.fallback ? pageRoutes.get(route.id) : undefined;
+    if (page !== undefined) {
+      rendered.set(route.path, page);
+    }
+  }
+  return (route) => {
+    const suffixAt = route.search(/[?#]/u);
+    const path = suffixAt === -1 ? route : route.slice(0, suffixAt);
+    const page = rendered.get(path);
+    return page === undefined ? route : `${page}${route.slice(path.length)}`;
+  };
+};
+
 /**
- * Build the rewriter for a project: the file → route lookup a `.md`/`.mdx`
- * link resolves through is built once. A file shared by every locale
- * publishes once per locale, and the default locale's route stands for it;
- * fallback copies render another locale's file, so they never stand for one.
+ * Build the rewriter for a project, for an agent reading a page by URL or,
+ * with `assistant`, for the assistant's snapshot.
  */
 export const relativeLinkRewriter = (
-  project: BlumeProject
+  project: BlumeProject,
+  options: RelativeLinkOptions = {}
 ): RelativeLinkRewriter => {
   const { basePath, deployment, i18n } = project.config;
+  // Links are read under the real deployment base whoever reads them, so a
+  // root link to a content file that carries it is still recognized.
   const deployBase = normalizeBasePath(deployment.options.base);
   const contentRoot = resolveDocsCollection(
     project.config,
@@ -141,17 +230,38 @@ export const relativeLinkRewriter = (
   const localeTokens = i18n
     ? ["$", ...i18n.locales.map((locale) => locale.code)]
     : [];
-  const fileRoutes = buildFileRouteIndex(project.graph.pages, i18n ?? null);
-  const navPathBySource = new Map(
-    project.graph.pages.map((graphPage) => [
-      graphPage.sourcePath,
-      graphPage.navPath,
-    ])
-  );
-  const routes = new Set(project.manifest.routes.map((route) => route.path));
-  const localeByRoute = new Map(
-    project.manifest.routes.map((route) => [route.path, route.locale])
-  );
+  const { fileRoutes, localeByRoute, navPathBySource, routes } =
+    linkIndex(project);
+  const hasRoute = (path: string): boolean => routes.has(path);
+
+  // Where a resolved route lands for its reader. A route Blume serves takes
+  // the deployment base unconditionally — even over a route that starts with
+  // the base's name — except in the assistant's snapshot.
+  const land = options.assistant
+    ? snapshotRoute(project)
+    : (route: string): string => mountBasePath(deployBase, route);
+
+  /**
+   * How a page's root-relative links change, if they do: when the site is
+   * mounted under a prefix, or the page reads in a prefixed locale, whose
+   * copy of a route they move to. The assistant's snapshot keeps them as
+   * written.
+   */
+  const rootLinksOf = (
+    route: string
+  ): { localize?: LocalizeHrefOptions } | undefined => {
+    if (options.assistant) {
+      return undefined;
+    }
+    const locale = localeByRoute.get(route);
+    const localize =
+      i18n && locale !== undefined && localePrefix(locale, i18n) !== ""
+        ? { basePath, deployBase, i18n, locale, routes }
+        : undefined;
+    return deployBase !== "" || basePath !== "" || localize !== undefined
+      ? { localize }
+      : undefined;
+  };
 
   /**
    * A page's relative-link resolver; `undefined` when the page has no file
@@ -160,43 +270,36 @@ export const relativeLinkRewriter = (
   const relativeRoute = (
     page: LinkedPage
   ): ((target: string) => string | undefined) | undefined => {
-    const { sourcePath } = page;
-    if (!sourcePath) {
+    const { entryId, sourcePath } = page;
+    const file = sourcePath ?? entryId;
+    if (!file) {
       return;
     }
     const from: RelativeLinkBase = {
-      isIndex: isIndexFileName(basename(sourcePath), localeTokens),
+      isIndex: isIndexFileName(basename(file), localeTokens),
       route: page.route,
     };
-    const navPath = navPathBySource.get(sourcePath) ?? basename(sourcePath);
-    const resolveFile = (path: string): string | undefined =>
-      routeOfLinkedFile(fileRoutes, { navPath, sourcePath }, path);
-    // A resolved route is one Blume serves, so the deployment base goes on
-    // unconditionally — even over a route that starts with the base's name.
-    return (target) => {
-      const route = resolveRelativeHref(target, from, resolveFile, (path) =>
-        routes.has(path)
-      );
-      return route === undefined ? undefined : mountBasePath(deployBase, route);
-    };
+    // A staged page (a remote or CMS source) has no file on disk: it
+    // resolves a sibling by its entry id, as `blume validate` does.
+    let resolveFile: (path: string) => string | undefined;
+    if (sourcePath) {
+      const navPath = navPathBySource.get(sourcePath) ?? basename(sourcePath);
+      resolveFile = (path) =>
+        routeOfLinkedFile(fileRoutes, { navPath, sourcePath }, path);
+    } else {
+      resolveFile = (path) => routeOfLinkedEntry(fileRoutes, file, path);
+    }
+    return (target) => resolveRelativeHref(target, from, resolveFile, hasRoute);
   };
 
   /** Whether a page is served at a based, fragment-less path. */
   const servesPage = (route: string): boolean => servesRoute(routes, route);
 
   return (text, page) => {
-    const locale = localeByRoute.get(page.route);
-    // The page's locale moves root links only when it has a URL prefix.
-    const localize =
-      i18n && locale !== undefined && localePrefix(locale, i18n) !== ""
-        ? { basePath, deployBase, i18n, locale, routes }
-        : undefined;
-    // A root-relative link only changes when the site is mounted under a
-    // prefix or the page reads in a prefixed locale.
-    const rootLinks =
-      deployBase !== "" || basePath !== "" || localize !== undefined;
+    const rootLinks = rootLinksOf(page.route);
+    const localize = rootLinks?.localize;
     if (
-      !(page.sourcePath || rootLinks) ||
+      !(page.sourcePath || page.entryId || rootLinks) ||
       !(
         (rootLinks ? MAYBE_PAGE_LINK : MAYBE_RELATIVE).test(text) ||
         MAYBE_ROOT_FILE.test(text)
@@ -230,20 +333,24 @@ export const relativeLinkRewriter = (
       if (route === undefined) {
         return undefined;
       }
-      const based = mountBasePath(deployBase, route);
-      return localize ? localizeHref(based, localize) : based;
+      const landed = land(route);
+      return localize ? localizeHref(landed, localize) : landed;
     };
     const routed = (target: string, raw: boolean): string | undefined => {
       if (!isInternalPath(target)) {
-        return relative?.(target);
+        const route = raw
+          ? resolveRawRelativeHref(target, page.route, hasRoute)
+          : relative?.(target);
+        return route === undefined ? undefined : land(route);
       }
-      return (raw ? undefined : rootFile(target)) ?? rooted(target);
+      const file = raw ? undefined : rootFile(target);
+      return file ?? (rootLinks ? rooted(target) : undefined);
     };
     // An image is always a file: `public/` (or a generated asset endpoint),
     // served under the deployment base but never `basePath`. A relative one
     // is left to `core/content-assets.ts`.
     const imaged = (target: string): string | undefined => {
-      const based = withBasePath(deployBase, target);
+      const based = rootLinks ? withBasePath(deployBase, target) : target;
       return based === target ? undefined : based;
     };
 

package/src/ai/site-skill.ts

@@ -14,6 +14,7 @@ import type { NavNode, PageRecord } from "../core/types.ts";
 import { resolveReferences } from "../openapi/references.ts";
 import { docsPhrase } from "./ai-catalog.ts";
 import { API_PAGES_PATH } from "./api/paths.ts";
+import { linkText } from "./link-text.ts";
 import { asciiSlugify } from "./mcp/discovery.ts";
 import {
   SKILL_DESCRIPTION_MAX,
@@ -54,10 +55,6 @@ export const siteSkillName = (project: BlumeProject): string => {
   return name.slice(0, NAME_MAX).replace(/-+$/u, "");
 };
 
-/** A title as Markdown link text (brackets escaped, as in llms.txt). */
-const linkText = (title: string): string =>
-  title.replaceAll(/[\\[\]]/gu, String.raw`\$&`);
-
 /**
  * Current-version, default-locale pages worth listing: not API operations,
  * and not changelog entries, which the changelog index covers in one line.

package/src/astro/generate.ts

@@ -88,6 +88,7 @@ import type { Diagnostic, Navigation } from "../core/types.ts";
 import { getBlumeVersion } from "../core/version.ts";
 import { servedFiles } from "../deploy/generated-files.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
+import { hreflangAlternates } from "../deploy/sitemap.ts";
 import {
   languageIconCss,
   languageIconSlugsIn,
@@ -1204,6 +1205,8 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     i18n?.defaultLocale
   );
 
+  const hreflang = hreflangAlternates(project);
+
   const navigationByLocale = i18n
     ? Object.fromEntries(
         i18n.locales.map(({ code }) => [
@@ -1273,6 +1276,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
             }
           : null,
       imageZoom: config.markdown.imageZoom,
+      jsonLd: config.seo.jsonLd,
       logo,
       mcp: config.agents.mcp.enabled
         ? {
@@ -1293,6 +1297,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       og: {
         description: resolveOgDescription(config),
         enabled: config.seo.og.enabled ?? false,
+        image: config.seo.og.image,
         logo: ogLogo,
         palette: config.seo.og.palette,
         site: resolveOgSite(config),
@@ -1353,12 +1358,14 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       entryId: route.entryId,
       fallback: route.fallback ?? false,
       hidden: route.hidden,
+      hreflang: hreflang.get(route.path) ?? [],
       id: route.id,
       indexable: route.indexable,
       lastModified: route.lastModified ?? null,
       locale: route.locale,
       monolingual: route.monolingual ?? false,
       path: route.path,
+      published: route.published ?? null,
       title: route.title,
       version: route.version,
       versionAlternates: route.versionAlternates,

package/src/astro/templates.ts

@@ -2512,6 +2512,7 @@ import RootLayout from "blume/components/layout/RootLayout.astro";
 import { withBase, withMountedBase } from "blume/components/islands/base-path.ts";
 import { mountBasePath, stripBasePath } from "blume/core/base-path.ts";
 import { routeSetFor, servesRoute } from "blume/core/locale-links.ts";
+import { resolveLocalizable } from "blume/core/localizable.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 ${componentImports}
 import data from "blume:data";
@@ -2536,8 +2537,10 @@ export function getStaticPaths() {
       editUrl: route.editUrl,
       entryId: route.entryId,
       fallback: route.fallback,
+      hreflang: route.hreflang,
       indexable: route.indexable,
       lastModified: route.lastModified,
+      published: route.published,
       locale: route.locale,
       monolingual: route.monolingual,
       route: route.path,
@@ -2548,7 +2551,7 @@ export function getStaticPaths() {
   }));
 }
 
-const { entryId, collection, route, title, indexable, editUrl, lastModified, locale, alternates, fallback, monolingual, version, versionAlternates } = Astro.props;
+const { entryId, collection, route, title, indexable, editUrl, lastModified, published, locale, alternates, hreflang, fallback, monolingual, version, versionAlternates } = Astro.props;
 const entry = await getEntry(collection as CollectionKey, entryId);
 if (!entry) {
   return new Response(null, { status: 404 });
@@ -2598,19 +2601,23 @@ const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const ogPath = data.config.og.enabled
   ? encodeURI(\`/og/\${route === "/" ? "index" : route.slice(1)}.png\`)
   : null;
-// Absolute URLs also carry the deployment base (the page is served under it):
-// \`site + base + path\`. Only absolutize root-relative paths: \`seo.image\` may be
+// Root-relative paths carry the deployment base (the page is served under it),
+// and the site too once it's known: \`site + base + path\`. \`seo.image\` may be
 // an external URL, which passes through verbatim (mirrors PageLayout). An
-// authored \`seo.image\` keeps a base written by hand; the generated card is
-// always mounted under it.
+// authored image keeps a base written by hand; the generated card is always
+// mounted under it.
 const absoluteOg = (path: string, based: (path: string) => string) =>
-  base && path.startsWith("/") ? \`\${base}\${based(path)}\` : path;
-const ogImage = seo.image
-  ? absoluteOg(seo.image, withBase)
+  path.startsWith("/") ? \`\${base ?? ""}\${based(path)}\` : path;
+// The page's own image, else the site's default for its locale.
+const selectedOgImage =
+  seo.image ??
+  (data.config.og.image && resolveLocalizable(data.config.og.image, locale, data.config.i18n?.defaultLocale));
+const ogImage = selectedOgImage
+  ? absoluteOg(selectedOgImage, withBase)
   : ogPath && absoluteOg(ogPath, withMountedBase);
-// Blume's generated card has known dimensions the layout can declare; a user's
-// \`seo.image\` could be any size or format, so it gets none.
-const ogGenerated = !seo.image && Boolean(ogPath);
+// Blume's generated card has known dimensions the layout can declare; an
+// authored image could be any size or format, so it gets none.
+const ogGenerated = !selectedOgImage && Boolean(ogPath);
 
 // X attribution: the site's account, plus a creator the page can claim for
 // itself (a guest post crediting its own author) over the configured default.
@@ -2706,11 +2713,12 @@ const canonical =
       : null);
 const effectiveNoindex = Boolean(seo.noindex) || (archived?.noindex ?? false);
 
+// hreflang names only indexable translations (see \`hreflangAlternates\`).
 const localeAlternates =
   i18n && base
-    ? (alternates ?? []).map((alt) => ({ hreflang: alt.locale, href: absolute(alt.path) }))
+    ? (hreflang ?? []).map((alt) => ({ hreflang: alt.locale, href: absolute(alt.path) }))
     : [];
-const defaultAlt = i18n ? (alternates ?? []).find((alt) => alt.locale === i18n.defaultLocale) : null;
+const defaultAlt = i18n ? (hreflang ?? []).find((alt) => alt.locale === i18n.defaultLocale) : null;
 const xDefault = defaultAlt && base ? absolute(defaultAlt.path) : null;
 
 // \`route\` arrives with \`basePath\` already applied, so the locale segment it
@@ -2874,7 +2882,8 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   pageType={frontmatter.type}
   apiRail={remarkPluginFrontmatter?.${API_RAIL_KEY} === true}
   pageMode={frontmatter.mode}
-  published={frontmatter.date ?? frontmatter.changelog?.date ?? null}
+  published={frontmatter.date ?? frontmatter.changelog?.date ?? published}
+  authors={frontmatter.authors}
   lastModified={lastModified}
   noindex={effectiveNoindex}
   structuredDataEnabled={data.config.structuredData}
@@ -2922,8 +2931,9 @@ export const changelogIndexTemplate = (options: {
 // Generated by Blume. Do not edit.
 import RootLayout from "blume/components/layout/RootLayout.astro";
 import Changelog from "blume/components/content/Changelog.astro";
-import { withMountedBase } from "blume/components/islands/base-path.ts";
+import { withBase, withMountedBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
+import { resolveLocalizable } from "blume/core/localizable.ts";
 import { layoutOverrides } from "../generated/components.ts";
 import data from "blume:data";
 
@@ -2945,11 +2955,17 @@ const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const basedRoute = withMountedBase("/changelog");
 const canonical = base ? base + basedRoute : null;
 
-// The generated OG card for this route (the /og endpoint emits it alongside
-// the content-route cards), absolutized like the catch-all's so crawlers get
-// a full URL when the site is known.
+// The site's default image, else the generated OG card for this route (the /og
+// endpoint emits it alongside the content-route cards), absolutized like the
+// catch-all's so crawlers get a full URL when the site is known.
+const defaultOgImage =
+  data.config.og.image && resolveLocalizable(data.config.og.image, htmlLang, i18n?.defaultLocale);
 const ogPath = data.config.og.enabled ? withMountedBase("/og/changelog.png") : null;
-const ogImage = ogPath && base ? base + ogPath : ogPath;
+const ogImage = defaultOgImage
+  ? defaultOgImage.startsWith("/")
+    ? (base ?? "") + withBase(defaultOgImage)
+    : defaultOgImage
+  : ogPath && base ? base + ogPath : ogPath;
 
 // The page chrome (h1, title, description) comes from the translatable
 // \`changelog\` group, which carries the \`changelog\` config's title and
@@ -2997,7 +3013,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   searchEnabled={data.config.search.enabled}
   indexable={true}
   ogImage={ogImage}
-  ogGenerated={Boolean(ogImage)}
+  ogGenerated={!defaultOgImage && Boolean(ogImage)}
   x={data.config.x}
   canonical={canonical}
   exportPdf={${options.exportPdf}}

package/src/components/layout/PageLayout.astro

@@ -41,6 +41,7 @@ import { normalizeXHandle } from "../../seo/x-handle.ts";
 import Icon from "../Icon.astro";
 import { stripBase, withBase, withMountedBase } from "../islands/base-path.ts";
 import { routeSetFor } from "../../core/locale-links.ts";
+import { resolveLocalizable } from "../../core/localizable.ts";
 import {
   browserLanguageTargets,
   LOCALE_REDIRECT_SCRIPT,
@@ -265,20 +266,30 @@ const resolvedCanonical =
   (siteBase
     ? `${siteBase}${basedRoute === "/" ? "/" : encodeURI(basedRoute)}`
     : null);
-// An explicit `ogImage` wins. A root-relative path (e.g. an image dropped in
-// `public/`) is resolved against the site URL so crawlers get an absolute
-// `og:image`; an already-absolute URL passes through untouched. Otherwise fall
-// back to the generated OG card for this route.
+// An explicit `ogImage` wins, then the site's default image for this locale. A
+// root-relative path (e.g. an image dropped in `public/`) is served under the
+// deployment base and resolved against the site URL so crawlers get an
+// absolute `og:image`; an already-absolute URL passes through untouched.
+// Otherwise fall back to the generated OG card for this route.
 const absolutizeOgImage = (value: string): string =>
-  value.startsWith("/") && siteBase ? `${siteBase}${withBase(value)}` : value;
-const resolvedOgImage = ogImage
-  ? absolutizeOgImage(ogImage)
+  value.startsWith("/") ? `${siteBase ?? ""}${withBase(value)}` : value;
+const selectedOgImage =
+  ogImage ??
+  (data.config.og.image &&
+    resolveLocalizable(
+      data.config.og.image,
+      locale,
+      data.config.i18n?.defaultLocale
+    ));
+const resolvedOgImage = selectedOgImage
+  ? absolutizeOgImage(selectedOgImage)
   : ogEnabled && ogCardGenerated && siteBase
     ? `${siteBase}${encodeURI(withMountedBase(`/og/${ogSlug}.png`))}`
     : null;
 // Only the generated card has a known size and format, so its dimensions are
-// declared for crawlers; a user-supplied `ogImage` could be any image.
-const ogGenerated = !ogImage && Boolean(resolvedOgImage);
+// declared for crawlers; any other image could be any size. The size and alt
+// props describe the page's own `ogImage`, never the site default.
+const ogGenerated = !selectedOgImage && Boolean(resolvedOgImage);
 // A page with no image still gets a card on X — the compact `summary` variant
 // — rather than rendering as a bare link.
 const twitterCard = resolvedOgImage ? "summary_large_image" : "summary";
@@ -297,6 +308,8 @@ const structuredData =
       breadcrumbs: [],
       description,
       identity: data.config.identity,
+      jsonLd: data.config.jsonLd,
+      image: resolvedOgImage,
       locale,
       modified: lastModified,
       route,
@@ -386,7 +399,7 @@ const localeRedirect = localeTargets
               <meta content={pageTitle} property="og:image:alt" />
             </>
           )}
-          {!ogGenerated && ogImageSize && (
+          {ogImage && ogImageSize && (
             <>
               <meta
                 content={String(ogImageSize.width)}
@@ -398,12 +411,12 @@ const localeRedirect = localeTargets
               />
             </>
           )}
-          {!ogGenerated && ogImageAlt && (
+          {ogImage && ogImageAlt && (
             <meta content={ogImageAlt} property="og:image:alt" />
           )}
           <meta content={resolvedOgImage} name="twitter:image" />
           {ogGenerated && <meta content={pageTitle} name="twitter:image:alt" />}
-          {!ogGenerated && ogImageAlt && (
+          {ogImage && ogImageAlt && (
             <meta content={ogImageAlt} name="twitter:image:alt" />
           )}
         </>

package/src/components/layout/RootLayout.astro

@@ -43,6 +43,7 @@ import {
   OG_IMAGE_WIDTH,
 } from "../../og/dimensions.ts";
 import { buildStructuredData, toIso } from "../../seo/jsonld.ts";
+import type { AuthorInput } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase, withMountedBase } from "../islands/base-path.ts";
 import { routeSetFor } from "../../core/locale-links.ts";
@@ -196,6 +197,8 @@ interface Props {
   /** The page's `mode` frontmatter: what it shows around its content (see `core/page-modes.ts`). */
   pageMode?: PageMode;
   published?: string | Date | null;
+  /** The page's front matter `authors`, credited in its JSON-LD. */
+  authors?: AuthorInput | AuthorInput[];
   lastModified?: string | null;
   noindex?: boolean;
   structuredDataEnabled?: boolean;
@@ -312,6 +315,7 @@ const {
   apiRail = false,
   pageMode,
   published,
+  authors,
   lastModified,
   noindex,
   structuredDataEnabled,
@@ -534,11 +538,14 @@ const structuredData =
   structuredDataEnabled === false || noindex
     ? null
     : buildStructuredData({
+      authors,
       base: import.meta.env.BASE_URL,
       breadcrumbs: crumbs,
       description,
       homeRoute: navigation.root,
       identity: data.config.identity,
+      jsonLd: data.config.jsonLd,
+      image: ogImage,
       locale,
       modified: lastModified,
       pageType,