blume 1.3.0 → 1.4.0

package/src/components/layout/Logo.astro

@@ -36,7 +36,7 @@ const brandText = logo?.text ?? site.title;
     logoSvg && (
       <span
         aria-hidden="true"
-        class="inline-flex h-5 items-center [&>svg]:h-5 [&>svg]:w-auto"
+        class="inline-flex h-5 shrink-0 items-center [&>svg]:h-5 [&>svg]:w-auto"
         set:html={logoSvg}
       />
     )
@@ -47,7 +47,7 @@ const brandText = logo?.text ?? site.title;
       (logoLight === logoDark ? (
         <img
           alt={logoAlt}
-          class="h-5 w-auto"
+          class="h-5 w-auto shrink-0"
           height={logoLightDimensions?.height}
           src={withBase(logoLight)}
           width={logoLightDimensions?.width}
@@ -56,14 +56,14 @@ const brandText = logo?.text ?? site.title;
         <>
           <img
             alt={logoAlt}
-            class="h-5 w-auto dark:hidden"
+            class="h-5 w-auto shrink-0 dark:hidden"
             height={logoLightDimensions?.height}
             src={withBase(logoLight)}
             width={logoLightDimensions?.width}
           />
           <img
             alt={logoAlt}
-            class="hidden h-5 w-auto dark:block"
+            class="hidden h-5 w-auto shrink-0 dark:block"
             height={logoDarkDimensions?.height}
             src={withBase(logoDark)}
             width={logoDarkDimensions?.width}

package/src/components/layout/PageActions.astro

@@ -44,14 +44,19 @@ const LOGOS: Record<string, string> = {
   v0: '<svg class="size-4 shrink-0" fill="currentColor" viewBox="0 0 147 70" xmlns="http://www.w3.org/2000/svg"><path d="M56 50.2031V14H70V60.1562C70 65.5928 65.5928 70 60.1562 70C57.5605 70 54.9982 68.9992 53.1562 67.1573L0 14H19.7969L56 50.2031Z"/><path d="M147 56H133V23.9531L100.953 56H133V70H96.6875C85.8144 70 77 61.1856 77 50.3125V14H91V46.1562L123.156 14H91V0H127.312C138.186 0 147 8.81439 147 19.6875V56Z"/></svg>',
 };
 
+// Brand names stay verbatim; the surrounding "Open in" phrase localizes via
+// the `actions.openIn` template.
 const PROVIDERS = [
-  { key: "v0", label: "Open in v0" },
-  { key: "chatgpt", label: "Open in ChatGPT" },
-  { key: "claude", label: "Open in Claude" },
-  { key: "t3", label: "Open in T3 Chat" },
-  { key: "scira", label: "Open in Scira" },
-  { key: "cursor", label: "Open in Cursor" },
-];
+  { key: "v0", name: "v0" },
+  { key: "chatgpt", name: "ChatGPT" },
+  { key: "claude", name: "Claude" },
+  { key: "t3", name: "T3 Chat" },
+  { key: "scira", name: "Scira" },
+  { key: "cursor", name: "Cursor" },
+].map((provider) => ({
+  ...provider,
+  label: a.openIn.replace("{name}", provider.name),
+}));
 
 // Top-level actions match the ToC links: flat, no background/padding, color
 // shift on hover only.

package/src/components/layout/Search.astro

@@ -2,7 +2,7 @@
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { Navigation } from "../../core/types.ts";
-import { resolveIcon } from "../../theme/icons.ts";
+import { resolvePopularIconMarkup } from "../../search/popular-icon.ts";
 import Icon from "../Icon.astro";
 import { flattenPages } from "./nav-utils.ts";
 
@@ -28,23 +28,15 @@ const { askEnabled = false, navigation, popularPages, strings, locale } =
 // default, matching the pattern PageActions uses for its own dictionary.
 const s = { ...EN_UI.search, ...strings };
 
-// Icons resolve to inline SVG here (`theme/icons.ts` is a server-only module —
-// far too large to ship to the browser), so the island gets ready-to-render
-// markup rather than a name it can't resolve. Same approach as AskAI.astro.
-// A name outside the set falls through to the island's own file glyph.
-const iconSvg = (name: string | undefined): string | undefined => {
-  const resolved = name ? resolveIcon(name) : null;
-  return resolved
-    ? `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="${resolved.viewBox}" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${resolved.body}</svg>`
-    : undefined;
-};
-
-// Pages shown in the empty state, before the user has typed anything. Only
-// curated entries carry an icon; sidebar-derived rows keep the file glyph.
+// Resolve popular icons to markup here (icon set is server-only). Unknown
+// names fall through to the island's file glyph.
 const popular =
   popularPages && popularPages.length > 0
     ? popularPages.map((page) => ({
-        icon: iconSvg(page.icon),
+        icon: resolvePopularIconMarkup(
+          page.icon,
+          import.meta.env.BASE_URL ?? "/"
+        ),
         label: page.label,
         route: page.route,
       }))
@@ -68,15 +60,18 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   data-i18n-results={s.results}
   data-locale={locale || undefined}
 >
+  {/* The label and shortcut hint wait until `lg`: below it the hamburger and
+      inline tab bar share the header row, and a full-width search field would
+      press into the language switcher. */}
   <button
     aria-label={s.button}
-    class="inline-flex h-9 cursor-pointer items-center gap-2 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground sm:min-w-48"
+    class="inline-flex h-9 cursor-pointer items-center gap-2 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground lg:min-w-48"
     data-blume-search-open
     type="button"
   >
     <Icon name="search" size={16} />
-    <span class="flex-1 text-start max-sm:hidden">{s.button}</span>
-    <kbd class="font-mono text-[0.7rem] max-sm:hidden" data-blume-search-kbd
+    <span class="flex-1 text-start max-lg:hidden">{s.button}</span>
+    <kbd class="font-mono text-[0.7rem] max-lg:hidden" data-blume-search-kbd
       >⌘K</kbd
     >
   </button>
@@ -626,8 +621,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         const href = prefixBase(import.meta.env.BASE_URL, url);
         el.href = href;
         el.className = ROW_CLASS;
-        // `icon` is server-resolved markup from the bundled icon set, not
-        // author HTML — the label still goes through `escapeHtml`.
+        // `icon` is server-resolved markup (built-in Lucide, `<img>`, or
+        // config-authored inline SVG) — the label still goes through `escapeHtml`.
         el.innerHTML = `
           <span class="mt-0.5 shrink-0 text-muted-foreground">${icon ?? svg("file")}</span>
           <span class="flex-1">

package/src/components/layout/search/orama.ts

@@ -23,7 +23,9 @@ export const createSearch = async (opts: {
   const db = await buildOramaIndex(documents, opts.locale);
 
   return async (query, options) => {
-    const docs = await queryOramaIndex(db, query, RESULT_POOL, options?.locale);
+    const docs = await queryOramaIndex(db, query, RESULT_POOL, {
+      locale: options?.locale,
+    });
     return buildResult(docs as IndexedDocument[], query, options?.section);
   };
 };

package/src/core/base-path.ts

@@ -28,6 +28,15 @@ export const normalizeBasePath = (input?: string): string => {
   return trimmed === "" ? "" : `/${trimmed}`;
 };
 
+/**
+ * Normalize a served path for comparison: drop the trailing slash (Astro serves
+ * `/docs` and `/docs/` as the same page) and collapse an empty path to `/`.
+ */
+export const normalizePath = (path: string): string => {
+  const trimmed = path.replace(/\/+$/u, "");
+  return trimmed === "" ? "/" : trimmed;
+};
+
 /**
  * Whether a link target is a root-relative internal path (`/x`) — the only
  * shape a base path applies to. Protocol-relative (`//host`), absolute URLs,

package/src/core/config-input.ts

@@ -269,20 +269,88 @@ export interface ContentConfig {
    * Releases, Sanity, Notion, or a custom `ContentSource`.
    */
   sources?: ContentSourceInput[];
+  /**
+   * Per-type content definitions, keyed by the frontmatter `type` they apply
+   * to (including `defaultType`, for pages that set none):
+   *
+   * ```ts
+   * import { z } from "zod";
+   *
+   * content: {
+   *   types: {
+   *     rfc: {
+   *       frontmatter: {
+   *         domain: z.string(),
+   *         status: z.enum(["draft", "enforced"]),
+   *       },
+   *     },
+   *   },
+   * },
+   * ```
+   */
+  types?: Record<string, ContentTypeConfig>;
+}
+
+/**
+ * A per-type content definition: configuration that applies only to pages
+ * whose resolved frontmatter `type` matches the map key.
+ */
+export interface ContentTypeConfig {
+  /**
+   * Custom frontmatter keys whose values become filterable facets for pages
+   * of this type. Faceted values ride along on search documents
+   * (`blume-search.json` and the MCP index), and the MCP `search_docs` and
+   * `list_pages` tools accept a `filters` input matching against them:
+   *
+   * ```ts
+   * content: {
+   *   types: {
+   *     rfc: {
+   *       facets: ["domain", "status"],
+   *       frontmatter: { domain: z.string(), status: z.string() },
+   *     },
+   *   },
+   * },
+   * ```
+   *
+   * Each name must be a custom key declared for the type — in its
+   * `frontmatter` map or the site-wide `frontmatter.extend`. String values
+   * facet as-is; numbers and booleans are stringified; anything else
+   * (objects, arrays, transformed dates) does not facet.
+   */
+  facets?: string[];
+  /**
+   * Custom frontmatter keys for pages of this type, layered on top of the
+   * site-wide `frontmatter.extend` (a key can be declared in one or the
+   * other, not both). Schemas follow the same rules as `extend`: any
+   * Standard Schema library works, every declared key is validated on every
+   * page of the type — absent ones included — so a required schema enforces
+   * the key type-wide (mark it `.optional()` to validate only when present),
+   * and validated values land on the page record's `custom` field. Built-in
+   * frontmatter fields cannot be redeclared.
+   */
+  frontmatter?: Record<string, StandardSchema>;
 }
 
 // ---------------------------------------------------------------------------
 // Navigation
 // ---------------------------------------------------------------------------
 
+/**
+ * A header label, optionally per locale: a plain string, or a map of locale
+ * code to label (`{ en: "Docs", ja: "ドキュメント" }`). The active locale's
+ * entry wins, then the default locale's, then the map's first entry.
+ */
+export type LocalizableLabel = string | Record<string, string>;
+
 /** A single item inside a header tab's dropdown. */
 export interface NavTabItem {
   /** Secondary line under the label. */
   description?: string;
   /** Lucide icon name shown beside the label. */
   icon?: string;
-  /** Item label. */
-  label: string;
+  /** Item label, optionally per locale. */
+  label: LocalizableLabel;
   /** Route the item links to. */
   path: string;
   /** Short tag/pill (e.g. `New`, `Beta`). */
@@ -304,8 +372,8 @@ export interface NavTab {
   icon?: string;
   /** Dropdown items; omit for a plain link tab. */
   items?: NavTabItem[];
-  /** Tab label. */
-  label: string;
+  /** Tab label, optionally per locale. */
+  label: LocalizableLabel;
   /** Route the tab links to. */
   path: string;
 }
@@ -512,7 +580,10 @@ export interface MixedbreadSearch {
 export interface SearchPopularLink {
   /** Internal route or external URL. */
   href: string;
-  /** Built-in icon name shown beside the label; defaults to the file glyph. */
+  /**
+   * Icon shown beside the label — a built-in name, image path/URL, or inline
+   * SVG (same as nav icons). Defaults to the file glyph.
+   */
   icon?: string;
   /** Link label shown in the dialog. */
   label: string;
@@ -728,6 +799,12 @@ export interface LocaleConfigInput {
   dir?: "ltr" | "rtl";
   /** Human-readable name shown in the switcher. */
   label: string;
+  /**
+   * Freeform style guidance for `blume translate`, e.g. "Brazilian
+   * Portuguese, informal você". Pins register and dialect from the first
+   * translation and wins over an existing translation's style on reruns.
+   */
+  style?: string;
 }
 
 /**
@@ -1145,7 +1222,8 @@ export interface FrontmatterConfig {
    * 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.
+   * redeclared. To scope a key to one content type instead, declare it under
+   * `content.types.<type>.frontmatter`.
    */
   extend?: Record<string, StandardSchema>;
 }

package/src/core/graph.ts

@@ -4,6 +4,7 @@ import { validateNavIcons, validateNavStructure } from "./nav-diagnostics.ts";
 import { buildNavigation } from "./navigation.ts";
 import type {
   FolderMeta,
+  LocalizableLabel,
   ResolvedConfig,
   ResolvedI18nConfig,
 } from "./schema.ts";
@@ -11,6 +12,7 @@ import type {
   ContentGraph,
   Diagnostic,
   Navigation,
+  NavTab,
   PageRecord,
 } from "./types.ts";
 
@@ -79,6 +81,42 @@ const localePagesFor = (
   return [...real, ...filled];
 };
 
+/**
+ * Resolve a possibly-per-locale header label to the string a locale renders:
+ * the active locale's entry, else the default locale's, else the map's first
+ * entry (which is also what a single-locale site gets).
+ */
+const resolveLabel = (
+  label: LocalizableLabel,
+  locale: string,
+  defaultLocale?: string
+): string => {
+  if (typeof label === "string") {
+    return label;
+  }
+  return (
+    label[locale] ??
+    (defaultLocale === undefined ? undefined : label[defaultLocale]) ??
+    Object.values(label)[0] ??
+    ""
+  );
+};
+
+/** Resolve every localizable label in the configured tabs for one locale. */
+const resolveTabLabels = (
+  tabs: BuildContentGraphOptions["navigation"]["tabs"],
+  locale: string,
+  defaultLocale?: string
+): NavTab[] =>
+  (tabs ?? []).map((tab) => ({
+    ...tab,
+    items: tab.items?.map((item) => ({
+      ...item,
+      label: resolveLabel(item.label, locale, defaultLocale),
+    })),
+    label: resolveLabel(tab.label, locale, defaultLocale),
+  }));
+
 /** Build one locale's navigation tree from its own pages and folder meta. */
 const buildLocaleNavigation = (
   code: string,
@@ -95,7 +133,11 @@ const buildLocaleNavigation = (
   // selector's items intentionally target specific locales.
   const localizePath = (path: string): string =>
     path.startsWith("/") ? localizeRoute(path, code, i18n) : path;
-  const tabs = options.navigation.tabs?.map((tab) => ({
+  const tabs = resolveTabLabels(
+    options.navigation.tabs,
+    code,
+    i18n.defaultLocale
+  ).map((tab) => ({
     ...tab,
     ...(tab.href ? { href: localizePath(tab.href) } : {}),
     items: tab.items?.map((item) => ({
@@ -220,7 +262,9 @@ export const buildContentGraph = (
           selectors: options.navigation.selectors,
           sharedFolderMeta: options.sharedFolderMeta,
           sidebar: options.navigation.sidebar.items,
-          tabs: options.navigation.tabs,
+          // No locale to prefer: a per-locale label map resolves to its first
+          // entry on a single-locale site.
+          tabs: resolveTabLabels(options.navigation.tabs, ""),
         }),
         navigationByLocale: {} as Record<string, Navigation>,
       };

package/src/core/i18n-ui.ts

@@ -28,6 +28,8 @@ const uiStringsObject = z.object({
       exportEpub: z.string().default("Export to EPUB"),
       exportPdf: z.string().default("Export to PDF"),
       generating: z.string().default("Generating…"),
+      // `{name}` is replaced with the provider's brand name at render time.
+      openIn: z.string().default("Open in {name}"),
       openInChat: z.string().default("Open in chat"),
       scrollToTop: z.string().default("Scroll to top"),
     })

package/src/core/i18n.ts

@@ -148,6 +148,37 @@ export const localePlacement = (
   return { locales: [locale], navPath: rest.join("/") };
 };
 
+/**
+ * The inverse of {@link localePlacement}: where a default-locale file's
+ * translation into `locale` lives, by parser:
+ * - `dir`: a leading locale directory (`guides/x.mdx` → `fr/guides/x.mdx`)
+ * - `dot`: a filename suffix (`guides/x.mdx` → `guides/x.fr.mdx`)
+ *
+ * Under `dot`, a source authored with an explicit default-locale suffix
+ * (`x.en.mdx`) swaps it for the target's (`x.fr.mdx`) — same case-insensitive
+ * last-dot-inside-filename logic as `localePlacement`, so both spellings of a
+ * default-locale file resolve to one canonical target.
+ */
+export const localeTargetPath = (
+  rel: string,
+  ext: string,
+  locale: string,
+  i18n: ResolvedI18nConfig
+): string => {
+  if (i18n.parser === "dot") {
+    let base = rel.slice(0, rel.length - ext.length);
+    const lastDot = base.lastIndexOf(".");
+    if (lastDot > base.lastIndexOf("/")) {
+      const suffix = base.slice(lastDot + 1).toLowerCase();
+      if (i18n.locales.some((entry) => entry.code.toLowerCase() === suffix)) {
+        base = base.slice(0, lastDot);
+      }
+    }
+    return `${base}.${locale}${ext}`;
+  }
+  return `${locale}/${rel}`;
+};
+
 /**
  * Warn about top-level content folders that look like a locale (a code Blume
  * recognizes) but aren't declared in `i18n.locales`. Without this they're

package/src/core/nav-diagnostics.ts

@@ -1,3 +1,4 @@
+import { isAssetIcon } from "../theme/icon-kind.ts";
 import { hasIcon } from "../theme/icons.ts";
 import type { Diagnostic, NavNode, Navigation, PageRecord } from "./types.ts";
 
@@ -8,12 +9,8 @@ import type { Diagnostic, NavNode, Navigation, PageRecord } from "./types.ts";
  * covers every source (config, folder meta, frontmatter) at once.
  */
 
-const IMAGE_ICON =
-  /^(?:https?:\/\/|data:image\/|\/|\.{1,2}\/)|\.(?:avif|gif|jpe?g|png|svg|webp)$/iu;
-
-/** Whether an icon string is an asset (image/URL/inline SVG), not a set name. */
-const isAssetIcon = (value: string): boolean =>
-  value.startsWith("<") || IMAGE_ICON.test(value);
+const ICON_SHAPE_HINT =
+  "Use a built-in icon name, an image path/URL, or inline SVG markup.";
 
 /** Flatten a sidebar tree to every node, descending into groups. */
 const flattenNodes = (nodes: NavNode[]): NavNode[] =>
@@ -66,9 +63,14 @@ const unknownIconDiagnostics = (
       continue;
     }
     seen.add(icon);
+    // Markup that isn't a complete <svg> element (an <img> tag, a truncated
+    // svg) is a shape problem, not a set-name typo — say so.
+    const message = icon.trimStart().startsWith("<")
+      ? `Icon markup "${icon}" (${where}) isn't a complete inline <svg> element, so it won't render.`
+      : `Unknown icon "${icon}" (${where}) — it isn't in Blume's icon set.`;
     diagnostics.push({
       code: "BLUME_UNKNOWN_ICON",
-      message: `Unknown icon "${icon}" (${where}) — it isn't in Blume's icon set.`,
+      message,
       severity: "warning",
       suggestion,
     });
@@ -78,16 +80,11 @@ const unknownIconDiagnostics = (
 
 /** Warn about icon names that aren't in Blume's set (skipping image/SVG icons). */
 export const validateNavIcons = (navigation: Navigation): Diagnostic[] =>
-  unknownIconDiagnostics(
-    collectIcons(navigation),
-    "Use a built-in icon name, an image path/URL, or inline SVG markup."
-  );
+  unknownIconDiagnostics(collectIcons(navigation), ICON_SHAPE_HINT);
 
 /**
- * Warn about unknown icons on curated `search.popular` links. Separate from
- * {@link validateNavIcons} because these live under `search`, not the built
- * navigation — and unlike nav icons they resolve in a *client* island, so only
- * set names work (an image/SVG icon quietly falls back to the file glyph).
+ * Warn about unknown icons on curated `search.popular` links. Same accepted
+ * input shapes as nav icons — resolved to markup on the server for the island.
  */
 export const validateSearchPopularIcons = (
   popular: { icon?: string; label: string }[]
@@ -97,25 +94,7 @@ export const validateSearchPopularIcons = (
       ? [{ icon: link.icon, where: `popular link "${link.label}"` }]
       : []
   );
-  // Asset icons are valid in the nav, so the shared helper skips them — but
-  // here they are exactly the silent failure this validator exists to catch.
-  const diagnostics: Diagnostic[] = [];
-  const seen = new Set<string>();
-  for (const { icon, where } of icons) {
-    if (isAssetIcon(icon) && !seen.has(icon)) {
-      seen.add(icon);
-      diagnostics.push({
-        code: "BLUME_UNKNOWN_ICON",
-        message: `Icon "${icon}" (${where}) is an image or inline SVG — popular links render in the client search island, where only built-in icon names resolve, so it falls back to the file glyph.`,
-        severity: "warning",
-        suggestion: "Use a built-in icon name.",
-      });
-    }
-  }
-  return [
-    ...diagnostics,
-    ...unknownIconDiagnostics(icons, "Use a built-in icon name."),
-  ];
+  return unknownIconDiagnostics(icons, ICON_SHAPE_HINT);
 };
 
 /** Whether an internal path resolves to a page or a section that has pages. */

package/src/core/project-graph.ts

@@ -143,12 +143,22 @@ const normalizeLoadedEntries = (
   loaded: ({ source: ContentSource } & SourceLoadResult)[],
   config: ResolvedConfig
 ): { pages: PageRecord[]; diagnostics: Diagnostic[]; droppedPages: number } => {
-  // Only thread `frontmatter.extend` through when a project opts in, so the
-  // known-key split in `normalizeEntry` stays off the default path.
+  // Only thread `frontmatter.extend` / `content.types` through when a project
+  // opts in, so the known-key split in `normalizeEntry` stays off the default
+  // path.
   const frontmatterExtend =
     Object.keys(config.frontmatter.extend).length > 0
       ? config.frontmatter.extend
       : undefined;
+  const declaredTypes = Object.entries(config.content.types).filter(
+    ([, type]) => Object.keys(type.frontmatter).length > 0
+  );
+  const typeFrontmatter =
+    declaredTypes.length > 0
+      ? Object.fromEntries(
+          declaredTypes.map(([name, type]) => [name, type.frontmatter])
+        )
+      : undefined;
 
   const pages: PageRecord[] = [];
   const allDiagnostics: Diagnostic[] = [];
@@ -166,6 +176,7 @@ const normalizeLoadedEntries = (
           prefix: source.prefix,
           staged: source.staged,
         },
+        typeFrontmatter,
       });
       if (normalized.pages.length === 0 && normalized.diagnostics.length > 0) {
         droppedPages += 1;