blume 0.4.0 → 0.5.1

package/src/core/schema.ts

@@ -69,9 +69,30 @@ const changelogMetaSchema = z
   })
   .strict();
 
+/**
+ * A post author: a bare name/handle, or an object with a name plus optional
+ * avatar/URL. The object is passthrough so richer author metadata (social
+ * handles, roles) survives untouched — Blume doesn't render authors yet, so
+ * this exists to preserve the field (common on blog/changelog pages) rather
+ * than have a strict scan reject it.
+ */
+const authorSchema = z.union([
+  z.string(),
+  z
+    .object({
+      avatar: z.string().optional(),
+      image: z.string().optional(),
+      name: z.string(),
+      url: z.string().optional(),
+    })
+    .passthrough(),
+]);
+
 /** Frontmatter accepted on any content page. */
 const pageMetaBaseSchema = z
   .object({
+    /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
+    authors: z.union([authorSchema, z.array(authorSchema)]).optional(),
     changelog: changelogMetaSchema.optional(),
     /** Publish date for feed-backed content like blog/changelog. */
     date: dateSchema.optional(),
@@ -462,13 +483,6 @@ const sidebarItemSchema: z.ZodType<SidebarItemConfig> = z.lazy(() =>
   ])
 );
 
-const sidebarVariantSchema = z
-  .object({
-    items: z.array(sidebarItemSchema).default([]),
-    path: z.string(),
-  })
-  .strict();
-
 const variablesConfigSchema = z
   .record(z.string().regex(/^[A-Za-z0-9-]+$/u), z.string())
   .default({});
@@ -645,7 +659,6 @@ const navigationConfigSchema = z
     selectors: z.array(navSelectorSchema).default([]),
     /** Explicit sidebar override; when omitted the sidebar is generated. */
     sidebar: z.array(sidebarItemSchema).optional(),
-    sidebarVariants: z.array(sidebarVariantSchema).default([]),
     tabs: z.array(navTabSchema).optional(),
   })
   .strict();
@@ -903,8 +916,8 @@ const markdownConfigSchema = z
   .strict();
 
 /**
- * A single spec rendered by the API reference (Scalar). `spec` is a local path
- * or an `http(s)` URL; Scalar auto-detects OpenAPI vs AsyncAPI documents.
+ * A single spec rendered by the API reference. `spec` is a local path or an
+ * `http(s)` URL (OpenAPI for the Blume renderer; OpenAPI or AsyncAPI for Scalar).
  */
 const openapiSourceSchema = z
   .object({
@@ -920,20 +933,28 @@ const openapiSourceSchema = z
 export type OpenApiSource = z.infer<typeof openapiSourceSchema>;
 
 /**
- * OpenAPI reference, delegated wholesale to Scalar (`@scalar/astro`). The
- * reference is a self-contained embed on its own route — it does not weave into
- * Blume's sidebar, search, or llms. Set `enabled: true` to opt in.
+ * OpenAPI reference. By default (`renderer: "blume"`) Blume parses the spec with
+ * Scalar's parser and renders its own UI: one real page per operation, grouped
+ * by tag in the sidebar and included in site search, llms.txt, and OG. Set
+ * `renderer: "scalar"` to fall back to the embedded Scalar SPA (a single
+ * self-contained route that doesn't weave into the sidebar or search).
  */
 const openapiConfigSchema = z
   .object({
+    /** Code-sample languages shown per operation (Blume renderer). */
+    codeSamples: z.array(z.string()).default(["curl", "js", "python"]),
     enabled: z.boolean().default(false),
+    /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
+    expandSchemas: z.boolean().default(false),
+    /** Who renders the reference: Blume's own UI, or the embedded Scalar SPA. */
+    renderer: z.enum(["blume", "scalar"]).default("blume"),
     /** Where the reference mounts. */
     route: z.string().default("/reference"),
     /** One or more specs; each renders on its own route by default. */
     sources: z.array(openapiSourceSchema).default([]),
     /** Shorthand for a single source: `sources: [{ spec }]`. */
     spec: z.string().optional(),
-    /** Scalar theme name; defaults to a Blume-derived accent override. */
+    /** Scalar theme name (Scalar renderer only). */
     theme: z.string().optional(),
   })
   .strict();
@@ -980,6 +1001,17 @@ const tocConfigSchema = z
     };
   });
 
