blume 0.3.0 → 0.5.0

package/src/migrate/mintlify/assets.ts

@@ -0,0 +1,46 @@
+import type { BlumeConfig } from "../../core/schema.ts";
+
+/** Asset paths referenced by the resolved config (logo, favicon, backgrounds). */
+const assetRefs = (config: BlumeConfig): unknown[] => {
+  const refs: unknown[] = ["/images"];
+  const logo = config.logo as
+    | string
+    | { dark?: string; light?: string }
+    | undefined;
+  if (typeof logo === "string") {
+    refs.push(logo);
+  } else if (logo) {
+    refs.push(logo.light, logo.dark);
+  }
+  const favicon = config.favicon as
+    | string
+    | { dark?: string; light?: string }
+    | undefined;
+  if (typeof favicon === "string") {
+    refs.push(favicon);
+  } else if (favicon) {
+    refs.push(favicon.light, favicon.dark);
+  }
+  refs.push(config.theme?.backgroundImage, config.theme?.backgroundImageDark);
+  return refs;
+};
+
+/**
+ * Top-level path segments referenced as static assets by a Mintlify config
+ * (the conventional `/images`, plus logo/favicon/background paths). These are
+ * the root-served folders Mintlify exposes at the site root; Blume serves them
+ * via `content.assets` (bridge) or relocates them under `public/` (migrator).
+ */
+export const assetSegments = (config: BlumeConfig): string[] => {
+  const segments = new Set<string>();
+  for (const ref of assetRefs(config)) {
+    if (typeof ref !== "string" || !ref.startsWith("/")) {
+      continue;
+    }
+    const [segment] = ref.replace(/^\/+/u, "").split("/");
+    if (segment) {
+      segments.add(segment);
+    }
+  }
+  return [...segments];
+};

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"];
@@ -593,6 +594,16 @@ const mintignorePatterns = async (root: string): Promise<string[]> => {
   }
 };
 
+// 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}]`
+  );
+
 const mintlifyRedirects = (
   spec: JsonObject
 ): NonNullable<BlumeConfig["redirects"]> =>
