blume 1.0.3 → 1.1.0

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

@@ -2,6 +2,7 @@ import type { ComponentMarkdown } from "../ai/component-markdown.ts";
 import type { FontSlug } from "../theme/fonts.ts";
 import type { OpenApiSource, SearchProvider, SidebarDisplay, SidebarItemConfig } from "./schema.ts";
 import type { ContentSource } from "./sources/types.ts";
+import type { StandardSchema } from "./standard-schema.ts";
 /**
  * The public, hand-documented authoring type for `blume.config.ts`.
  *
@@ -382,6 +383,15 @@ export interface TypesenseSearch {
 export interface MixedbreadSearch {
     storeId: string;
 }
+/** A curated link for the search dialog empty state. */
+export interface SearchPopularLink {
+    /** Internal route or external URL. */
+    href: string;
+    /** Built-in icon name shown beside the label; defaults to the file glyph. */
+    icon?: string;
+    /** Link label shown in the dialog. */
+    label: string;
+}
 /**
  * Search backend. The default `orama` builds a local index at build time (and
  * runs in dev); hosted providers need their credential block below. `none`
@@ -399,6 +409,11 @@ export interface SearchConfig {
     mixedbread?: MixedbreadSearch;
     /** Orama Cloud credentials (required when `provider` is `orama-cloud`). */
     oramaCloud?: OramaCloudSearch;
+    /**
+     * Curated links for the Cmd+K empty state. When omitted or empty, the first
+     * sidebar pages are shown instead.
+     */
+    popular?: SearchPopularLink[];
     /** Which backend powers search. Defaults to `orama`. */
     provider?: SearchProvider;
     /** Typesense credentials (required when `provider` is `typesense`). */
@@ -602,6 +617,44 @@ export interface RssConfig {
     /** Content types that each get a feed at `/<type>/rss.xml`. Defaults to blog + changelog. */
     types?: string[];
 }
