blume 0.5.3 → 0.6.0

package/docs/advanced/migrate.mdx

@@ -1,124 +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.
-- The source `docs.json`/`mint.json` is removed once `blume.config.ts` is safely written. Leaving it around would keep the project a [Bridge mode](/docs/advanced/bridge) candidate — a later run without a Blume config would silently serve the un-migrated Mintlify site.
-- 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>

package/src/astro/static-assets.ts

@@ -1,124 +0,0 @@
-import { createReadStream, existsSync, statSync } from "node:fs";
-import type { Stats } from "node:fs";
-import { cp } from "node:fs/promises";
-import type { IncomingMessage, ServerResponse } from "node:http";
-
-import { extname, join, relative, resolve, sep } from "pathe";
-
-import type { AssetMount } from "../core/assets.ts";
-
-/** Content types for the asset extensions a docs project commonly serves. */
-const MIME_TYPES: Record<string, string> = {
-  ".avif": "image/avif",
-  ".css": "text/css; charset=utf-8",
-  ".gif": "image/gif",
-  ".ico": "image/x-icon",
-  ".jpeg": "image/jpeg",
-  ".jpg": "image/jpeg",
-  ".js": "text/javascript; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".mp4": "video/mp4",
-  ".otf": "font/otf",
-  ".pdf": "application/pdf",
-  ".png": "image/png",
-  ".svg": "image/svg+xml",
-  ".ttf": "font/ttf",
-  ".txt": "text/plain; charset=utf-8",
-  ".webm": "video/webm",
-  ".webp": "image/webp",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-};
-
-const mimeType = (file: string): string =>
-  MIME_TYPES[extname(file).toLowerCase()] ?? "application/octet-stream";
-
-/** Whether `child` is `parent` itself or a path nested under it. */
-const isContained = (parent: string, child: string): boolean => {
-  const rel = relative(parent, child);
-  return rel === "" || (!rel.startsWith("..") && !rel.startsWith(sep));
-};
-
-/** Resolve a request URL to an on-disk file within one of the mounts, if any. */
-const resolveRequest = (url: string, mounts: AssetMount[]): string | null => {
-  let pathname: string;
-  try {
-    pathname = decodeURIComponent(
-      (url.split("?")[0] ?? "").split("#")[0] ?? ""
-    );
-  } catch {
-    // Malformed percent-encoding (`/images/%zz`) throws URIError; treat it as
-    // a plain miss (404) rather than a middleware exception.
-    return null;
-  }
-  for (const mount of mounts) {
-    if (pathname !== mount.url && !pathname.startsWith(`${mount.url}/`)) {
-      continue;
-    }
-    // `.` + rel keeps the join relative so an absolute-looking suffix can't
-    // escape the mount; the containment check rejects `..` traversal outright.
-    const file = resolve(mount.dir, `.${pathname.slice(mount.url.length)}`);
-    if (isContained(mount.dir, file)) {
-      return file;
-    }
-  }
-  return null;
-};
-
-/** `statSync` that returns null instead of throwing on a missing file. */
-const statFile = (file: string): Stats | null => {
-  try {
-    return statSync(file);
-  } catch {
-    return null;
-  }
-};
-
-/**
- * A dev-server middleware that serves `content.assets` mounts (top-level dirs
- * kept in place, e.g. a migrated `images/`) at their site URL. Astro only serves
- * `publicDir` in dev, so without this those references would 404. Non-matching
- * requests, and any path that isn't a real file, fall through to Astro. Stat is
- * synchronous — this is dev-only middleware and mirrors how sirv serves statics.
- */
-export const serveAssetMounts =
-  (mounts: AssetMount[]) =>
-  (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
-    if ((req.method !== "GET" && req.method !== "HEAD") || !req.url) {
-      next();
-      return;
-    }
-    const file = resolveRequest(req.url, mounts);
-    const stats = file ? statFile(file) : null;
-    if (!(file && stats?.isFile())) {
-      next();
-      return;
-    }
-    res.setHeader("Content-Type", mimeType(file));
-    res.setHeader("Content-Length", String(stats.size));
-    if (req.method === "HEAD") {
-      res.end();
-      return;
-    }
-    createReadStream(file).pipe(res);
-  };
-
-/**
- * Copy every asset mount into the build output, mirroring what Astro does with
- * `publicDir`. Runs on `astro:build:done` so in-place asset dirs ship in the
- * final `dist/`. A missing source dir is skipped (it may be referenced but
- * absent); `cp` handles both directories and single files.
- */
-export const copyAssetMounts = async (
-  mounts: AssetMount[],
-  outDir: string
-): Promise<void> => {
-  for (const mount of mounts) {
-    if (!existsSync(mount.dir)) {
-      continue;
-    }
-    const dest = join(outDir, mount.url.replace(/^\/+/u, ""));
-    // oxlint-disable-next-line no-await-in-loop -- sequential fs copies
-    await cp(mount.dir, dest, { recursive: true });
-  }
-};

package/src/cli/commands/migrate.ts