@@ -609,9 +620,100 @@ const mintlifyRedirects = (
     if (!from || !to) {
       return [];
     }
-    return [{ from, to }];
+    return [{ from: toAstroRedirectPath(from), to: toAstroRedirectPath(to) }];
+  });
+
+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 [
+      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") {
     return value;
@@ -645,6 +747,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 +880,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,6 +974,7 @@ 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: {
@@ -834,6 +984,7 @@ export const loadMintlifyConfig = async (
       sidebarVariants: await mintlifySidebarVariants(spec),
       tabs: mintlifyTabs(spec),
     },
+    openapi: mintlifyOpenapi(spec),
     redirects: mintlifyRedirects(spec),
     search: {
       indexing: {
@@ -851,6 +1002,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

@@ -88,8 +88,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[] =>

package/src/migrate/mintlify/index.ts

@@ -1,10 +1,11 @@
 import { existsSync } from "node:fs";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 
 import { dirname, join } from "pathe";
 import { glob } from "tinyglobby";
 
 import type { BlumeConfig } from "../../core/schema.ts";
+import { assetSegments } from "./assets.ts";
 import { loadMintlifyConfig } from "./config.ts";
 import { mintlifyI18n } from "./i18n.ts";
 import { transformMintlifyContent } from "./transform.ts";
@@ -14,6 +15,56 @@ export interface MintlifyMigrationResult {
   warnings: string[];
 }
 
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+  value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+
+const hasFontFamily = (value: unknown): boolean => {
+  const object = asRecord(value);
+  if (!object) {
+    return false;
+  }
+  const named = (child: unknown): boolean =>
+    typeof asRecord(child)?.family === "string";
+  return (
+    typeof object.family === "string" ||
+    named(object.heading) ||
+    named(object.body)
+  );
+};
+
+/**
+ * Warn about Mintlify site chrome that Blume's config doesn't model, so it isn't
+ * dropped silently: header links (`navbar.links`/`navbar.primary`), footer
+ * socials (`footer.socials`), and fonts outside Blume's curated Google set. The
+ * contextual page menu and last-updated timestamp are covered by Blume defaults
+ * (page actions, git-derived dates), so they need no warning.
+ */
+const droppedChromeWarnings = (
+  spec: Record<string, unknown>,
+  config: BlumeConfig
+): string[] => {
+  const warnings: string[] = [];
+  const navbar = asRecord(spec.navbar);
+  if (navbar && (navbar.links || navbar.primary)) {
+    warnings.push(
+      "Header links (navbar.links/navbar.primary) have no blume.config equivalent and were dropped; re-add them with navigation.tabs or a Header layout override."
+    );
+  }
+  if (asRecord(spec.footer)?.socials) {
+    warnings.push(
+      "Footer social links (footer.socials) have no blume.config equivalent and were dropped; add them with a Footer layout override."
+    );
+  }
+  if (hasFontFamily(spec.fonts ?? spec.font) && !config.theme?.fonts) {
+    warnings.push(
+      "docs.json font family isn't in Blume's curated Google Fonts set; set theme.fonts to a supported slug or add @font-face rules in theme.css."
+    );
+  }
+  return warnings;
+};
+
 /** Recursively drop `undefined`, empty arrays, and empty objects. */
 const prune = (value: unknown): unknown => {
   if (Array.isArray(value)) {
@@ -52,28 +103,37 @@ const writeBlumeConfig = async (
   await writeFile(join(root, "blume.config.ts"), body, "utf-8");
 };
 
-/** Move a referenced top-level asset path (file or dir) under `public/`. */
+interface RelocatedAssets {
+  /** Top-level dirs served in place via `content.assets` (no files moved). */
+  served: string[];
+  /** Top-level files moved under `public/`. */
+  moved: string[];
+}
+
+/**
+ * Make referenced top-level assets resolvable in Blume. Directories (e.g.
+ * Mintlify's `images/`) are left in place and served via `content.assets`, so
+ * the migration doesn't churn every file under them; loose top-level files
+ * (a root `favicon.png`, `logo.png`) are moved under `public/` since a mount
+ * points at a directory.
+ */
 const relocateAssets = async (
   root: string,
-  refs: unknown[]
-): Promise<string[]> => {
-  const segments = new Set<string>();
-  for (const ref of refs) {
-    if (typeof ref !== "string" || !ref.startsWith("/")) {
-      continue;
-    }
-    const [segment] = ref.replace(/^\/+/u, "").split("/");
-    if (segment) {
-      segments.add(segment);
-    }
-  }
-
+  segments: string[]
+): Promise<RelocatedAssets> => {
+  const served: string[] = [];
   const moved: string[] = [];
   for (const segment of segments) {
     const source = join(root, segment);
     if (!existsSync(source) || segment === "public") {
       continue;
     }
+    // oxlint-disable-next-line no-await-in-loop -- sequential fs stats
+    const stats = await stat(source);
+    if (stats.isDirectory()) {
+      served.push(segment);
+      continue;
+    }
     const dest = join(root, "public", segment);
     if (existsSync(dest)) {
       continue;
@@ -84,7 +144,32 @@ const relocateAssets = async (
     await rename(source, dest);
     moved.push(segment);
   }
-  return moved;
+  return { moved, served };
+};
+
+/**
+ * Fold relocated assets into the config (served dirs become `content.assets`)
+ * and record what happened. Served dirs stay in place; only loose files moved.
+ */
+const applyRelocatedAssets = (
+  config: BlumeConfig,
+  assets: RelocatedAssets,
+  warnings: string[]
+): void => {
+  if (assets.served.length > 0) {
+    config.content = {
+      ...config.content,
+      assets: [
+        ...new Set([...(config.content?.assets ?? []), ...assets.served]),
+      ],
+    };
+    warnings.push(
+      `Kept asset dir(s) in place, served via content.assets: ${assets.served.join(", ")}.`
+    );
+  }
+  if (assets.moved.length > 0) {
+    warnings.push(`Moved assets into public/: ${assets.moved.join(", ")}.`);
+  }
 };
 
 /**
@@ -121,31 +206,6 @@ const cleanupSnippets = async (
   }
 };
 
-/** Asset paths referenced by the resolved config (logo, favicon, backgrounds). */
-const assetRefs = (config: BlumeConfig): unknown[] => {
-  const refs: unknown[] = ["/images"];
-  const logo = config.logo as
-    | string
-    | { dark?: string; light?: string }
-    | undefined;
-  if (typeof logo === "string") {
-    refs.push(logo);
-  } else if (logo) {
-    refs.push(logo.light, logo.dark);
-  }
-  const favicon = config.favicon as
-    | string
-    | { dark?: string; light?: string }
-    | undefined;
-  if (typeof favicon === "string") {
-    refs.push(favicon);
-  } else if (favicon) {
-    refs.push(favicon.light, favicon.dark);
-  }
-  refs.push(config.theme?.backgroundImage, config.theme?.backgroundImageDark);
-  return refs;
-};
-
 /**
  * Migrate a Mintlify project to Blume: translate `docs.json`/`mint.json` into
  * `blume.config.ts`, rewrite every page to idiomatic Blume MDX in place, and
@@ -180,6 +240,13 @@ export const migrateMintlifyProject = async (
         `Mapped ${i18n.locales.length} languages to i18n.locales (default: ${i18n.defaultLocale}); review the locale labels.`
       );
     }
+    const openapiSources = config.openapi?.sources ?? [];
+    if (openapiSources.length > 0) {
+      warnings.push(
+        `Mapped ${openapiSources.length} OpenAPI spec source(s) to openapi.sources (native reference renderer); verify each spec path or URL resolves.`
+      );
+    }
+    warnings.push(...droppedChromeWarnings(spec, config));
   } else {
     warnings.push("No docs.json or mint.json found; writing a default config.");
     config = { content: { root: "." }, title: "Documentation" };
@@ -232,12 +299,13 @@ export const migrateMintlifyProject = async (
     moved += 1;
   }
 
-  const movedAssets = await relocateAssets(root, assetRefs(config));
+  const assets = await relocateAssets(root, assetSegments(config));
   await cleanupSnippets(root, keptComponents, warnings);
 
   if (config.content?.exclude) {
     config.content.exclude = [...new Set(config.content.exclude)];
   }
+  applyRelocatedAssets(config, assets, warnings);
   await writeBlumeConfig(root, config);
 
   if (Object.keys(variables).length > 0) {
@@ -245,9 +313,6 @@ export const migrateMintlifyProject = async (
       `Inlined ${Object.keys(variables).length} docs.json variable(s) into content; Blume has no runtime variable substitution.`
     );
   }
-  if (movedAssets.length > 0) {
-    warnings.push(`Moved assets into public/: ${movedAssets.join(", ")}.`);
-  }
   if (removedKeys.size > 0) {
     warnings.push(
       `Dropped unsupported page frontmatter keys: ${[...removedKeys].join(", ")}.`
@@ -255,7 +320,7 @@ export const migrateMintlifyProject = async (
   }
   if (unsupported.size > 0) {
     warnings.push(
-      `Components without a Blume equivalent need manual review (use the OpenAPI reference instead): ${[...unsupported].join(", ")}.`
+      `Components without a Blume equivalent need manual review: ${[...unsupported].join(", ")}.`
     );
   }
   warnings.push(

package/src/migrate/shared.ts

@@ -1,11 +1,22 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 
-import { join } from "pathe";
+import { isAbsolute, join, relative } from "pathe";
 
 import type { BlumeConfig } from "../core/schema.ts";
 import { pageMetaSchema } from "../core/schema.ts";
 
+/**
+ * Whether `candidate` resolves to a path inside `root` (or is `root` itself).
+ * Guards migrators against `../` traversal in author-controlled source paths
+ * (`pages` entries, `<include>` targets) that would otherwise read or move
+ * files outside the docs tree.
+ */
+export const isInsideRoot = (root: string, candidate: string): boolean => {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+};
+
 /**
  * Framework-agnostic helpers shared by more than one migrator. Each piece here
  * was generalized from a migrator-specific implementation so Mintlify, Nextra,
@@ -86,32 +97,6 @@ export const rewriteFrameworkScripts = async (
   return changed;
 };
 
-/** A `.gitignore` line, normalized for comparison (trailing slashes dropped). */
-const gitignoreKey = (line: string): string => line.trim().replace(/\/+$/u, "");
-
-/**
- * Ensure `.gitignore` ignores each of `entries`, appending any that are missing
- * (creating the file when absent). Trailing-slash differences (`dist` vs
- * `dist/`) count as already present. Returns the entries actually added.
- */
-export const ensureGitignore = async (
-  root: string,
-  entries: string[]
-): Promise<string[]> => {
-  const path = join(root, ".gitignore");
-  const existing = existsSync(path) ? await readFile(path, "utf-8") : "";
-  const present = new Set(
-    existing.split("\n").map(gitignoreKey).filter(Boolean)
-  );
-  const added = entries.filter((entry) => !present.has(gitignoreKey(entry)));
-  if (added.length === 0) {
-    return [];
-  }
-  const gap = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-  await writeFile(path, `${existing}${gap}${added.join("\n")}\n`, "utf-8");
-  return added;
-};
-
 /** Of the candidate project-relative paths, the ones that still exist — the old
  * framework files a migration leaves behind for the user to remove by hand. */
 export const leftoverFiles = (root: string, candidates: string[]): string[] =>

package/src/og/card.ts

@@ -56,8 +56,20 @@ const MUTED = "#737373";
 const FAINT = "#a3a3a3";
 const BORDER = "#e5e5e5";
 
-const truncate = (value: string, max: number): string =>
-  value.length > max ? `${value.slice(0, max - 1).trimEnd()}…` : value;
+/**
+ * Truncate to `max` code points with an ellipsis. Slices by code points, not
+ * UTF-16 units, so cutting mid-emoji doesn't leave a lone surrogate (a broken
+ * glyph) before the ellipsis.
+ */
+export const truncate = (value: string, max: number): string => {
+  const chars = [...value];
+  return chars.length > max
+    ? `${chars
+        .slice(0, max - 1)
+        .join("")
+        .trimEnd()}…`
+    : value;
+};
 
 // Brand mark sizing: target this height, but scale down so a wide wordmark logo
 // stays within the lockup.