+/** Colors used by generated Open Graph cards. Any CSS color — hex, `oklch(…)`, `rgb(…)`, named. */
+export interface OgPaletteConfig {
+    /** Fallback mark color. Defaults to the light theme accent. */
+    accent?: string;
+    /** Card background. */
+    background?: string;
+    /** Footer divider. */
+    border?: string;
+    /** Headline and `currentColor` logo color. */
+    foreground?: string;
+    /** Description and footer text. */
+    muted?: string;
+}
+/** Per-page Open Graph image generation. */
+export interface OgConfig {
+    /**
+     * Generate an OG image per page. Defaults to on once a deployment `site`
+     * URL is known and off otherwise (`og:image` must be absolute). An explicit
+     * value always wins.
+     */
+    enabled?: boolean;
+    /**
+     * Google Font families for the generated card, extending Takumi's Latin-only
+     * default so non-Latin titles (CJK, and so on) render instead of tofu.
+     * Fetched from Google Fonts at build. A bare string loads the family's
+     * default weights; the object form pins weights (`700`, `[400, 700]`, or a
+     * `"100..900"` variable range) and styles.
+     */
+    fonts?: (string | {
+        name: string;
+        style?: "normal" | "italic" | ("normal" | "italic")[];
+        weight?: number | number[] | string;
+    })[];
+    /** Local SVG used in the generated card instead of the site logo. */
+    logo?: string;
+    /** Optional generated-card colors. */
+    palette?: OgPaletteConfig;
+}
 /** Discoverability: OG images, feeds, sitemap, robots, and structured data. */
 export interface SeoConfig {
     /**
@@ -612,14 +665,7 @@ export interface SeoConfig {
     /** robots.txt `Content-Signal` usage declaration. Defaults to `true`. */
     contentSignals?: ContentSignalsConfig;
     /** Per-page Open Graph image generation. */
-    og?: {
-        /**
-         * Generate an OG image per page. Defaults to on once a deployment `site`
-         * URL is known and off otherwise (`og:image` must be absolute). An explicit
-         * value always wins.
-         */
-        enabled?: boolean;
-    };
+    og?: OgConfig;
     /** Generate robots.txt (with a Sitemap reference when available). Defaults to `true`. */
     robots?: boolean;
     /** RSS/Atom feeds. */
@@ -761,6 +807,37 @@ export type ExportConfig = boolean | {
     /** Offer PDF export (via print). Defaults to `false`. */
     pdf?: boolean;
 };
+/**
+ * Opt-in custom frontmatter keys. Page frontmatter is strictly validated —
+ * an unknown key fails the build so typos are caught — and `extend` carves
+ * out project-specific keys from that rule, each validated by a schema you
+ * supply.
+ */
+export interface FrontmatterConfig {
+    /**
+     * Extra frontmatter keys pages may carry, mapped to their validation
+     * schemas — any library implementing Standard Schema works (Zod — the
+     * version your project installs, 3.24+ or 4 — Valibot, ArkType):
+     *
+     * ```ts
+     * import { z } from "zod";
+     *
+     * frontmatter: {
+     *   extend: {
+     *     owner: z.string(),
+     *     reviewedAt: z.coerce.date().optional(),
+     *   },
+     * },
+     * ```
+     *
+     * Every declared key is validated on every page — absent ones included —
+     * so a required schema enforces the key site-wide; mark it `.optional()`
+     * to validate only when present. Validated values are preserved on each
+     * page record's `custom` field. Built-in frontmatter fields cannot be
+     * redeclared.
+     */
+    extend?: Record<string, StandardSchema>;
+}
 /**
  * "Last updated" timestamps. `false` (default) disables them; `true` derives
  * each date from git history; the object form selects the source. A page's
@@ -824,6 +901,8 @@ export interface BlumeConfig {
     export?: ExportConfig;
     /** Show the per-page "Was this helpful?" widget. Defaults to `true`. */
     feedback?: boolean;
+    /** Opt-in custom frontmatter keys, validated by schemas you supply. */
+    frontmatter?: FrontmatterConfig;
     /** Source repository (Edit-this-page links and the header repo link). */
     github?: GithubConfig;
     /** Internationalization (opt-in multi-locale). */

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

@@ -1,3 +1,4 @@
+import type { OgFont } from "../og/card.ts";
 import type { UIStrings } from "./i18n-ui.ts";
 import type { ResolvedConfig, SearchProvider } from "./schema.ts";
 import type { Navigation, RouteAlternate } from "./types.ts";
@@ -13,6 +14,16 @@ export interface BlumeLogo {
     svg?: string;
     light?: string;
     dark?: string;
+    dimensions?: {
+        dark?: {
+            height: number;
+            width: number;
+        };
+        light?: {
+            height: number;
+            width: number;
+        };
+    };
     alt: string;
     href: string;
     /** Wordmark text beside the mark; `undefined` falls back to the site title. */
@@ -108,11 +119,21 @@ export interface BlumeDataConfig {
     /** Open Graph image generation. */
     og: {
         enabled: boolean;
+        /** Extra Google Font family specs for the card renderer, fetched at build. */
+        fonts?: OgFont[];
+        logo?: string;
+        palette?: ResolvedConfig["seo"]["og"]["palette"];
     };
     /** Repository URL for header/edit links, or `null`. */
     repoUrl: string | null;
     search: {
         enabled: boolean;
+        /** Resolved empty-state links; empty when unset (Search falls back to sidebar). */
+        popular: {
+            icon?: string;
+            label: string;
+            route: string;
+        }[];
         provider: SearchProvider;
     };
     /** Deployment site URL, or `null` when none is configured/detected. */

package/dist/types/core/deployment-env.d.ts

@@ -1,4 +1,10 @@
 import type { ResolvedConfig } from "./schema.ts";
+/**
+ * Adapters whose `deployment.site` arrives from platform env vars at deploy
+ * time. Consumers (e.g. the audit) use this to tell "site is missing" apart
+ * from "site is missing *here*, but the platform will set it".
+ */
+export declare const SITE_INFERRING_ADAPTERS: ReadonlySet<string>;
 /**
  * Fill in `deployment.adapter` and `deployment.site` from platform env vars
  * (Vercel, Netlify, Cloudflare Pages) when the user hasn't set them. Explicit

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

@@ -10,6 +10,29 @@ export declare const createDiagnostic: (diagnostic: Diagnostic) => Diagnostic;
 export declare const resolveDocsUrl: (code: string) => string | undefined;
 /** Fill in `docsUrl` from the code map where a diagnostic doesn't set its own. */
 export declare const enrichDiagnostic: (diagnostic: Diagnostic) => Diagnostic;
+/**
+ * Locate a front matter key in a content file, e.g. `["seo", "description"]` in
+ * `docs/api.mdx`. Scoped to the front matter block so a `title:` written in the
+ * page body can't be mistaken for the front matter key of the same name; returns
+ * undefined when the file has no front matter or the key isn't set (a missing
+ * key has no line to point at — callers anchor to the file instead).
+ */
+export declare const locateFrontmatterKey: (source: string, path: readonly (string | number)[]) => {
+    column: number;
+    line: number;
+} | undefined;
+/**
+ * Convert generic validation issues (message + path, the shape shared by Zod
+ * and Standard Schema issues) into Blume diagnostics, anchored to a file.
+ */
+export declare const diagnosticsFromIssues: (issues: readonly {
+    message: string;
+    path: readonly (string | number)[];
+}[], options: {
+    code: string;
+    file?: string;
+    source?: string;
+}) => Diagnostic[];
 /** Convert a ZodError into Blume diagnostics, anchored to a file. */
 export declare const diagnosticsFromZod: (error: ZodError, options: {
     code: string;