@@ -1,39 +0,0 @@
-import { defineCommand } from "citty";
-
-import { migrators } from "../../migrate/migrate.ts";
-import { logger } from "../log.ts";
-
-const makeMigrateCommand = (source: keyof typeof migrators) =>
-  defineCommand({
-    meta: {
-      description: `Migrate a ${source} project to Blume.`,
-      name: source,
-    },
-    async run() {
-      const root = process.cwd();
-      logger.start(`Migrating ${source} project`);
-      const result = await migrators[source]?.(root);
-      if (!result) {
-        logger.error(`No migrator for ${source}.`);
-        process.exit(1);
-      }
-      logger.success(`Migrated ${result.moved} content file(s).`);
-      for (const warning of result.warnings) {
-        logger.warn(warning);
-      }
-      logger.box("Review blume.config.ts and run `blume dev`.");
-    },
-  });
-
-export const migrateCommand = defineCommand({
-  meta: {
-    description: "Migrate from another docs tool to Blume.",
-    name: "migrate",
-  },
-  subCommands: {
-    fumadocs: makeMigrateCommand("fumadocs"),
-    mintlify: makeMigrateCommand("mintlify"),
-    nextra: makeMigrateCommand("nextra"),
-    starlight: makeMigrateCommand("starlight"),
-  },
-});

package/src/components/content/ApiField.astro

@@ -1,75 +0,0 @@
----
-// Shared field row behind the Mintlify-compat <ParamField>/<ResponseField>/
-// <RequestField> components: a labeled name + type + badges, with the field's
-// description rendered from the slot (which may hold rich MDX, including nested
-// <Expandable> or further fields). Styled to match the native OpenAPI reference
-// rows (src/components/openapi/), so a migrated site reads consistently.
-interface Props {
-  default?: unknown;
-  deprecated?: unknown;
-  location?: string;
-  name?: string;
-  required?: unknown;
-  type?: string;
-}
-
-const {
-  default: defaultValue,
-  deprecated,
-  location,
-  name,
-  required,
-  type,
-} = Astro.props;
-
-// Booleans arrive as MDX shorthand (`required`) or strings (`required="true"`).
-const isTrue = (value: unknown): boolean => value === true || value === "true";
-const hasDefault =
-  defaultValue !== undefined && defaultValue !== null && defaultValue !== "";
-const hasDescription = Astro.slots.has("default");
----
-
-<div class="not-prose my-2 rounded-blume border border-border px-4 py-3">
-  <div class="flex flex-wrap items-baseline gap-x-2 gap-y-1">
-    {name && <code class="font-mono text-foreground text-sm">{name}</code>}
-    {
-      location && (
-        <span class="rounded bg-muted px-1.5 py-0.5 font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide">
-          {location}
-        </span>
-      )
-    }
-    {type && <span class="text-muted-foreground text-xs">{type}</span>}
-    {
-      isTrue(required) && (
-        <span class="font-medium text-[0.625rem] text-red-600 uppercase tracking-wide dark:text-red-400">
-          required
-        </span>
-      )
-    }
-    {
-      isTrue(deprecated) && (
-        <span class="font-medium text-[0.625rem] text-muted-foreground uppercase tracking-wide line-through">
-          deprecated
-        </span>
-      )
-    }
-  </div>
-  {
-    hasDefault && (
-      <div class="mt-1 text-muted-foreground text-xs">
-        Default:{" "}
-        <code class="rounded bg-muted px-1 py-0.5 text-foreground">
-          {String(defaultValue)}
-        </code>
-      </div>
-    )
-  }
-  {
-    hasDescription && (
-      <div class="mt-1.5 text-muted-foreground text-sm [&>:first-child]:mt-0 [&>:last-child]:mb-0">
-        <slot />
-      </div>
-    )
-  }
-</div>

package/src/components/content/ParamField.astro

@@ -1,39 +0,0 @@
----
-// Mintlify-compat <ParamField>. Mintlify encodes the parameter's location in the
-// attribute name (`<ParamField path="id" />`, `query`, `header`, `body`); the
-// attribute's value is the field name. Falls back to a plain `name` prop.
-import ApiField from "./ApiField.astro";
-
-const {
-  body,
-  default: defaultValue,
-  deprecated,
-  header,
-  name,
-  path,
-  query,
-  required,
-  type,
-} = Astro.props;
-
-const locations = [
-  { key: "path", value: path },
-  { key: "query", value: query },
-  { key: "header", value: header },
-  { key: "body", value: body },
-] as const;
-const located = locations.find((entry) => typeof entry.value === "string");
-const fieldName = located ? located.value : name;
-const location = located?.key;
----
-
-<ApiField
-  default={defaultValue}
-  deprecated={deprecated}
-  location={location}
-  name={fieldName}
-  required={required}
-  type={type}
->
-  <slot />
-</ApiField>

package/src/components/content/RequestField.astro

