blume 1.3.1 → 1.4.0

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;