blume 0.5.2 → 0.5.4

package/src/theme/icons.ts

@@ -1,16 +1,11 @@
 /**
- * Icon resolution backed by the open Iconify icon sets — Font Awesome (free),
- * Lucide, and Tabler — the three libraries Mintlify exposes. Resolution runs at
+ * Icon resolution backed by the open Iconify Lucide set. Resolution runs at
  * **build time, server-side**, and returns ready-to-inline SVG, so icons stay
- * zero-JS and fully self-contained (no runtime CDN fetch, unlike Mintlify).
+ * zero-JS and fully self-contained (no runtime CDN fetch).
  *
  * Because the Iconify set data is large, this module must only be imported from
  * server contexts (`.astro` frontmatter, the CLI). Client scripts use the tiny
  * hand-inlined set in `./chrome-icons.ts` instead.
- *
- * Coverage vs Mintlify: full parity for every Font Awesome *free* name, Lucide,
- * and Tabler. Font Awesome Pro styles (`light`/`thin`/`duotone`/`sharp-solid`)
- * aren't in the open data, so they fall back to `solid`.
  */
 import { createRequire } from "node:module";
 
@@ -25,97 +20,43 @@ const requireJson = createRequire(import.meta.url);
 const loadSet = (pkg: string): IconifyJSON => requireJson(pkg) as IconifyJSON;
 
 const SETS: Record<string, IconifyJSON> = {
-  "fa6-brands": loadSet("@iconify-json/fa6-brands/icons.json"),
-  "fa6-regular": loadSet("@iconify-json/fa6-regular/icons.json"),
-  "fa6-solid": loadSet("@iconify-json/fa6-solid/icons.json"),
   lucide: loadSet("@iconify-json/lucide/icons.json"),
-  tabler: loadSet("@iconify-json/tabler/icons.json"),
 };
 
-/** Blume's default library when a project sets no `icons.library`. */
+/** Blume's only icon library. */
 const DEFAULT_SET = "lucide";
 