@@ -1,23 +0,0 @@
----
-// Mintlify-compat <RequestField>: same shape as <ResponseField> — a named field
-// (`name`, `type`, `required`, `default`, `deprecated`) with a slotted body.
-import ApiField from "./ApiField.astro";
-
-const {
-  default: defaultValue,
-  deprecated,
-  name,
-  required,
-  type,
-} = Astro.props;
----
-
-<ApiField
-  default={defaultValue}
-  deprecated={deprecated}
-  name={name}
-  required={required}
-  type={type}
->
-  <slot />
-</ApiField>

package/src/components/content/ResponseField.astro

@@ -1,23 +0,0 @@
----
-// Mintlify-compat <ResponseField>: a named field (`name`, `type`, `required`,
-// `default`, `deprecated`) with its description in the slot.
-import ApiField from "./ApiField.astro";
-
-const {
-  default: defaultValue,
-  deprecated,
-  name,
-  required,
-  type,
-} = Astro.props;
----
-
-<ApiField
-  default={defaultValue}
-  deprecated={deprecated}
-  name={name}
-  required={required}
-  type={type}
->
-  <slot />
-</ApiField>

package/src/components/content/Warning.astro

@@ -1,9 +0,0 @@
----
-import Callout from "./Callout.astro";
-
-const { title } = Astro.props;
----
-
-<Callout title={title} type="warning">
-  <slot />
-</Callout>

package/src/core/assets.ts

@@ -1,31 +0,0 @@
-import { join } from "pathe";
-
-/** A static directory served at a URL prefix, in addition to `public/`. */
-export interface AssetMount {
-  /** Absolute filesystem path to the source directory (or file). */
-  dir: string;
-  /** URL path prefix the source is served at, e.g. `/images`. */
-  url: string;
-}
-
-/**
- * Resolve `content.assets` entries (top-level dirs served at the site root,
- * alongside `public/`) to `{ dir, url }` mounts. Shared by the generated Astro
- * runtime (dev middleware + build copy) and by link validation, so all three
- * agree on where a `/images/foo.png` reference resolves on disk.
- *
- * Each entry is normalized to a leading-slash URL and joined to the project
- * root; leading `./` or `/` and any `..` segments are stripped so a mount can't
- * escape the root or collide with the site's own routing prefix.
- */
-export const resolveAssetMounts = (
-  root: string,
-  assets: string[]
-): AssetMount[] =>
-  assets.map((entry) => {
-    const rel = entry
-      .replace(/^[./]+/u, "")
-      .replaceAll(/\.\.\/?/gu, "")
-      .replace(/\/+$/u, "");
-    return { dir: join(root, rel), url: `/${rel}` };
-  });

package/src/core/bridge.ts

@@ -1,102 +0,0 @@
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-
-import { join } from "pathe";
-
-import { assetSegments } from "../migrate/mintlify/assets.ts";
-import { loadMintlifyConfig } from "../migrate/mintlify/config.ts";
-import { mintlifyI18n } from "../migrate/mintlify/i18n.ts";
-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;
-}
-
-const MINTLIFY_CONFIG_FILES = ["docs.json", "mint.json"];
-
-/**
- * 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 const detectMintlifyBridge = async (
-  root: string
-): Promise<BridgeDetection | null> => {
-  const configFile = MINTLIFY_CONFIG_FILES.map((name) => join(root, name)).find(
-    (candidate) => existsSync(candidate)
-  );
-  if (!configFile) {
-    return null;
-  }
-
-  const config = await loadMintlifyConfig(root, configFile);
-
-  // i18n is derived from the raw spec (language dirs), mirroring the migrator.
-  const spec = JSON.parse(await readFile(configFile, "utf-8")) as Record<
-    string,
-    unknown
-  >;
-  const i18n = mintlifyI18n(spec);
-  if (i18n) {
-    config.i18n = i18n;
-    // Language switching is handled by Blume i18n, not a nav selector.
-    if (config.navigation?.selectors) {
-      config.navigation.selectors = config.navigation.selectors.filter(
-        (selector) => selector.kind !== "language"
-      );
-    }
-  }
-
-  const variables = (config.variables as Record<string, string>) ?? {};
-  const root_ = config.content?.root ?? ".";
-  const exclude = config.content?.exclude ?? [];
-
-  // Mintlify serves assets from the project root; the bridge never moves files,
-  // so referenced root-level asset folders (e.g. `images/`) are served in place
-  // via `content.assets` instead. This is the read-only twin of the migrator's
-  // relocation — same referenced segments, just no `public/` move.
-  const assets = assetSegments(config).filter(
-    (segment) => segment !== "public" && existsSync(join(root, segment))
-  );
-
-  return {
-    configFile,
-    raw: {
-      ...config,
-      content: {
-        assets,
-        // Mirror the excludes onto `content.exclude` too: the generated Astro
-        // `docs` collection globs `content.root` (here the project root) and
-        // must skip node_modules/snippets just like the source does.
-        exclude,
-        root: root_,
-        sources: [
-          {
-            configFile,
-            exclude,
-            root: root_,
-            type: "mintlify",
-            variables,
-          },
-        ],
-      },
-      // Globals are inlined into content by the source; drop the top-level copy.
-      variables: undefined,
-    },
-    tool: "mintlify",
-  };
-};