+/**
+ * Which icon library bare `icon` names resolve against (mirrors Mintlify's
+ * `icons.library`). Names can always opt into a specific set with an explicit
+ * `prefix:name` (`lucide:rocket`, `fa6-brands:github`) regardless of this.
+ */
+const iconsConfigSchema = z
+  .object({
+    library: z.enum(["lucide", "fontawesome", "tabler"]).default("lucide"),
+  })
+  .strict();
+
 export const blumeConfigSchema = z
   .object({
     ai: aiConfigSchema.default({}),
@@ -1008,6 +1040,7 @@ export const blumeConfigSchema = z
     feedback: z.boolean().default(true),
     github: githubConfigSchema.optional(),
     i18n: i18nConfigSchema.optional(),
+    icons: iconsConfigSchema.default({}),
     lastModified: lastModifiedConfigSchema.default(false),
     logo: logoConfigSchema.optional(),
     markdown: markdownConfigSchema.default({}),

package/src/core/sources/mintlify.ts

@@ -102,7 +102,7 @@ export const mintlifySource = (
         ? [
             {
               code: "BLUME_MINTLIFY_UNSUPPORTED",
-              message: `Mintlify components without a Blume equivalent were left as-is: ${[...unsupported].toSorted().join(", ")}. Use the OpenAPI reference for API parameters.`,
+              message: `Mintlify components without a Blume equivalent were left as-is: ${[...unsupported].toSorted().join(", ")}. Replace them by hand or provide a matching component.`,
               severity: "warning",
             },
           ]

package/src/core/sources/resolve.ts

@@ -1,5 +1,7 @@
 import { join } from "pathe";
 
+import { blumeReferences } from "../../openapi/references.ts";
+import { openApiSource } from "../../openapi/source.ts";
 import type { ContentSourceConfig, ResolvedConfig } from "../schema.ts";
 import type { ProjectContext } from "../types.ts";
 import { filesystemSource } from "./filesystem.ts";
@@ -144,12 +146,8 @@ const baseName = (def: ContentSourceConfig): string => {
   return def.prefix ?? def.type;
 };
 
-/**
- * Build the ordered list of content sources for a project. With no
- * `content.sources` configured, the top-level `root`/`include`/`exclude` desugar
- * to a single implicit filesystem source, so existing projects are untouched.
- */
-export const resolveSources = (
+/** The content sources declared by config (implicit filesystem when none). */
+const contentSources = (
   config: ResolvedConfig,
   context: ProjectContext,
   runtime: SourceRuntime
@@ -172,3 +170,27 @@ export const resolveSources = (
     buildSource(def, nameFor(baseName(def)), context, runtime)
   );
 };
+
+/**
+ * Build the ordered list of content sources for a project. With no
+ * `content.sources` configured, the top-level `root`/`include`/`exclude` desugar
+ * to a single implicit filesystem source, so existing projects are untouched.
+ * A Blume-rendered OpenAPI reference contributes an internal staged source that
+ * lowers each operation into a real content page (routing/nav/search/OG).
+ */
+export const resolveSources = (
+  config: ResolvedConfig,
+  context: ProjectContext,
+  runtime: SourceRuntime
+): ContentSource[] => {
+  const sources = contentSources(config, context, runtime);
+
+  const references = blumeReferences(config);
+  if (references.length > 0) {
+    sources.push(
+      openApiSource(references, sourceContext(context, "openapi", runtime))
+    );
+  }
+
+  return sources;
+};

package/src/core/types.ts

@@ -54,6 +54,13 @@ export interface ProjectContext {
   pagesRoot: string | null;
   /** Absolute path to the generated runtime (`<root>/.blume`). */
   outDir: string;
+  /**
+   * Absolute path to the Astro build output. `<root>/dist` normally; for a
+   * relocated runtime (isolated verify build) it lives under the runtime dir so
+   * it never empties the real `dist/`. Optional so hand-built test contexts and
+   * older callers still typecheck; `resolveProjectContext` always sets it.
+   */
+  distDir?: string;
   /** Absolute path to the user `theme.css`, if present. */
   themeFile: string | null;
   /** Absolute path to the user `components.ts`/`.tsx`, if present. */
@@ -173,12 +180,6 @@ export interface NavSelector {
   items: NavSelectorItem[];
 }
 
-/** Sidebar tree used when the current route belongs to a nav partition. */
-export interface NavSidebarVariant {
-  path: string;
-  sidebar: NavNode[];
-}
-
 /** Chrome overrides used when the current route belongs to a nav partition. */
 export interface NavChromeVariant {
   path: string;
@@ -191,7 +192,6 @@ export interface Navigation {
   selectors: NavSelector[];
   chromeVariants: NavChromeVariant[];
   sidebar: NavNode[];
-  sidebarVariants: NavSidebarVariant[];
   /** Repo URL for the header link, or null when hidden (`navigation.repo`). */
   repoUrl?: string | null;
 }

package/src/migrate/mintlify/config.ts

@@ -9,6 +9,7 @@ import type {
   ResolvedConfig,
   SidebarItemConfig,
 } from "../../core/schema.ts";
+import { GOOGLE_FONTS } from "../../theme/fonts.ts";
 
 type JsonObject = Record<string, unknown>;
 type NavigationSelectors = ResolvedConfig["navigation"]["selectors"];
@@ -16,8 +17,6 @@ type NavigationSelectorItem = NavigationSelectors[number]["items"][number];
 type NavigationChromeVariants = NonNullable<
   BlumeConfig["navigation"]
 >["chromeVariants"];
-type NavigationSidebarVariants =
-  ResolvedConfig["navigation"]["sidebarVariants"];
 
 const MINTLIFY_DEFAULT_IGNORES = [
   "**/_*",
@@ -306,18 +305,6 @@ const mintlifyBackgroundDecoration = (
   return undefined;
 };
 
-const sidebarItemPaths = (items: SidebarItemConfig[]): string[] =>
-  items.flatMap((item) => {
-    if (typeof item === "string") {
-      return [tabPathFromRef(item)];
-    }
-    if (item.href) {
-      return [item.href];
-    }
-    const paths = item.root ? [tabPathFromRef(item.root)] : [];
-    return item.items ? [...paths, ...sidebarItemPaths(item.items)] : paths;
-  });
-
 const collapsedFromExpanded = (value: unknown): boolean | undefined => {
   if (value === false) {
     return true;
@@ -438,79 +425,6 @@ const isExternalRoute = (path: string): boolean =>
   path.startsWith("mailto:") ||
   path.startsWith("tel:");
 
-const hasOwnNavigationContent = (item: JsonObject): boolean =>
-  Boolean(asString(item.root)) || childItemsFor(item).length > 0;
-
-const mintlifySidebarVariants = async (
-  spec: JsonObject
-): Promise<NavigationSidebarVariants> => {
-  const navigation = asObject(spec.navigation) ?? {};
-  const global = asObject(navigation.global) ?? {};
-  interface SidebarVariantCandidate {
-    item: unknown;
-    path: string;
-  }
-  const candidates: SidebarVariantCandidate[] = [];
-
-  const addCandidate = (item: unknown): void => {
-    const path = navItemPath(item);
-    if (!path || isExternalRoute(path)) {
-      return;
-    }
-
-    candidates.push({ item, path });
-  };
-
-  for (const item of [
-    ...asArray(navigation.tabs),
-    ...asArray(navigation.anchors),
-    ...asArray(global.anchors),
-  ]) {
-    const object = asObject(item);
-    if (!object) {
-      addCandidate(item);
-      continue;
-    }
-
-    for (const menuItem of asArray(object.menu)) {
-      addCandidate(menuItem);
-    }
-
-    if (hasOwnNavigationContent(object)) {
-      addCandidate(item);
-    }
-  }
-
-  for (const item of [
-    ...asArray(navigation.dropdowns),
-    ...asArray(navigation.products),
-    ...asArray(navigation.versions),
-    ...asArray(navigation.languages),
-  ]) {
-    addCandidate(item);
-  }
-
-  const resolved = await Promise.all(
-    candidates.map(async (candidate) => {
-      const items = await toSidebarItems([candidate.item], {});
-      if (items.length === 0) {
-        return [];
-      }
-      return [candidate.path, ...sidebarItemPaths(items)]
-        .filter((path) => !isExternalRoute(path))
-        .map((path) => ({ items, path }));
-    })
-  );
-  const seen = new Set<string>();
-  return resolved.flat().flatMap((variant) => {
-    if (!variant || seen.has(variant.path)) {
-      return [];
-    }
-    seen.add(variant.path);
-    return [variant];
-  });
-};
-
 const mintlifyTabs = (
   spec: JsonObject
 ): NonNullable<BlumeConfig["navigation"]>["tabs"] => {
@@ -593,24 +507,154 @@ const mintignorePatterns = async (root: string): Promise<string[]> => {
   }
 };
 
-const mintlifyRedirects = (
+// path-to-regexp param (:slug, :slug*, :id?) → Astro dynamic segment.
+// *,+ (repeatable) → spread [...name]; bare/? → single [name]. Name must start
+// with a letter/underscore so URL ports (:8080) and protocols (https:) are left alone.
+const REDIRECT_PARAM = /:(?<name>[A-Za-z_]\w*)(?<modifier>[*+?])?/gu;
+
+const toAstroRedirectPath = (path: string): string =>
+  path.replaceAll(REDIRECT_PARAM, (_match, name: string, modifier?: string) =>
+    modifier === "*" || modifier === "+" ? `[...${name}]` : `[${name}]`
+  );
+
+// A converted path is dynamic once it holds an Astro segment (`[id]`/`[...slug]`
+// from a `:param`). Blume redirects are static path-to-path: a dynamic segment
+// has no matching route, so Astro aborts the build ("destination does not match
+// any existing route"), and the platform redirect files emit the segment
+// verbatim, which no host understands. Such redirects are dropped, not emitted.
+const isDynamicRedirectPath = (path: string): boolean => path.includes("[");
+
+export interface MintlifyRedirectPartition {
+  /** Static redirects Blume can honor, translated to Blume's `from`/`to` shape. */
+  kept: NonNullable<BlumeConfig["redirects"]>;
+  /** Source paths of dynamic redirects dropped because Blume can't model them. */
+  dropped: string[];
+}
+
+/**
+ * Split a spec's redirects into the static ones Blume emits and the dynamic
+ * (wildcard/param) ones it drops. Keeping a dynamic redirect crashes the Astro
+ * build, so the migrator surfaces the dropped sources as a warning instead.
+ */
+export const partitionMintlifyRedirects = (
   spec: JsonObject
-): NonNullable<BlumeConfig["redirects"]> =>
-  asArray(spec.redirects).flatMap((redirect) => {
+): MintlifyRedirectPartition => {
+  const kept: NonNullable<BlumeConfig["redirects"]> = [];
+  const dropped: string[] = [];
+  for (const redirect of asArray(spec.redirects)) {
     const object = asObject(redirect);
     if (!object) {
-      return [];
+      continue;
     }
-    const from = asString(object.source) ?? asString(object.from);
-    const to =
+    const source = asString(object.source) ?? asString(object.from);
+    const destination =
       asString(object.destination) ??
       asString(object.to) ??
       asString(object.redirect);
-    if (!from || !to) {
+    if (!source || !destination) {
+      continue;
+    }
+    const from = toAstroRedirectPath(source);
+    const to = toAstroRedirectPath(destination);
+    if (isDynamicRedirectPath(from) || isDynamicRedirectPath(to)) {
+      dropped.push(source);
+    } else {
+      kept.push({ from, to });
+    }
+  }
+  return { dropped, kept };
+};
+
+interface OpenApiSourceDraft {
+  label?: string;
+  route?: string;
+  spec: string;
+}
+
+// A Mintlify `{ source, directory }` object's `directory` is the URL path its
+// generated pages mount under; map it to a Blume per-source `route`.
+const openapiRouteFromDirectory = (value: unknown): string | undefined => {
+  const directory = normalizeDirectory(asString(value) ?? "");
+  return directory.length > 0 ? `/${directory}` : undefined;
+};
+
+// Resolve a Mintlify `openapi` value (a spec string, an array, or a
+// `{ source, directory }` object) into spec sources. Endpoint refs (`GET /path`)
+// are skipped — Blume's native renderer generates those pages from the spec.
+const openapiSourcesFromValue = (
+  value: unknown,
+  context: { label?: string; route?: string }
+): OpenApiSourceDraft[] => {
+  if (typeof value === "string") {
+    if (value.length === 0 || API_ENDPOINT_REF.test(value)) {
       return [];
     }
-    return [{ from, to }];
+    return [
+      withoutUndefined({
+        label: context.label,
+        route: context.route,
+        spec: value,
+      }),
+    ];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => openapiSourcesFromValue(item, context));
+  }
+  const object = asObject(value);
+  if (!object) {
+    return [];
+  }
+  return openapiSourcesFromValue(object.source ?? object.openapi, {
+    label: context.label,
+    route: openapiRouteFromDirectory(object.directory) ?? context.route,
   });
+};
+
+// Walk the navigation tree collecting every `openapi` source — a group or tab
+// can declare one alongside its pages — then fold in the top-level specs
+// (legacy `mint.json` `openapi`, newer `api.openapi`) and dedupe by spec so a
+// Mintlify API reference maps to Blume's native renderer instead of dropping.
+const mintlifyOpenapi = (spec: JsonObject): BlumeConfig["openapi"] => {
+  const drafts: OpenApiSourceDraft[] = [];
+
+  const visit = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      for (const item of node) {
+        visit(item);
+      }
+      return;
+    }
+    const object = asObject(node);
+    if (!object) {
+      return;
+    }
+    if (hasOwn(object, "openapi")) {
+      drafts.push(
+        ...openapiSourcesFromValue(object.openapi, {
+          label: labelForNavItem(object),
+        })
+      );
+    }
+    for (const children of childNavigationArrays(object)) {
+      visit(children);
+    }
+  };
+
+  visit(spec.navigation);
+  drafts.push(...openapiSourcesFromValue(spec.openapi, {}));
+  drafts.push(...openapiSourcesFromValue(asObject(spec.api)?.openapi, {}));
+
+  const seen = new Set<string>();
+  const sources = drafts.flatMap((draft) => {
+    if (seen.has(draft.spec)) {
+      return [];
+    }
+    seen.add(draft.spec);
+    return [draft];
+  });
+
+  return sources.length > 0 ? { enabled: true, sources } : undefined;
+};
 
 const mintlifyLogo = (value: unknown): BlumeConfig["logo"] => {
   if (typeof value === "string") {
@@ -645,6 +689,16 @@ const mintlifyFavicon = (value: unknown): BlumeConfig["favicon"] => {
   return withoutUndefined({ dark, light });
 };
 
+// Mintlify defaults to Font Awesome, so a migrated site's bare `icon` names are
+// FA names unless it opted into Lucide/Tabler. Set the default library to match.
+const mintlifyIcons = (value: unknown): BlumeConfig["icons"] => {
+  const library = asString(asObject(value)?.library);
+  return {
+    library:
+      library === "lucide" || library === "tabler" ? library : "fontawesome",
+  };
+};
+
 const mintlifyBanner = (value: unknown): BlumeConfig["banner"] => {
   const object = asObject(value);
   const content = object ? asString(object.content) : undefined;
@@ -768,6 +822,43 @@ const mintlifyMarkdown = (
   });
 };
 
+type ThemeFonts = NonNullable<NonNullable<BlumeConfig["theme"]>["fonts"]>;
+
+// Blume's curated Google-font family names, indexed by lowercased family so a
+// Mintlify `fonts.family: "Space Grotesk"` resolves to the `space-grotesk` slug.
+const FAMILY_TO_SLUG: Record<string, string> = Object.fromEntries(
+  Object.entries(GOOGLE_FONTS).map(([slug, def]) => [
+    def.family.toLowerCase(),
+    slug,
+  ])
+);
+
+const fontSlugForFamily = (value: unknown): string | undefined => {
+  const family = asString(value);
+  return family ? FAMILY_TO_SLUG[family.toLowerCase()] : undefined;
+};
+
+/**
+ * Map Mintlify `fonts` onto Blume `theme.fonts`. Mintlify sets one family for
+ * everything (`fonts.family`) or splits heading/body (`fonts.heading.family`,
+ * `fonts.body.family`); each maps to a curated Blume slug when one matches.
+ * Families outside Blume's set are left unset (defaults) and warned about.
+ */
+const mintlifyFonts = (value: unknown): ThemeFonts | undefined => {
+  const object = asObject(value);
+  if (!object) {
+    return undefined;
+  }
+  const heading = asObject(object.heading);
+  const body = asObject(object.body);
+  const fonts = withoutUndefined({
+    body: fontSlugForFamily(body?.family) ?? fontSlugForFamily(object.family),
+    display:
+      fontSlugForFamily(heading?.family) ?? fontSlugForFamily(object.family),
+  });
+  return Object.keys(fonts).length > 0 ? (fonts as ThemeFonts) : undefined;
+};
+
 const mintlifySeo = (value: unknown): NonNullable<BlumeConfig["seo"]> => {
   const object = asObject(value);
   const metatags = asObject(object?.metatags);
@@ -825,16 +916,17 @@ export const loadMintlifyConfig = async (
     },
     description: asString(spec.description),
     favicon: mintlifyFavicon(spec.favicon),
+    icons: mintlifyIcons(spec.icons),
     logo: mintlifyLogo(spec.logo),
     markdown: mintlifyMarkdown(spec.markdown, styling),
     navigation: {
       chromeVariants: mintlifyChromeVariants(spec),
       selectors: mintlifySelectors(spec),
       sidebar: await toSidebarItems(mintlifyNavigationItems(navigation), {}),
-      sidebarVariants: await mintlifySidebarVariants(spec),
       tabs: mintlifyTabs(spec),
     },
-    redirects: mintlifyRedirects(spec),
+    openapi: mintlifyOpenapi(spec),
+    redirects: partitionMintlifyRedirects(spec).kept,
     search: {
       indexing: {
         includeHiddenPages: seo.indexing === "all",
@@ -851,6 +943,7 @@ export const loadMintlifyConfig = async (
       backgroundDecoration: mintlifyBackgroundDecoration(spec.background),
       backgroundImage: backgroundImage.light,
       backgroundImageDark: backgroundImage.dark,
+      fonts: mintlifyFonts(spec.fonts ?? spec.font),
       mode:
         appearance.default === "light" ||
         appearance.default === "dark" ||

package/src/migrate/mintlify/content.ts

@@ -56,6 +56,22 @@ export const rewriteMintlifyExampleBlocks = (source: string): string =>
     "<$<close>CodeGroup"
   );
 
+/**
+ * Mintlify nests `<Accordion title="…">` items inside an `<AccordionGroup>`.
+ * Blume inverts that: `<Accordion>` is the container and each item is an
+ * `<AccordionItem title="…">`. Rewrite both in a single pass — the `\b` after
+ * `Accordion` keeps `<AccordionGroup>` (the `Group` branch) distinct from an
+ * item, so open/close tags of either map correctly regardless of order. Without
+ * this, migrated pages keep `<AccordionGroup>`, which Blume doesn't ship and the
+ * MDX build rejects with "Expected component AccordionGroup to be defined".
+ */
+export const rewriteMintlifyAccordions = (source: string): string =>
+  source.replaceAll(
+    /<(?<close>\/?)Accordion(?<group>Group)?\b/gu,
+    (_match, close: string, group: string | undefined) =>
+      group ? `<${close}Accordion` : `<${close}AccordionItem`
+  );
+
 const SNIPPET_IMPORT =
   /^import\s+[\s\S]*?\s+from\s+["'](?<source>\/snippets\/[^"']+)["'];?[ \t]*\n?/gmu;
 
@@ -88,8 +104,14 @@ export const rewriteSnippetImports = (
   return { components, source: next };
 };
 
-/** Component tags Blume has no equivalent for — reported for manual review. */
-const UNSUPPORTED_COMPONENTS = ["ParamField", "ResponseField"];
+/**
+ * Component tags Blume has no equivalent for — reported for manual review.
+ * `<ParamField>`/`<ResponseField>`/`<RequestField>` are no longer here: Blume
+ * ships compat components for them, so migrated docs render as-is. Mintlify's
+ * `<Update>` changelog entry has no component form in Blume (changelog is
+ * frontmatter-driven via `type: changelog`), so it stays flagged.
+ */
+const UNSUPPORTED_COMPONENTS = ["Update"];
 
 /** Names of Mintlify components in `source` that need manual attention. */
 export const unsupportedMintlifyComponents = (source: string): string[] =>