blume 1.5.0 → 1.5.1

package/dist/types/core/config-input.d.ts

@@ -438,7 +438,7 @@ export type FontInput = LiteralUnion<FontSlug> | RemoteFontInput | LocalFontInpu
 export interface FontsConfig {
     /** Body / prose font. Defaults to `inter`. */
     body?: FontInput;
-    /** Display / heading font. Defaults to `inter-tight`. */
+    /** Display / heading font. Defaults to `inter` (shared with the body). */
     display?: FontInput;
     /** Monospace / code font. Defaults to `ibm-plex-mono`. */
     mono?: FontInput;

package/dist/types/core/data.d.ts

@@ -1,3 +1,4 @@
+import type { FontHead } from "../theme/fonts.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
 import type { Navigation, RouteAlternate, VersionAlternate } from "./types.ts";
@@ -209,8 +210,8 @@ export interface BlumeClientData {
 export interface BlumeData {
     config: BlumeDataConfig;
     feeds: BlumeFeed[];
-    /** CSS variable names for the configured fonts (Astro `<Font>` integration). */
-    fontCssVars: string[];
+    /** Configured fonts for the head: CSS variable + preload weights per family. */
+    fontCssVars: FontHead[];
     /** Sidebar + tab tree for the default locale. */
     navigation: Navigation;
     /** Per-locale navigation trees, keyed by locale code (empty without i18n). */

package/dist/types/theme/fonts.d.ts

@@ -203,5 +203,14 @@ export declare const buildFontEntries: (fonts: FontsConfig) => FontEntry[];
  * config tokens; empty when no fonts are set so defaults stay the system stacks.
  */
 export declare const buildFontsCss: (fonts: FontsConfig) => string;
-/** The CSS variables to feed Astro's `<Font>` component in the document head. */
-export declare const configuredCssVars: (fonts: FontsConfig) => string[];
+/** One `<Font>` render in the head: its CSS variable + weights to preload. */
+export interface FontHead {
+    cssVariable: string;
+    preloadWeights: number[];
+}
+/**
+ * The fonts to feed Astro's `<Font>` component in the document head, deduped
+ * by CSS variable with preload weights unioned across the roles that share a
+ * family (so `display` and `body` both set to Inter preload 400/500/600 once).
+ */
+export declare const configuredFonts: (fonts: FontsConfig) => FontHead[];

package/docs/advanced/custom-pages.mdx

@@ -231,13 +231,17 @@ Passing `siteUrl` (and `ogEnabled`) derives the page's `canonical` and a generat
   siteUrl={config.site}
   ogEnabled={config.og.enabled}
   ogImage="/opengraph-image.png"
+  ogImageAlt="Acme — the fastest docs"
+  ogImageSize={{ width: 1200, height: 630 }}
   page={{ title: config.title }}
 >
   <!-- page content -->
 </PageLayout>
 ```
 
-Only this page changes — every other route keeps its generated card — so it's how you give the home page alone a bespoke share image.
+Only this page changes — every other route keeps its generated card — so it's how you give the home page alone a bespoke share image. The generated card declares its size and alt text to crawlers on its own; for your own `ogImage`, pass `ogImageAlt` and `ogImageSize` alongside so the share card gets the same treatment.
+
+The page also emits schema.org JSON-LD — the same `WebSite` graph the docs pages carry, so the home page (usually a custom page) isn't the one URL without structured data. Pass `structuredDataEnabled={config.structuredData}` to keep it in sync with the [`structuredData`](/docs/configuration/seo) config, or `structuredDataEnabled={false}` to turn it off for one page.
 
 `page.title` is used verbatim as the document title (no `- siteTitle` suffix), since marketing pages usually set their own. To give a custom page the full docs chrome instead — sidebar, TOC, and all — wrap it in `RootLayout`, the layout the generated pages use. Pull the required props straight from `blume:data`:
 

package/docs/configuration/index.mdx

@@ -289,7 +289,7 @@ lastModified: true,
 | `{ type: "git" }` | Same as `true`, written explicitly. |
 | `{ type: "frontmatter" }` | Never run git — use only the `lastModified` frontmatter field. |
 
-The git source reads the most recent commit that touched each file, so it works in any git repository — including monorepos — and needs the repo's history at build time (avoid a shallow `--depth 1` checkout in CI). A page's own `lastModified` frontmatter always wins, which is handy for pinning a date or for files that aren't committed yet:
+The git source reads the most recent commit that touched each file, so it works in any git repository — including monorepos — and needs the repo's history at build time. CI platforms usually check out a shallow clone, which silently drops most dates (the build warns with `BLUME_SHALLOW_GIT_HISTORY` when that happens): on Vercel, set the `VERCEL_DEEP_CLONE=true` environment variable; with `actions/checkout`, set `fetch-depth: 0`. A page's own `lastModified` frontmatter always wins, which is handy for pinning a date or for files that aren't committed yet:
 
 ```mdx page.mdx
 ---

package/docs/configuration/theming.mdx

@@ -15,7 +15,7 @@ theme: {
   radius: "md",     // none | sm | md | lg
   mode: "system",   // system | light | dark
   fonts: {          // self-hosted Google Fonts
-    display: "inter-tight",
+    display: "inter",
     body: "inter",
     mono: "ibm-plex-mono",
   },
@@ -57,12 +57,14 @@ A toggle in the header always lets readers switch, and their choice is remembere
 - **`body`** — body text, UI, and prose
 - **`mono`** — code blocks and inline code
 
+Headings get display-grade letter-spacing (`-0.05em`) from the theme itself, so whatever you pick for `display` — including text families like the Inter default — reads correctly at heading sizes instead of depending on tracking built into the font.
+
 Each defaults to a curated Google Font, so Blume looks intentional out of the box:
 
 ```ts blume.config.ts lineNumbers
 theme: {
   fonts: {
-    display: "inter-tight",   // default
+    display: "inter",         // default
     body: "inter",            // default
     mono: "ibm-plex-mono",    // default
   },

package/docs/reference/cli.mdx

@@ -1,6 +1,6 @@
 ---
 title: CLI
-description: Every Blume command and flag explained in one place — init, dev, build, preview, add, sync, and eject — along with the options each one accepts.
+description: Every Blume command and flag explained in one place, along with the options each one accepts.
 ---
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/astro/generate.ts

@@ -61,7 +61,7 @@ import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
 } from "../theme/entry.ts";
-import { buildFontsCss, configuredCssVars } from "../theme/fonts.ts";
+import { buildFontsCss, configuredFonts } from "../theme/fonts.ts";
 import { buildThemeCss } from "../theme/palette.ts";
 import { twoslashCss } from "../theme/twoslash.ts";
 import { planComponentSlots } from "./component-slots.ts";
@@ -1255,7 +1255,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     })),
     // CSS variables for Astro's <Font> component; matches the astro.config
     // `fonts:` entries derived from the same theme.fonts config.
-    fontCssVars: configuredCssVars(config.theme.fonts),
+    fontCssVars: configuredFonts(config.theme.fonts),
     navigation: withRepoUrl(graph.navigation),
     // Per-locale navigation; the catch-all selects the active locale's tree.
     navigationByLocale,
@@ -1624,6 +1624,11 @@ export const generateRuntime = async (
   // private and filtered out anyway, but the intent is the user's pages.
   const ogRoutes = customOgRoutes(pages, config.title, config.seo.og.titles);
 
+  // Whether the generated `/changelog` index exists — shared by the OG endpoint
+  // (which adds the index's own card) and the page write below. Computed here,
+  // before the MCP discovery pages are appended, on the user's own pages.
+  const changelogIndex = hasGeneratedChangelog(project, pages);
+
   // The hosted MCP server. The `.well-known` discovery docs are injected as
   // prerendered routes alongside user pages; the server endpoint itself is a
   // normal (server-rendered) page written by `writeMcpFiles`.
@@ -1780,12 +1785,12 @@ export const generateRuntime = async (
   if (config.seo.og.enabled) {
     await write(
       join(srcDir, "pages", "og", "[...slug].png.ts"),
-      ogEndpointTemplate(ogRoutes, projectOgFonts(project))
+      ogEndpointTemplate(ogRoutes, projectOgFonts(project), changelogIndex)
     );
   }
 
   // Changelog index (`/changelog`), rendered through the Update timeline layout.
-  if (hasGeneratedChangelog(project, pages)) {
+  if (changelogIndex) {
     await write(
       join(srcDir, "pages", "changelog.astro"),
       changelogIndexTemplate({
@@ -1906,7 +1911,7 @@ export const generateRuntime = async (
     ...pages.map((page) => page.pattern),
     ...referenceRoutes(config),
   ]);
-  if (hasGeneratedChangelog(project, pages)) {
+  if (changelogIndex) {
     navTargetRoutes.add("/changelog");
   }
   // Curated `search.popular` icons live outside the navigation model, so they

package/src/astro/templates.ts

@@ -694,6 +694,11 @@ ${userConfigSetup}export default defineConfig({
     },
   },
   devToolbar: { enabled: false },
+  // Navigations are full document loads (no client router), so the next page's
+  // HTML is fetched on hover/viewport to hide the request latency behind the
+  // user's intent. Pairs with the cross-document view-transition rule in the
+  // theme sheet, which smooths the swap itself.
+  prefetch: { prefetchAll: true },
   vite: {
     plugins: [tailwindcss(), prerenderDepsPlugin(), serverAppResolvePlugin()],
     // Everything hydration can reach must be part of the dev dep optimizer's
@@ -1454,7 +1459,8 @@ export function GET({ props }: { props: { section: string } }) {
 /** Generate the OG image endpoint (`.blume/src/pages/og/[...slug].png.ts`). */
 export const ogEndpointTemplate = (
   customRoutes: OgCustomRoute[] = [],
-  og: { families?: OgFontFamilies; fonts?: OgFont[] } = {}
+  og: { families?: OgFontFamilies; fonts?: OgFont[] } = {},
+  includeChangelog = false
 ): string =>
   `// Generated by Blume. Do not edit.
 import { renderOgImage } from "blume/og";
@@ -1493,6 +1499,13 @@ export function getStaticPaths() {
   }
   for (const route of data.routes) {
     add(route.path === "/" ? "index" : route.path.slice(1), route.title);
+  }${
+    includeChangelog
+      ? `
+  // The generated changelog index is not a content route, so it needs its own
+  // card. Added last: a custom page or content route owning /changelog wins.
+  add("changelog", data.ui.changelog?.title ?? "Changelog");`
+      : ""
   }
   return paths;
 }
@@ -1795,10 +1808,9 @@ const contentLocale =
 const contentDir = i18n
   ? (i18n.locales.find((l) => l.code === contentLocale)?.dir ?? "ltr")
   : "ltr";
-const absolute = (path: string) => {
-  const p = withBase(path);
-  return base + (p === "/" ? "" : p);
-};
+// The root route keeps its trailing slash (\`https://site/\`) so canonical and
+// hreflang URLs byte-match the sitemap's <loc> for the home page.
+const absolute = (path: string) => base + withBase(path);
 
 // An archived page defaults its canonical to the same page in the latest docs
 // when that page still exists — search engines treat the live page as
@@ -1809,7 +1821,7 @@ const canonical =
   (archived && archived.canonical === "latest" && latestVersionAlt && base
     ? absolute(latestVersionAlt.path)
     : base
-      ? \`\${base}\${basedRoute === "/" ? "" : encodeURI(basedRoute)}\`
+      ? \`\${base}\${basedRoute === "/" ? "/" : encodeURI(basedRoute)}\`
       : null);
 const effectiveNoindex = Boolean(seo.noindex) || (archived?.noindex ?? false);
 
@@ -2122,6 +2134,12 @@ const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const basedRoute = withBase("/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.
+const ogPath = data.config.og.enabled ? withBase("/og/changelog.png") : null;
+const ogImage = ogPath && base ? base + ogPath : ogPath;
+
 // The page chrome (h1, title, description) comes from the same translatable
 // \`changelog\` group as the reveal button; optional chaining tolerates a
 // not-yet-regenerated data snapshot from before these keys existed.
@@ -2129,7 +2147,10 @@ const changelogTitle = data.ui.changelog?.title ?? "Changelog";
 const changelogDescription =
   data.ui.changelog?.description ??
   "Product updates, new features, and fixes from every release.";
-const pageTitle = data.config.title + " " + changelogTitle;
+// The layout suffixes "- {site title}" itself, so the page title is just the
+// changelog's own name — prefixing the site title too would double it
+// ("Acme Changelog - Acme").
+const pageTitle = changelogTitle;
 
 const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
@@ -2161,7 +2182,8 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
   indexable={true}
-  ogImage={null}
+  ogImage={ogImage}
+  ogGenerated={Boolean(ogImage)}
   x={data.config.x}
   canonical={canonical}
   exportPdf={${options.exportPdf}}

package/src/components/layout/Fonts.astro

@@ -1,14 +1,34 @@
 ---
 // Emits the optimized @font-face declarations + preload links for each
 // configured font (Astro's Fonts API). Renders nothing when no fonts are set;
-// the CSS variables match the astro.config `fonts:` entries.
+// the CSS variables match the astro.config `fonts:` entries. Preloads are
+// narrowed to the weights above-the-fold text renders in (see
+// `theme/fonts.ts`); a bare string entry — an older generated template — keeps
+// the previous preload-everything behavior.
 import { Font } from "astro:assets";
+import type { FontHead } from "../../theme/fonts.ts";
 
 interface Props {
-  cssVars: string[];
+  cssVars: (string | FontHead)[];
 }
 
 const { cssVars } = Astro.props;
+
+const entries = cssVars.map((value) =>
+  typeof value === "string"
+    ? { cssVariable: value, preload: true as const }
+    : {
+        cssVariable: value.cssVariable,
+        preload: value.preloadWeights.map((weight) => ({
+          style: "normal" as const,
+          weight,
+        })),
+      }
+);
 ---
 
-{cssVars.map((cssVar) => <Font cssVariable={cssVar} preload />)}
+{
+  entries.map((entry) => (
+    <Font cssVariable={entry.cssVariable} preload={entry.preload} />
+  ))
+}

package/src/components/layout/PageLayout.astro

@@ -24,12 +24,14 @@ import type {
 } from "../../core/data.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import type { FontHead } from "../../theme/fonts.ts";
 import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
 import {
   OG_IMAGE_HEIGHT,
   OG_IMAGE_TYPE,
   OG_IMAGE_WIDTH,
 } from "../../og/dimensions.ts";
+import { buildStructuredData } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase } from "../islands/base-path.ts";
 import "blume:theme";
@@ -57,7 +59,7 @@ interface Props {
    */
   page?: { title?: string; description?: string; route?: string };
   themeMode: "system" | "light" | "dark";
-  fontCssVars?: string[];
+  fontCssVars?: (string | FontHead)[];
   searchEnabled: boolean;
   /**
    * Opt this page out of the header's Ask AI trigger. Defaults to whether Ask
@@ -75,7 +77,24 @@ interface Props {
   ogEnabled?: boolean;
   /** SEO overrides; a marketing page often sets its own canonical/og image. */
   ogImage?: string | null;
+  /**
+   * Alt text for a user-supplied `ogImage`, emitted as `og:image:alt` /
+   * `twitter:image:alt`. The generated card derives its own from the title.
+   */
+  ogImageAlt?: string;
+  /**
+   * Pixel size of a user-supplied `ogImage`, emitted as `og:image:width` /
+   * `og:image:height` so crawlers can lay the card out before fetching it.
+   * The generated card declares its known size automatically.
+   */
+  ogImageSize?: { height: number; width: number };
   canonical?: string | null;
+  /**
+   * Emit schema.org JSON-LD for this page (`data.config.structuredData`) — a
+   * WebSite node, plus an article node on non-root routes. Defaults to on,
+   * matching RootLayout.
+   */
+  structuredDataEnabled?: boolean;
   /**
    * X (Twitter) attribution (`data.config.x`): the site's account and an author
    * handle, emitted as `twitter:site`/`twitter:creator`.
@@ -113,7 +132,10 @@ const {
   siteUrl,
   ogEnabled,
   ogImage,
+  ogImageAlt,
+  ogImageSize,
   canonical,
+  structuredDataEnabled,
   x,
   noindex,
   locale = "en",
@@ -153,11 +175,12 @@ const basedRoute = withBase(route);
 // don't come out double-slashed — the catch-all strips it the same way.
 const siteBase = siteUrl ? siteUrl.replace(/\/$/u, "") : null;
 // The route-derived part is percent-encoded (the sitemap convention) so a
-// Unicode route slug yields a legal URI that byte-matches the sitemap <loc>.
+// Unicode route slug yields a legal URI that byte-matches the sitemap <loc> —
+// including the root, whose <loc> is `https://site/` with the slash.
 const resolvedCanonical =
   canonical ??
   (siteBase
-    ? `${siteBase}${basedRoute === "/" ? "" : encodeURI(basedRoute)}`
+    ? `${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
@@ -180,6 +203,25 @@ const twitterCard = resolvedOgImage ? "summary_large_image" : "summary";
 const xSite = normalizeXHandle(x?.handle);
 const xCreator = normalizeXHandle(x?.creator);
 
+// JSON-LD, mirroring RootLayout: skipped when disabled or noindexed. A custom
+// page has no breadcrumb trail; the home route yields the WebSite node alone.
+const structuredData =
+  structuredDataEnabled === false || noindex
+    ? null
+    : buildStructuredData({
+      base: import.meta.env.BASE_URL,
+      breadcrumbs: [],
+      description,
+      locale,
+      route,
+      siteName: site.title,
+      siteUrl: siteUrl ?? null,
+      title: pageTitle,
+    });
+const structuredDataJson = structuredData
+  ? JSON.stringify(structuredData).replaceAll("<", "\\u003c")
+  : null;
+
 const bannerKey = banner?.dismissible ? banner.key : null;
 ---
 
@@ -218,8 +260,26 @@ const bannerKey = banner?.dismissible ? banner.key : null;
               <meta content={pageTitle} property="og:image:alt" />
             </>
           )}
+          {!ogGenerated && ogImageSize && (
+            <>
+              <meta
+                content={String(ogImageSize.width)}
+                property="og:image:width"
+              />
+              <meta
+                content={String(ogImageSize.height)}
+                property="og:image:height"
+              />
+            </>
+          )}
+          {!ogGenerated && ogImageAlt && (
+            <meta content={ogImageAlt} property="og:image:alt" />
+          )}
           <meta content={resolvedOgImage} name="twitter:image" />
           {ogGenerated && <meta content={pageTitle} name="twitter:image:alt" />}
+          {!ogGenerated && ogImageAlt && (
+            <meta content={ogImageAlt} name="twitter:image:alt" />
+          )}
         </>
       )
     }
@@ -228,6 +288,15 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     {description && <meta content={description} name="twitter:description" />}
     {xSite && <meta content={xSite} name="twitter:site" />}
     {xCreator && <meta content={xCreator} name="twitter:creator" />}
+    {
+      structuredDataJson && (
+        <script
+          is:inline
+          set:html={structuredDataJson}
+          type="application/ld+json"
+        />
+      )
+    }
     {
       bannerKey && (
         <script data-key={bannerKey} is:inline set:html={BANNER_INIT_SCRIPT} />

package/src/components/layout/ReferenceLayout.astro

@@ -2,6 +2,7 @@
 import "blume:theme";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import type { FontHead } from "../../theme/fonts.ts";
 import type { Navigation } from "../../core/types.ts";
 import Analytics from "./Analytics.astro";
 import WebMcp from "./WebMcp.astro";
@@ -51,7 +52,7 @@ interface Props {
   navigation: Navigation;
   route: string;
   themeMode: "system" | "light" | "dark";
-  fontCssVars?: string[];
+  fontCssVars?: (string | FontHead)[];
   searchEnabled: boolean;
   pageTitle: string;
   /** Keep the reference route out of crawler indexes. */

package/src/components/layout/RootLayout.astro

@@ -11,6 +11,7 @@ import type {
   NavSelector as NavSelectorType,
 } from "../../core/types.ts";
 import "blume:theme";
+import type { FontHead } from "../../theme/fonts.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
 import {
   OG_IMAGE_HEIGHT,
@@ -90,7 +91,7 @@ interface Props {
   imageZoom?: boolean;
   codeWrap?: boolean;
   themeMode: "system" | "light" | "dark";
-  fontCssVars?: string[];
+  fontCssVars?: (string | FontHead)[];
   searchEnabled: boolean;
   indexable: boolean;
   ogImage?: string | null;

package/src/core/config-input.ts

@@ -510,7 +510,7 @@ export type FontInput =
 export interface FontsConfig {
   /** Body / prose font. Defaults to `inter`. */
   body?: FontInput;
-  /** Display / heading font. Defaults to `inter-tight`. */
+  /** Display / heading font. Defaults to `inter` (shared with the body). */
   display?: FontInput;
   /** Monospace / code font. Defaults to `ibm-plex-mono`. */
   mono?: FontInput;

package/src/core/data.ts

@@ -1,3 +1,4 @@
+import type { FontHead } from "../theme/fonts.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
 import type { Navigation, RouteAlternate, VersionAlternate } from "./types.ts";
@@ -192,8 +193,8 @@ export interface BlumeClientData {
 export interface BlumeData {
   config: BlumeDataConfig;
   feeds: BlumeFeed[];
-  /** CSS variable names for the configured fonts (Astro `<Font>` integration). */
-  fontCssVars: string[];
+  /** Configured fonts for the head: CSS variable + preload weights per family. */
+  fontCssVars: FontHead[];
   /** Sidebar + tab tree for the default locale. */
   navigation: Navigation;
   /** Per-locale navigation trees, keyed by locale code (empty without i18n). */

package/src/core/last-modified.ts

@@ -2,6 +2,8 @@ import { execFileSync } from "node:child_process";
 
 import { relative } from "pathe";
 
+import type { Diagnostic } from "./types.ts";
+
 /** Normalized form of the `lastModified` config. */
 export interface ResolvedLastModified {
   enabled: boolean;
@@ -95,3 +97,50 @@ export const gitLastModifiedTimes = (
     return new Map();
   }
 };
+
+/**
+ * Whether the repository containing `root` is a shallow clone. Returns false
+ * when git is unavailable or the project isn't a repo — those cases already
+ * yield no dates at all, and the shallow warning would only mislead.
+ */
+export const isShallowGitRepository = (root: string): boolean => {
+  try {
+    return (
+      execFileSync(
+        // oxlint-disable-next-line sonarjs/no-os-command-from-path -- git is a required dev-tool dependency resolved from PATH
+        "git",
+        ["-C", root, "rev-parse", "--is-shallow-repository"],
+        // stderr silenced: outside a repository the probe fails by design.
+        { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }
+      ).trim() === "true"
+    );
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * A warning for git-derived dates silently missing because the build ran in a
+ * shallow clone — the default on Vercel and `actions/checkout`, where `git log`
+ * only sees the last few commits, so most pages get no date and the sitemap's
+ * `<lastmod>` / "Last updated" stamps quietly disappear in production while
+ * working locally. Empty when every page got a date or the clone isn't
+ * shallow.
+ */
+export const lastModifiedShallowWarning = (
+  root: string,
+  undatedCount: number
+): Diagnostic[] => {
+  if (undatedCount === 0 || !isShallowGitRepository(root)) {
+    return [];
+  }
+  return [
+    {
+      code: "BLUME_SHALLOW_GIT_HISTORY",
+      message: `lastModified is on, but this build runs in a shallow git clone, so ${undatedCount} page(s) have no git-derived date — their sitemap <lastmod> and "Last updated" stamps are omitted.`,
+      severity: "warning",
+      suggestion:
+        "Fetch full history in CI: set the VERCEL_DEEP_CLONE=true environment variable on Vercel, or fetch-depth: 0 for actions/checkout.",
+    },
+  ];
+};

package/src/core/project-graph.ts

@@ -6,6 +6,7 @@ import { buildContentGraph } from "./graph.ts";
 import { i18nDiagnostics } from "./i18n.ts";
 import {
   gitLastModifiedTimes,
+  lastModifiedShallowWarning,
   resolveLastModifiedConfig,
 } from "./last-modified.ts";
 import { buildManifest } from "./manifest.ts";
@@ -294,6 +295,7 @@ export const scanProject = async (
   // (which shares these page objects) picks them up. Frontmatter always wins;
   // git applies to filesystem entries, other sources supply dates on the entry.
   const lastModified = resolveLastModifiedConfig(config.lastModified);
+  const lastModifiedWarnings: Diagnostic[] = [];
   if (lastModified.enabled && lastModified.source === "git") {
     const fsPaths = pages
       .map((page) => page.sourcePath)
@@ -310,6 +312,14 @@ export const scanProject = async (
         page.lastModified = gitTimes.get(page.sourcePath);
       }
     }
+    // A shallow CI clone (Vercel, actions/checkout) silently drops most dates;
+    // surface that instead of letting production diverge from local builds.
+    const undated = pages.filter(
+      (page) => page.sourcePath && !page.lastModified
+    ).length;
+    lastModifiedWarnings.push(
+      ...lastModifiedShallowWarning(context.root, undated)
+    );
   }
 
   const graph = buildContentGraph(pages, {
@@ -339,6 +349,7 @@ export const scanProject = async (
       ...graph.diagnostics,
       ...i18nWarnings,
       ...versionWarnings,
+      ...lastModifiedWarnings,
     ],
     droppedPages,
     graph,

package/src/core/schema.ts

@@ -623,7 +623,7 @@ const themeConfigSchema = z.strictObject({
   fonts: z
     .strictObject({
       body: fontValueSchema.default("inter"),
-      display: fontValueSchema.default("inter-tight"),
+      display: fontValueSchema.default("inter"),
       mono: fontValueSchema.default("ibm-plex-mono"),
     })
     .prefault({}),