-/** `icons.library` config value → Iconify set. */
-const LIBRARY_SETS: Record<string, string> = {
-  fa: "fa6-solid",
-  "font-awesome": "fa6-solid",
-  fontawesome: "fa6-solid",
+/** Explicit `prefix:name` prefixes. Lucide is the only bundled set. */
+const PREFIX_SETS: Record<string, string> = {
   lucide: "lucide",
-  tabler: "tabler",
 };
 
 /**
- * Mintlify Font Awesome `iconType` → Iconify set. The Pro-only styles
- * (`light`/`thin`/`duotone`/`sharp-solid`) aren't in the free data, so they map
- * to `solid` rather than render nothing.
+ * Own-property map lookup. Icon names come from content and config, so a value
+ * like `constructor:x` would otherwise resolve an Object.prototype member (a
+ * function) and crash resolution deep in the build with no pointer to the
+ * offending page.
  */
-const ICON_TYPE_SETS: Record<string, string> = {
-  brands: "fa6-brands",
-  duotone: "fa6-solid",
-  light: "fa6-solid",
-  regular: "fa6-regular",
-  "sharp-solid": "fa6-solid",
-  solid: "fa6-solid",
-  thin: "fa6-solid",
-};
-
-/** Explicit `prefix:name` prefixes (Iconify prefixes + common FA aliases). */
-const PREFIX_SETS: Record<string, string> = {
-  ...LIBRARY_SETS,
-  fa: "fa6-solid",
-  "fa-brands": "fa6-brands",
-  "fa-regular": "fa6-regular",
-  "fa-solid": "fa6-solid",
-  "fa6-brands": "fa6-brands",
-  "fa6-regular": "fa6-regular",
-  "fa6-solid": "fa6-solid",
-  fab: "fa6-brands",
-  far: "fa6-regular",
-  fas: "fa6-solid",
-  ti: "tabler",
-};
+const ownEntry = <T>(map: Record<string, T>, key: string): T | undefined =>
+  Object.hasOwn(map, key) ? map[key] : undefined;
 
 export interface ResolvedIcon {
   /** Inner SVG markup (self-styled: carries its own fill/stroke). */
   body: string;
   /** The resolved icon name. */
   name: string;
-  /** The icon's viewBox, which varies per library (24×24, 512-height, …). */
+  /** The icon's viewBox (Lucide is 24×24). */
   viewBox: string;
 }
 
-export interface ResolveIconOptions {
-  /** Font Awesome style selector (`solid`, `regular`, `brands`, …). */
-  iconType?: string;
-  /** Default library for a bare name (`fontawesome` | `lucide` | `tabler`). */
-  library?: string;
-}
-
 const normalize = (name: string): string =>
   name
     .trim()
     .toLowerCase()
     .replaceAll(/[\s_]+/gu, "-");
 
-/** Which set a bare name resolves against, given library/iconType hints. */
-const setFor = (options: ResolveIconOptions): string => {
-  if (options.iconType) {
-    const set = ICON_TYPE_SETS[normalize(options.iconType)];
-    if (set) {
-      return set;
-    }
-  }
-  if (options.library) {
-    const set = LIBRARY_SETS[normalize(options.library)];
-    if (set) {
-      return set;
-    }
-  }
-  return DEFAULT_SET;
-};
-
 const fromSet = (setName: string, iconName: string): ResolvedIcon | null => {
-  const set = SETS[setName];
+  const set = ownEntry(SETS, setName);
   const data = set && getIconData(set, iconName);
   if (!data) {
     return null;
@@ -124,46 +65,23 @@ const fromSet = (setName: string, iconName: string): ResolvedIcon | null => {
   return { body, name: iconName, viewBox: attributes.viewBox };
 };
 
-// Font Awesome splits brands into their own set, so a bare `github` under a
-// solid/regular default still resolves.
-const fromFaSet = (setName: string, name: string): ResolvedIcon | null =>
-  fromSet(setName, name) ?? fromSet("fa6-brands", name);
-
-const resolveInSet = (setName: string, name: string): ResolvedIcon | null =>
-  setName.startsWith("fa6-")
-    ? fromFaSet(setName, name)
-    : fromSet(setName, name);
-
 /**
- * Resolve an icon name to inline SVG. Honors an explicit `prefix:name`
- * (`lucide:rocket`, `fa6-brands:github`), then `iconType`, then the configured
- * `library`, falling back to Lucide.
+ * Resolve an icon name to inline SVG. Honors an explicit `lucide:name` prefix;
+ * a bare name resolves against Lucide.
  */
-export const resolveIcon = (
-  name: string,
-  options: ResolveIconOptions = {}
-): ResolvedIcon | null => {
+export const resolveIcon = (name: string): ResolvedIcon | null => {
   const normalized = normalize(name);
   const colon = normalized.indexOf(":");
   if (colon > 0) {
-    const setName = PREFIX_SETS[normalized.slice(0, colon)];
-    if (setName) {
-      return resolveInSet(setName, normalized.slice(colon + 1));
-    }
+    const setName = ownEntry(PREFIX_SETS, normalized.slice(0, colon));
+    return setName ? fromSet(setName, normalized.slice(colon + 1)) : null;
   }
-  return resolveInSet(setFor(options), normalized);
+  return fromSet(DEFAULT_SET, normalized);
 };
 
-/**
- * Whether a name resolves to a known icon. Without a library hint this checks
- * every bundled set, so a valid Font Awesome/Tabler name isn't flagged as a typo
- * just because the project's default library is Lucide.
- */
-export const hasIcon = (
-  name: string,
-  options: ResolveIconOptions = {}
-): boolean => {
-  if (resolveIcon(name, options)) {
+/** Whether a name resolves to a known Lucide icon. */
+export const hasIcon = (name: string): boolean => {
+  if (resolveIcon(name)) {
     return true;
   }
   const normalized = normalize(name);

package/src/theme/palette.ts

@@ -22,6 +22,17 @@ const CSS_COLOR = /^[\w\s#%.,()/+-]+$/u;
 const safeColor = (value: string, fallback: string): string =>
   CSS_COLOR.test(value.trim()) ? value.trim() : fallback;
 
+/**
+ * Resolve a named preset or fall back to {@link safeColor}. `hasOwn` keeps a
+ * value like "constructor" from resolving an Object.prototype member — which
+ * would stringify a function into the generated CSS, breaking the rule (the
+ * exact breakout safeColor exists to prevent).
+ */
+const presetOrColor = (value: string): string =>
+  Object.hasOwn(ACCENTS, value)
+    ? (ACCENTS[value] as string)
+    : safeColor(value, FALLBACK_ACCENT);
+
 /** Like {@link safeColor} but drops an unsafe/absent value to `null`. */
 const safeColorOrNull = (value: string | undefined): string | null =>
   value && CSS_COLOR.test(value.trim()) ? value.trim() : null;
@@ -41,36 +52,11 @@ const backgroundImageCss = (image: string): string =>
 const cssToken = (name: string, value?: string | null): string[] =>
   value ? [`  ${name}: ${value};`] : [];
 
-const backgroundDecorationCss = (
-  decoration: ResolvedConfig["theme"]["backgroundDecoration"]
-): string => {
-  if (decoration === "gradient") {
-    return `  --blume-background-decoration: radial-gradient(circle at top left, color-mix(in oklab, var(--blume-accent) 18%, transparent), transparent 28rem), radial-gradient(circle at top right, color-mix(in oklab, var(--blume-action) 12%, transparent), transparent 24rem);
-  --blume-background-decoration-repeat: no-repeat, no-repeat;
-  --blume-background-decoration-size: auto, auto;
-`;
-  }
-  if (decoration === "grid") {
-    return `  --blume-background-decoration: linear-gradient(var(--blume-border) 1px, transparent 1px), linear-gradient(90deg, var(--blume-border) 1px, transparent 1px);
-  --blume-background-decoration-repeat: repeat, repeat;
-  --blume-background-decoration-size: 2rem 2rem, 2rem 2rem;
-`;
-  }
-  if (decoration === "windows") {
-    return `  --blume-background-decoration: linear-gradient(90deg, color-mix(in oklab, var(--blume-border) 70%, transparent) 1px, transparent 1px), linear-gradient(var(--blume-border) 1px, transparent 1px);
-  --blume-background-decoration-repeat: repeat, repeat;
-  --blume-background-decoration-size: 7rem 4.5rem, 7rem 4.5rem;
-`;
-  }
-  return "";
-};
-
 const themeRootCss = (
   theme: ResolvedConfig["theme"],
   options: {
     accent: string;
     action: string | null;
-    backgroundDecoration: string;
     radius: string;
   }
 ): string =>
@@ -86,7 +72,6 @@ const themeRootCss = (
       "--blume-background-image",
       theme.backgroundImage ? backgroundImageCss(theme.backgroundImage) : null
     ),
-    options.backgroundDecoration.trimEnd(),
     `  --blume-radius: ${options.radius};`,
   ]
     .filter(Boolean)
@@ -94,10 +79,23 @@ const themeRootCss = (
 
 const themeDarkCss = (
   theme: ResolvedConfig["theme"],
-  accentDark: string | null
+  options: {
+    accent: string;
+    action: string | null;
+  }
 ): string => {
+  // Mode-shared tokens (accent, action) must be re-declared here: the base
+  // stylesheet's own `:root[data-theme="dark"]` block outranks the `:root`
+  // config tokens on specificity, so without this block dark mode would
+  // silently keep its neutral defaults and ignore the config.
   const tokens = [
-    ...cssToken("--blume-accent", accentDark),
+    `  --blume-accent: ${options.accent};`,
+    "  --blume-accent-foreground: oklch(1 0 0);",
+    ...cssToken("--blume-action", options.action),
+    ...cssToken(
+      "--blume-action-foreground",
+      options.action ? "oklch(1 0 0)" : null
+    ),
     ...cssToken("--blume-background", safeColorOrNull(theme.backgroundDark)),
     ...cssToken(
       "--blume-background-image",
@@ -105,10 +103,7 @@ const themeDarkCss = (
         ? backgroundImageCss(theme.backgroundImageDark)
         : null
     ),
-  ];
-  if (tokens.length === 0) {
-    return "";
-  }
+  ].filter(Boolean);
   return `:root[data-theme="dark"] {
 ${tokens.join("\n")}
 }
@@ -121,7 +116,7 @@ ${tokens.join("\n")}
  * arbitrary colors without a config change.
  */
 export const resolveAccent = (theme: ResolvedConfig["theme"]): string =>
-  ACCENTS[theme.accent] ?? safeColor(theme.accent, FALLBACK_ACCENT);
+  presetOrColor(theme.accent);
 
 /** Resolve the configured radius preset to a CSS length. */
 export const resolveRadius = (theme: ResolvedConfig["theme"]): string =>
@@ -133,26 +128,19 @@ export const resolveRadius = (theme: ResolvedConfig["theme"]): string =>
  * arbitrary colors without a config change.
  */
 export const buildThemeCss = (theme: ResolvedConfig["theme"]): string => {
-  const accent =
-    ACCENTS[theme.accent] ?? safeColor(theme.accent, FALLBACK_ACCENT);
-  const accentDark = theme.accentDark
-    ? (ACCENTS[theme.accentDark] ??
-      safeColor(theme.accentDark, FALLBACK_ACCENT))
-    : null;
-  const action = theme.action
-    ? (ACCENTS[theme.action] ?? safeColor(theme.action, FALLBACK_ACCENT))
-    : null;
-  const backgroundDecoration = backgroundDecorationCss(
-    theme.backgroundDecoration
-  );
+  const accent = presetOrColor(theme.accent);
+  const accentDark = theme.accentDark ? presetOrColor(theme.accentDark) : null;
+  const action = theme.action ? presetOrColor(theme.action) : null;
   const radius = RADII[theme.radius];
   const root = themeRootCss(theme, {
     accent,
     action,
-    backgroundDecoration,
     radius,
   });
-  const dark = themeDarkCss(theme, accentDark);
+  const dark = themeDarkCss(theme, {
+    accent: accentDark ?? accent,
+    action,
+  });
 
   return `/* Generated by Blume from theme config. */
 :root {

package/src/theme/twoslash.ts

@@ -33,9 +33,14 @@ const OVERRIDES = `
 
 /* Popups are absolutely positioned and must escape the pre's scroll container.
    The base prose pre rule (from the typography layer) wins the cascade here
-   despite lower specificity, so !important is needed to force visibility. */
+   despite lower specificity, so !important is needed to force visibility.
+   Regular code blocks scroll their inner code element and carry the horizontal
+   padding there; twoslash code opts out of that scroller (popups again), so the
+   padding is restored on the pre. */
 .prose pre.twoslash {
   overflow: visible !important;
+  padding-left: 1.25rem;
+  padding-right: 1.25rem;
 }
 
 /* The rich renderer renders each popup's type signature as a nested Shiki

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

@@ -1,24 +0,0 @@
-import type { BlumeConfig } from "./schema.ts";
-/** A detected docs-tool config that Blume can serve without a migration. */
-export interface BridgeDetection {
-    /** Which foreign docs tool was detected. */
-    tool: "mintlify";
-    /** Absolute path of the detected config file (`docs.json`/`mint.json`). */
-    configFile: string;
-    /** A Blume config synthesized from the foreign config, ready to validate. */
-    raw: BlumeConfig;
-}
-/**
- * Detect a Mintlify project at `root` and synthesize an equivalent Blume config.
- *
- * "Bridge mode" lets a team swap `mintlify dev` for `blume dev` with no file
- * changes: `docs.json` is translated to Blume config (`loadMintlifyConfig`) and
- * its content block is rewired to a single `mintlify` content source, which
- * transforms each MDX page to Blume idiom at scan time. The original
- * `content.root`/`exclude` and `variables` move onto the source (Blume has no
- * runtime variable substitution, so globals are inlined into content there).
- *
- * Returns `null` when no Mintlify config is present. Only called when no
- * `blume.config.*` exists, so an explicit Blume config always takes precedence.
- */
-export declare const detectMintlifyBridge: (root: string) => Promise<BridgeDetection | null>;

package/dist/types/migrate/mintlify/assets.d.ts

@@ -1,8 +0,0 @@
-import type { BlumeConfig } from "../../core/schema.ts";
-/**
- * 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 declare const assetSegments: (config: BlumeConfig) => string[];

package/dist/types/migrate/mintlify/config.d.ts

@@ -1,16 +0,0 @@
-import type { BlumeConfig } from "../../core/schema.ts";
-type JsonObject = Record<string, unknown>;
-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 declare const partitionMintlifyRedirects: (spec: JsonObject) => MintlifyRedirectPartition;
-export declare const loadMintlifyConfig: (root: string, file: string) => Promise<BlumeConfig>;
-export {};

package/dist/types/migrate/mintlify/i18n.d.ts

@@ -1,7 +0,0 @@
-import type { BlumeConfig } from "../../core/schema.ts";
-/**
- * Map a Mintlify `navigation.languages[]` array to a Blume `i18n` config. The
- * entry marked `default: true` becomes `defaultLocale`; translated content
- * already lives in ISO-code directories, which match Blume's `dir` parser.
- */
-export declare const mintlifyI18n: (spec: Record<string, unknown>) => BlumeConfig["i18n"] | null;

package/docs/advanced/bridge.mdx

@@ -1,76 +0,0 @@
----
-title: Bridge
-description: Run blume dev directly on a Mintlify codebase — no config, no migration, no file changes. Blume detects docs.json and serves it in place.
----
-
-Bridge mode lets you point Blume at a **Mintlify** project and run it as-is. There's no config to write and no migration to commit: drop `blume dev` into a directory that has a `docs.json` (or legacy `mint.json`) and Blume detects it, synthesizes an equivalent config in memory, and serves your existing MDX — transformed to Blume idiom on the fly, on disk untouched.
-
-```bash
-cd my-mintlify-docs
-npx blume dev
-```
-
-```txt
-ℹ Detected docs.json — running in Mintlify bridge mode (no migration).
-  Run "blume migrate mintlify" to convert permanently.
-```
-
-It's the zero-commitment way to see what your docs look like on Blume — you can keep running `mintlify dev` in one terminal and `blume dev` in another, side by side, and decide later.
-
-## When it activates
-
-Bridge mode is entirely automatic, gated on two conditions:
-
-- **No Blume config.** There's no `blume.config.{ts,js,mjs}` at the project root. An explicit Blume config always wins — the moment one exists, Blume runs a normal project and bridge mode never triggers.
-- **A Mintlify config is present.** A `docs.json` or `mint.json` sits at the root.
-
-With both true, Blume treats the Mintlify config as its source of truth for that run.
-
-:::note
-Bridge mode applies to `blume build` too, not just `blume dev` — you can produce a static site from an unconverted Mintlify project. Only `blume dev` prints the detection notice.
-:::
-
-## What happens under the hood
-
-Bridge mode is the **read-only twin** of [`blume migrate mintlify`](/docs/advanced/migrate#mintlify): the same translation, without writing anything back.
-
-- **Config is synthesized in memory.** `docs.json` is translated to a Blume config — navigation, theme, and chrome mapped across — exactly as the migrator would, but nothing is written to disk.
-- **Content is served through a Mintlify source.** The config's content block is rewired to a single [`mintlify` content source](/docs/content/sources) rooted at the project. Each MDX page is transformed to Blume markup **at scan time** as it's read, so your files never change.
-- **Variables are inlined at scan time.** `docs.json` `variables` (`{{name}}`) are substituted into content as it's scanned — Blume has no runtime substitution.
-- **Assets are served in place.** Referenced folders like `images/` are served through [`content.assets`](/docs/content/sources) rather than moved to `public/`, so nothing is relocated.
-- **Languages map to i18n.** A multi-language `docs.json` maps to Blume's [`i18n`](/docs/content/i18n), with the language switch handled by Blume's locale routing instead of a nav selector.
-
-Because it reads the same `docs.json` and runs the same transforms, what you see in bridge mode is what you'd get from a full migration.
-
-## Bridge vs. migrate
-
-<CardGroup cols={2}>
-  <Card title="Bridge mode" icon="cable">
-    **Try Blume with zero changes.** Nothing is written; your Mintlify project
-    stays exactly as it is. Ideal for evaluating Blume, running both dev servers
-    side by side, or a reversible spike.
-  </Card>
-  <Card title="Migrate" href="/docs/advanced/migrate" icon="arrow-right">
-    **Convert for good.** [`blume migrate mintlify`](/docs/advanced/migrate)
-    rewrites your pages, config, and assets in place so Blume becomes the source
-    of truth. Do this once you've decided to switch.
-  </Card>
-</CardGroup>
-
-Everything you can do in bridge mode, you can do permanently by migrating — bridge is the preview, migrate is the commit.
-
-## Limitations
-
-- **Mintlify only.** Bridge detection is Mintlify-specific. The other frameworks — Fumadocs, Nextra, Starlight — need a [one-shot migration](/docs/advanced/migrate).
-- **Same idiom gaps as the migrator.** Components without a Blume equivalent are transformed on a best-effort basis; when you hit one, [migrate](/docs/advanced/migrate) and address the warnings, or switch that page to a Blume-native equivalent such as the [OpenAPI reference](/docs/advanced/api-reference).
-- **No runtime variables.** As with a migration, `{{variable}}` values are inlined at scan time rather than substituted at runtime.
-
-<CardGroup cols={2}>
-  <Card title="Migrate" href="/docs/advanced/migrate" icon="arrow-right">
-    Convert a Mintlify, Fumadocs, Nextra, or Starlight project permanently.
-  </Card>
-  <Card title="Content sources" href="/docs/content/sources" icon="folder-tree">
-    How the `mintlify` source and `content.assets` fit into Blume's content
-    graph.
-  </Card>
-</CardGroup>

package/docs/advanced/migrate.mdx

@@ -1,123 +0,0 @@
----
-title: Migrate
-description: Convert a Mintlify, Fumadocs, Nextra, or Starlight project to Blume in one command — config, content, navigation, and assets translated to idiomatic Blume.
----
-
-Already have a docs site somewhere else? `blume migrate` is a one-shot codemod that converts a project from another docs framework into Blume — translating the config, rewriting each page to idiomatic Blume MDX, converting navigation files, and relocating assets, all in place. When it finishes you have a `blume.config.ts` and a tree that `blume dev` can serve.
-
-```bash
-npx blume migrate <tool>
-```
-
-The `<tool>` is the framework you're coming from:
-
-| Tool | Detects | Command |
-| --- | --- | --- |
-| [Mintlify](#mintlify) | `docs.json` / `mint.json` | `blume migrate mintlify` |
-| [Fumadocs](#fumadocs) | `content/docs` + `meta.json` | `blume migrate fumadocs` |
-| [Nextra](#nextra) | `content/` or `pages/` + `_meta` | `blume migrate nextra` |
-| [Starlight](#starlight) | `src/content/docs` + `astro.config.*` | `blume migrate starlight` |
-
-:::warning
-A migration **rewrites files in place** — pages, config, navigation, and assets. Commit (or stash) your work first so you can review the diff and roll back cleanly.
-:::
-
-## What a migration does
-
-Every migrator runs the same shape of work, tuned to the source framework:
-
-<Steps>
-  <Step title="Translate the config">
-    The framework's config — `docs.json`, a `starlight({...})` block, and so on — becomes a `blume.config.ts` at your project root, with navigation, theme, and site chrome mapped across.
-  </Step>
-  <Step title="Rewrite every page">
-    Each `.md`/`.mdx` file is rewritten to idiomatic Blume markup: framework callouts become [`:::` directives](/docs/content/syntax), components are renamed or converted, and frontmatter is mapped to Blume's [page schema](/docs/reference/frontmatter). Keys Blume doesn't recognize are dropped and reported.
-  </Step>
-  <Step title="Convert navigation">
-    Navigation files (`_meta.{js,ts,json}`, `meta.json`) become typed [`meta.ts`](/docs/content/meta) files, preserving order and titles.
-  </Step>
-  <Step title="Relocate assets and scripts">
-    Referenced asset folders are kept in place and served via [`content.assets`](/docs/content/sources); loose top-level files move under `public/`. Your `dev`/`build`/`start` npm scripts are repointed at the matching `blume` commands.
-  </Step>
-</Steps>
-
-When it's done the CLI prints how many files it touched, a list of **warnings** — anything that needs a human eye, like a component with no Blume equivalent or a dropped frontmatter key — and a reminder to review the generated config:
-
-```txt
-✔ Migrated 42 content file(s).
-⚠ Components without a Blume equivalent need manual review: <Frame>.
-⚠ Dropped unsupported page frontmatter keys: mode, "og:image".
-▶ Review blume.config.ts and run `blume dev`.
-```
-
-## Tools
-
-### Mintlify
-
-Reads `docs.json` (or legacy `mint.json`) and rewrites every page **in place** — content stays at the project root (`content.root` is `"."`).
-
-- Snippets under `/snippets` are inlined as includes; component snippets (e.g. `.jsx`) are kept and their imports rewritten to relative paths.
-- A Mintlify `openapi` spec — declared top-level or on a nav group (a path, URL, or `{ source, directory }`) — maps to Blume's [native OpenAPI reference](/docs/advanced/api-reference) (`openapi.sources`), which renders one real page per operation. A group's `directory` becomes the reference's route; endpoint refs like `GET /users` are dropped since Blume generates them from the spec.
-- `docs.json` `variables` are inlined into content — Blume has no runtime `{{variable}}` substitution.
-- Multi-language projects map to [`i18n.locales`](/docs/content/i18n); the language nav selector is dropped in favor of Blume's locale switching.
-- Icons resolve against the real bundled libraries — Font Awesome (free), Lucide, and Tabler. The migrator sets [`icons.library: fontawesome`](/docs/content/components#default-library) (Mintlify's default), so Font Awesome names (`shield-halved`, `gauge-high`, `layer-group`, …) and `iconType` styles render unchanged. Pro-only FA styles (`light`/`thin`/`duotone`/`sharp-solid`) fall back to solid.
-- Fonts map to [`theme.fonts`](/docs/configuration/theming) when the family is one of Blume's curated Google Fonts (`fonts.family`, or a `heading`/`body` split); a family outside that set is warned about, not guessed. Header links (`navbar.links`/`navbar.primary`) and footer socials (`footer.socials`) have no `blume.config` equivalent yet, so they're reported as warnings rather than dropped silently — re-add them with [`navigation.tabs`](/docs/content/navigation) or a Header/Footer [layout override](/docs/advanced/custom-pages). The contextual page menu and last-updated timestamp are already Blume defaults.
-- Field components — [`<ParamField>`, `<ResponseField>`, `<RequestField>`](/docs/content/components#api-fields) — render natively via Blume's compat components, so hand-written CLI/SDK/endpoint field docs carry over unchanged. Any remaining component with no Blume equivalent (e.g. `<Update>`) is flagged for manual review.
-
-:::tip
-Want to preview Blume against a Mintlify codebase **without** rewriting anything? Run `blume dev` with no config and Blume serves `docs.json` as-is in [Bridge mode](/docs/advanced/bridge). Migrate when you're ready to commit.
-:::
-
-### Fumadocs
-
-Reads `content/docs` + `meta.json`. Moves pages into `docs/`, preserving the `/docs` route prefix, and rewrites Fumadocs MDX to Blume markup: callouts, `<Cards>`/`<Accordions>`/`<Files>`, `<Tabs items>`, and `<include>` directives are all converted. Each `meta.json` becomes a typed `meta.ts`.
-
-### Nextra
-
-Reads `content/` or `pages/` plus `_meta` files. Moves pages into `docs/`, rewrites `<Callout>`s to [directives](/docs/content/syntax), and converts every `_meta.{js,ts,json}` into a typed `meta.ts` — navigation order and titles preserved.
-
-### Starlight
-
-Reads `src/content/docs` + your `astro.config.*`. Translates the `starlight({...})` options into `blume.config.ts` and rewrites each page **in place** (content stays under `src/content/docs`): asides become directives, components are renamed, and frontmatter is mapped across.
-
-## After migrating
-
-<Steps>
-  <Step title="Review the config">
-    Open `blume.config.ts` and check the mapped navigation, theme, and site
-    settings. The migrator is thorough but conservative — some source options
-    have no Blume equivalent and are left out.
-  </Step>
-  <Step title="Read the warnings">
-    Each warning points at something the codemod couldn't fully translate. Work
-    through them before shipping.
-  </Step>
-  <Step title="Run the dev server">
-    Serve the migrated site. Blume [validates your content](/docs/reference/cli#validating-links) as it serves it, so broken links, missing anchors, and schema errors surface immediately.
-
-    ```bash
-    blume dev
-    ```
-
-  </Step>
-  <Step title="Delete leftovers">
-    Old framework files (lockfile entries, `astro.config`, `theme.config`,
-    framework dependencies) are left untouched so nothing is lost. Remove them
-    by hand once you've confirmed the site builds.
-  </Step>
-</Steps>
-
-<CardGroup cols={2}>
-  <Card title="Bridge mode" href="/docs/advanced/bridge" icon="cable">
-    Serve a Mintlify project with `blume dev` — no migration, no file changes.
-  </Card>
-  <Card title="CLI reference" href="/docs/reference/cli" icon="terminal">
-    Every command and flag, including `blume migrate`.
-  </Card>
-  <Card title="Content sources" href="/docs/content/sources" icon="folder-tree">
-    How Blume scans content, assets, and remote sources into a site.
-  </Card>
-  <Card title="Frontmatter" href="/docs/reference/frontmatter" icon="file-text">
-    The page schema your migrated frontmatter is mapped onto.
-  </Card>
-</CardGroup>