blume 0.1.5 → 0.3.0

package/src/core/sources/normalize.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from "node:fs";
+
 import GithubSlugger from "github-slugger";
 import { extname } from "pathe";
 
@@ -146,6 +148,44 @@ export const extractLinks = (body: string): PageLink[] => {
   return links;
 };
 
+const INLINE_CODE = /`[^`]*`/gu;
+// Double-quoted strings hold JSX attribute values and JSON in `{...}` props; a
+// `<Tag>` written inside prose there (e.g. an "Astro <Font> integration" note)
+// isn't a real usage. Single quotes are left alone so prose apostrophes don't
+// swallow a real tag between two words.
+const DOUBLE_QUOTED = /"[^"]*"/gu;
+const JSX_OPEN = /<(?<tag>[A-Z][A-Za-z0-9]*)/gu;
+
+/**
+ * Capitalized JSX component tags used in an `.mdx` body (`<Callout>`,
+ * `<Tree.File>` → `Tree`). Skips fenced code, inline code, and double-quoted
+ * strings so code samples and prose don't count. Powers the missing-component
+ * diagnostic.
+ */
+export const extractComponentTags = (body: string): string[] => {
+  const tags = new Set<string>();
+  let inFence = false;
+  for (const line of body.split("\n")) {
+    if (CODE_FENCE.test(line.trimStart())) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) {
+      continue;
+    }
+    const clean = line
+      .replaceAll(INLINE_CODE, "")
+      .replaceAll(DOUBLE_QUOTED, "");
+    for (const match of clean.matchAll(JSX_OPEN)) {
+      const tag = match.groups?.tag;
+      if (tag) {
+        tags.add(tag);
+      }
+    }
+  }
+  return [...tags];
+};
+
 const deriveTitle = (
   meta: PageMeta,
   headings: Heading[],
@@ -179,10 +219,19 @@ export const normalizeEntry = (
 
   const result = pageMetaSchema.safeParse(entry.data);
   if (!result.success) {
+    // Source text lets the error carry a line/column into the frontmatter block:
+    // `entry.raw` for non-filesystem sources, else the file itself (read only on
+    // this rare error path, so filesystem entries stay cheap in the happy path).
+    const source =
+      entry.raw ??
+      (entry.sourcePath && existsSync(entry.sourcePath)
+        ? readFileSync(entry.sourcePath, "utf-8")
+        : undefined);
     return {
       diagnostics: diagnosticsFromZod(result.error, {
         code: "BLUME_FRONTMATTER_INVALID",
         file: entry.sourcePath ?? `${ctx.source.name}:${entry.ref}`,
+        source,
       }),
       pages: [],
     };
@@ -212,6 +261,8 @@ export const normalizeEntry = (
   const base = {
     body: staged ? { format, text: entry.raw ?? entry.body.text } : undefined,
     collection: staged ? "staged" : undefined,
+    componentsUsed:
+      format === "mdx" ? extractComponentTags(entry.body.text) : undefined,
     contentType: meta.type ?? ctx.defaultType,
     description: meta.description,
     editUrl: entry.editUrl,

package/src/core/sources/resolve.ts

@@ -3,6 +3,7 @@ import { join } from "pathe";
 import type { ContentSourceConfig, ResolvedConfig } from "../schema.ts";
 import type { ProjectContext } from "../types.ts";
 import { filesystemSource } from "./filesystem.ts";
+import { githubReleasesSource } from "./github-releases.ts";
 import { mdxRemoteSource } from "./mdx-remote.ts";
 import { mintlifySource } from "./mintlify.ts";
 import { notionSource } from "./notion.ts";
@@ -106,6 +107,21 @@ const buildSource = (
       sourceContext(context, name, runtime)
     );
   }
+  if (def.type === "github-releases") {
+    return githubReleasesSource(
+      {
+        drafts: def.drafts,
+        limit: def.limit,
+        name,
+        owner: def.owner,
+        pollInterval: def.pollInterval,
+        prefix: def.prefix,
+        prereleases: def.prereleases,
+        repo: def.repo,
+      },
+      sourceContext(context, name, runtime)
+    );
+  }
   return mdxRemoteSource(
     {
       files: def.files,

package/src/core/types.ts

@@ -113,6 +113,8 @@ export interface PageRecord {
   format: "md" | "mdx";
   /** Internal/asset links discovered in the page (for validation). */
   links: PageLink[];
+  /** Capitalized JSX component tags used in the body (`.mdx` only). */
+  componentsUsed?: string[];
   /** Resolved "last updated" ISO date, when the feature is enabled. */
   lastModified?: string;
 }
@@ -181,8 +183,6 @@ export interface NavSidebarVariant {
 export interface NavChromeVariant {
   path: string;
   banner?: ResolvedConfig["banner"];
-  footer?: ResolvedConfig["footer"];
-  navbar?: ResolvedConfig["navbar"];
 }
 
 /** The complete navigation model derived from the content graph. */

package/src/deploy/redirects.ts

@@ -0,0 +1,43 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+
+/**
+ * Platform redirect files for a static build. Astro already emits redirect HTML
+ * (meta-refresh) pages for `deployment.output: "static"`, but that's a soft
+ * client redirect. These give the host a real HTTP 3xx: Netlify/Cloudflare read
+ * `_redirects`, Vercel reads `vercel.json`, and `blume-redirects.json` is a
+ * structured manifest for anything else (Apache/nginx rules, an edge worker).
+ */
+
+type Redirect = ResolvedConfig["redirects"][number];
+
+/** `_redirects` text (Netlify + Cloudflare Pages): `from to status` per line. */
+export const buildNetlifyRedirects = (redirects: Redirect[]): string =>
+  `${redirects
+    .map((redirect) => `${redirect.from} ${redirect.to} ${redirect.status}`)
+    .join("\n")}\n`;
+
+/** `vercel.json` contents with a `redirects` array (permanent = 301/308). */
+export const buildVercelConfig = (redirects: Redirect[]): string =>
+  `${JSON.stringify(
+    {
+      redirects: redirects.map((redirect) => ({
+        destination: redirect.to,
+        permanent: redirect.status === 301 || redirect.status === 308,
+        source: redirect.from,
+      })),
+    },
+    null,
+    2
+  )}\n`;
+
+/** Structured manifest for hosts that need manual wiring. */
+export const buildRedirectManifest = (redirects: Redirect[]): string =>
+  `${JSON.stringify(
+    redirects.map((redirect) => ({
+      from: redirect.from,
+      status: redirect.status,
+      to: redirect.to,
+    })),
+    null,
+    2
+  )}\n`;

package/src/markdown/index.ts

@@ -128,9 +128,26 @@ const astroCodeClassTransformer = (extra?: string): ShikiTransformer =>
     },
   }) as unknown as ShikiTransformer;
 
+/**
+ * Tag the `<pre>` with `data-language` — raw `codeToHtml` omits it (unlike
+ * Astro's Markdown Shiki), and the theme's code header keys off it. Applied only
+ * on the titled path so a titled standalone block renders the same header bar a
+ * fence would, while header-less panes (e.g. the Component source view) stay
+ * untouched.
+ */
+const languageAttrTransformer = (lang: string): ShikiTransformer =>
+  ({
+    name: "blume:data-language",
+    pre(node: { properties: Record<string, unknown> }) {
+      node.properties.dataLanguage ??= lang;
+    },
+  }) as unknown as ShikiTransformer;
+
 export interface HighlightCodeOptions extends BlumeShikiOptions {
   /** Extra `<pre>` class names, e.g. `blume-source` for a height-capped pane. */
   className?: string;
+  /** Header title (a filename), matching a fence's `title="..."` meta. */
+  title?: string;
 }
 
 /**
@@ -152,10 +169,17 @@ export const highlightCode = async (
     return await codeToHtml(code, {
       defaultColor: false,
       lang,
+      // The code-title transformer reads the fence meta; feeding a `title="..."`
+      // string here gives non-fence callers (e.g. `<CodeBlock title>`) the same
+      // `data-title` header a Markdown fence gets.
+      meta: options.title
+        ? { __raw: `title="${options.title.replaceAll('"', "")}"` }
+        : undefined,
       themes: CODE_THEMES,
       transformers: [
         ...blumeShikiTransformers({ icons: options.icons }),
         astroCodeClassTransformer(options.className),
+        ...(options.title ? [languageAttrTransformer(lang)] : []),
       ],
     });
   } catch {

package/src/migrate/mintlify/config.ts

@@ -579,72 +579,6 @@ const mintlifySelectors = (spec: JsonObject): NavigationSelectors => {
   ].filter((selector) => selector.items.length > 0);
 };
 
-const navbarTypeLabel = (type: string | undefined): string | undefined => {
-  if (type === "github") {
-    return "GitHub";
-  }
-  if (type === "discord") {
-    return "Discord";
-  }
-  return undefined;
-};
-
-const navbarLinkType = (
-  type: string | undefined
-): "github" | "discord" | undefined =>
-  type === "github" || type === "discord" ? type : undefined;
-
-const navbarPrimaryType = (
-  type: string | undefined
-): "button" | "github" | "discord" =>
-  type === "github" || type === "discord" ? type : "button";
-
-const mintlifyNavbar = (value: unknown): NonNullable<BlumeConfig["navbar"]> => {
-  const object = asObject(value);
-  if (!object) {
-    return { links: [] };
-  }
-
-  const links = asArray(object.links).flatMap((item) => {
-    const itemObject = asObject(item);
-    const href = itemObject ? asString(itemObject.href) : undefined;
-    const type = itemObject ? asString(itemObject.type) : undefined;
-    const label = itemObject
-      ? (asString(itemObject.label) ?? navbarTypeLabel(type))
-      : undefined;
-    if (!itemObject || !href || !label) {
-      return [];
-    }
-    return [
-      withoutUndefined({
-        href,
-        icon: asString(itemObject.icon),
-        label,
-        type: navbarLinkType(type),
-      }),
-    ];
-  });
-
-  const primaryObject = asObject(object.primary);
-  const primaryHref = primaryObject ? asString(primaryObject.href) : undefined;
-  const primaryType = primaryObject
-    ? (asString(primaryObject.type) ?? "button")
-    : undefined;
-  const primaryLabel = primaryObject
-    ? (asString(primaryObject.label) ?? navbarTypeLabel(primaryType))
-    : undefined;
-  const primary =
-    primaryObject && primaryHref && primaryLabel
-      ? withoutUndefined({
-          href: primaryHref,
-          label: primaryLabel,
-          type: navbarPrimaryType(primaryType),
-        })
-      : undefined;
-
-  return withoutUndefined({ links, primary });
-};
-
 const mintignorePatterns = async (root: string): Promise<string[]> => {
   try {
     const raw = await readFile(resolve(root, ".mintignore"), "utf-8");
@@ -678,78 +612,6 @@ const mintlifyRedirects = (
     return [{ from, to }];
   });
 
-const mintlifyContextual = (
-  value: unknown
-): NonNullable<BlumeConfig["contextual"]> => {
-  const object = asObject(value);
-  if (!object) {
-    return { options: [] };
-  }
-
-  const display = object.display === "toc" ? "toc" : "header";
-  const options: NonNullable<BlumeConfig["contextual"]>["options"] = [];
-  for (const option of asArray(object.options)) {
-    if (typeof option === "string") {
-      options.push(option);
-      continue;
-    }
-
-    const optionObject = asObject(option);
-    const title = optionObject ? asString(optionObject.title) : undefined;
-    if (!optionObject || !title) {
-      continue;
-    }
-
-    options.push(
-      withoutUndefined({
-        description: asString(optionObject.description),
-        href: asString(optionObject.href),
-        icon: asString(optionObject.icon),
-        title,
-      })
-    );
-  }
-
-  return { display, options };
-};
-
-const mintlifyFooter = (value: unknown): NonNullable<BlumeConfig["footer"]> => {
-  const object = asObject(value);
-  const socials = asObject(object?.socials);
-  const links = asArray(object?.links)
-    .flatMap((group) => {
-      const groupObject = asObject(group);
-      const items = asArray(groupObject?.items).flatMap((item) => {
-        const itemObject = asObject(item);
-        const label = itemObject ? asString(itemObject.label) : undefined;
-        const href = itemObject ? asString(itemObject.href) : undefined;
-        return label && href ? [{ href, label }] : [];
-      });
-      if (!groupObject || items.length === 0) {
-        return [];
-      }
-      return [
-        withoutUndefined({
-          header: asString(groupObject.header),
-          items,
-        }),
-      ];
-    })
-    .slice(0, 4);
-
-  return {
-    links,
-    socials: socials
-      ? Object.fromEntries(
-          Object.entries(socials).flatMap(([label, href]) => {
-            const hrefValue = asString(href);
-            return hrefValue ? [[label, hrefValue]] : [];
-          })
-        )
-      : {},
-  };
-};
-
 const mintlifyLogo = (value: unknown): BlumeConfig["logo"] => {
   if (typeof value === "string") {
     return value;
@@ -826,21 +688,13 @@ const mintlifyChromeVariants = (spec: JsonObject): NavigationChromeVariants => {
     const banner = hasOwn(object, "banner")
       ? mintlifyBanner(object.banner)
       : undefined;
-    const footer = hasOwn(object, "footer")
-      ? mintlifyFooter(object.footer)
-      : undefined;
-    const navbar = hasOwn(object, "navbar")
-      ? mintlifyNavbar(object.navbar)
-      : undefined;
-    if (!banner && !footer && !navbar) {
+    if (!banner) {
       return [];
     }
 
     return [
       withoutUndefined({
         banner,
-        footer,
-        navbar,
         path,
       }),
     ];
@@ -914,19 +768,6 @@ const mintlifyMarkdown = (
   });
 };
 
-const mintlifyStyling = (
-  value: unknown
-): NonNullable<BlumeConfig["styling"]> => {
-  const object = asObject(value);
-  const eyebrows = asString(object?.eyebrows);
-  return withoutUndefined({
-    eyebrows:
-      eyebrows === "breadcrumbs" || eyebrows === "section"
-        ? eyebrows
-        : undefined,
-  });
-};
-
 const mintlifySeo = (value: unknown): NonNullable<BlumeConfig["seo"]> => {
   const object = asObject(value);
   const metatags = asObject(object?.metatags);
@@ -942,17 +783,6 @@ const mintlifySeo = (value: unknown): NonNullable<BlumeConfig["seo"]> => {
   };
 };
 
-const mintlifyIcons = (value: unknown): NonNullable<BlumeConfig["icons"]> => {
-  const object = asObject(value);
-  const library = object?.library;
-  return withoutUndefined({
-    library:
-      library === "fontawesome" || library === "lucide" || library === "tabler"
-        ? library
-        : undefined,
-  });
-};
-
 export const loadMintlifyConfig = async (
   root: string,
   file: string
@@ -993,14 +823,10 @@ export const loadMintlifyConfig = async (
       ],
       root: ".",
     },
-    contextual: mintlifyContextual(spec.contextual),
     description: asString(spec.description),
     favicon: mintlifyFavicon(spec.favicon),
-    footer: mintlifyFooter(spec.footer),
-    icons: mintlifyIcons(spec.icons),
     logo: mintlifyLogo(spec.logo),
     markdown: mintlifyMarkdown(spec.markdown, styling),
-    navbar: mintlifyNavbar(spec.navbar),
     navigation: {
       chromeVariants: mintlifyChromeVariants(spec),
       selectors: mintlifySelectors(spec),
@@ -1016,7 +842,6 @@ export const loadMintlifyConfig = async (
       prompt: asString(search.prompt),
     },
     seo: mintlifySeo(seo),
-    styling: mintlifyStyling(styling),
     theme: {
       accent: asString(colors.primary) ?? "blue",
       accentDark: asString(colors.light),

package/src/migrate/starlight/config.ts

@@ -425,10 +425,6 @@ export const mapStarlightConfig = (
   }
 
   const social = mapSocial(options.social);
-  if (Object.keys(social.socials).length > 0) {
-    config.footer = { socials: social.socials };
-  }
-
   const github = mapEditLink(options.editLink) ?? social.github;
   if (github) {
     config.github = github;

package/src/og/card.ts

@@ -1,5 +1,6 @@
 import { Renderer } from "@takumi-rs/core";
-import { container, text } from "@takumi-rs/helpers";
+import { container, image, text } from "@takumi-rs/helpers";
+import type { Node } from "@takumi-rs/helpers";
 
 // Reuse one renderer (and its loaded default fonts) across all images.
 let renderer: Renderer | null = null;
@@ -24,62 +25,186 @@ const resolveAccent = (accent: string): string =>
   ACCENT_HEX[accent] ?? (accent.startsWith("#") ? accent : "#3b82f6");
 
 export interface OgCardOptions {
+  /** Large headline — the page title. */
   title: string;
-  eyebrow?: string;
+  /** Accent color (named preset or hex) for the fallback brand mark. */
   accent?: string;
+  /** Brand/site name shown in the top-left lockup. */
+  brand?: string;
+  /** Muted subtitle under the headline (usually the site description). */
+  description?: string;
+  /**
+   * Inlined SVG markup of the configured logo (`config.logo.svg`), painted into
+   * the brand lockup. Falls back to an accent mark when absent.
+   */
+  logo?: string;
+  /** Footer-left repository slug, e.g. `owner/repo`. */
+  repo?: string;
+  /** Footer-right site host, e.g. `docs.acme.com`. */
+  site?: string;
 }
 
 const WIDTH = 1200;
 const HEIGHT = 630;
 
+// Light neutral scale mirrored from the docs homepage theme tokens:
+// FOREGROUND = --foreground, MUTED = --muted-foreground, FAINT = that lighter,
+// BORDER = --border.
+const BG = "#fafafa";
+const FOREGROUND = "#0a0a0a";
+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;
+
+// Brand mark sizing: target this height, but scale down so a wide wordmark logo
+// stays within the lockup.
+const MARK_HEIGHT = 32;
+const MARK_MAX_WIDTH = 100;
+const VIEW_BOX = /viewBox="0 0 (?<w>[\d.]+) (?<h>[\d.]+)"/u;
+
+// Render the configured logo as the brand mark. A `currentColor` logo carries
+// no intrinsic color, so it is painted in the foreground to read on the light
+// card, then handed to Takumi as a data URI sized from the SVG's aspect ratio.
+const logoMark = (svg: string): Node => {
+  const painted = svg.replaceAll("currentColor", FOREGROUND);
+  const box = painted.match(VIEW_BOX);
+  const w = Number(box?.groups?.w);
+  const h = Number(box?.groups?.h);
+  let height = MARK_HEIGHT;
+  let width = w && h ? (MARK_HEIGHT * w) / h : MARK_HEIGHT;
+  if (width > MARK_MAX_WIDTH) {
+    height = w && h ? (MARK_MAX_WIDTH * h) / w : MARK_HEIGHT;
+    width = MARK_MAX_WIDTH;
+  }
+  return image({
+    height: Math.round(height),
+    src: `data:image/svg+xml;base64,${Buffer.from(painted).toString("base64")}`,
+    width: Math.round(width),
+  });
+};
+
+// Fallback mark when no SVG logo is configured: an accent tile with the brand's
+// initial, matching the docs favicon aesthetic.
+const initialMark = (accent: string, initial: string): Node =>
+  container({
+    children: initial
+      ? [text(initial, { color: "#ffffff", fontSize: 32, fontWeight: 600 })]
+      : [],
+    style: {
+      alignItems: "center",
+      backgroundColor: accent,
+      borderRadius: 14,
+      display: "flex",
+      height: 60,
+      justifyContent: "center",
+      width: 60,
+    },
+  });
+
+// The headline shrinks as the title grows so it never spills past a couple of
+// lines within the card's content width.
+const titleSize = (title: string): number => {
+  if (title.length > 60) {
+    return 52;
+  }
+  if (title.length > 40) {
+    return 64;
+  }
+  return 76;
+};
+
 /** Render a 1200x630 Open Graph card to a PNG buffer. */
 export const renderOgImage = (options: OgCardOptions): Promise<Buffer> => {
   const accent = resolveAccent(options.accent ?? "blue");
+  const brand = options.brand?.trim();
+  const logo = options.logo?.trim();
+  const initial = brand ? brand.charAt(0).toUpperCase() : "";
+  const description = options.description?.trim();
+  const repo = options.repo?.trim();
+  const site = options.site?.trim();
 
-  const node = container({
+  const header = container({
     children: [
-      container({
-        children: [
-          container({
-            style: {
-              backgroundColor: accent,
-              borderRadius: 6,
-              height: 32,
-              width: 32,
-            },
-          }),
-          options.eyebrow
-            ? text(options.eyebrow, {
-                color: "#94a3b8",
-                fontSize: 30,
-              })
-            : container({}),
-        ],
-        style: { alignItems: "center", display: "flex", gap: 16 },
-      }),
-      text(options.title, {
-        color: "#f8fafc",
-        fontSize: 76,
-        fontWeight: 700,
-        lineHeight: 1.1,
-      }),
-      container({
-        style: {
-          backgroundColor: accent,
-          borderRadius: 4,
-          height: 8,
-          width: 120,
-        },
+      logo ? logoMark(logo) : initialMark(accent, initial),
+      brand
+        ? text(brand, {
+            color: FOREGROUND,
+            fontSize: 30,
+            fontWeight: 500,
+            letterSpacing: "-0.01em",
+          })
+        : container({}),
+    ],
+    style: { alignItems: "center", display: "flex", gap: 18 },
+  });
+
+  const body = container({
+    children: [
+      text(truncate(options.title, 64), {
+        color: FOREGROUND,
+        fontSize: titleSize(options.title),
+        fontWeight: 600,
+        letterSpacing: "-0.03em",
+        lineHeight: 1.05,
+        maxWidth: 1010,
+        textWrap: "balance",
       }),
+      description
+        ? text(truncate(description, 140), {
+            color: MUTED,
+            fontSize: 30,
+            lineHeight: 1.4,
+            marginTop: 28,
+            maxWidth: 900,
+            textWrap: "balance",
+          })
+        : container({}),
     ],
+    style: { display: "flex", flexDirection: "column" },
+  });
+
+  const footer =
+    repo || site
+      ? container({
+          children: [
+            container({
+              style: { backgroundColor: BORDER, height: 1, width: "100%" },
+            }),
+            container({
+              children: [
+                repo
+                  ? text(repo, { color: MUTED, fontSize: 22 })
+                  : container({}),
+                site
+                  ? text(site, { color: FAINT, fontSize: 22 })
+                  : container({}),
+              ],
+              style: {
+                alignItems: "center",
+                display: "flex",
+                justifyContent: "space-between",
+                marginTop: 28,
+                width: "100%",
+              },
+            }),
+          ],
+          style: { display: "flex", flexDirection: "column", width: "100%" },
+        })
+      : container({});
+
+  const node = container({
+    children: [header, body, footer],
     style: {
-      backgroundColor: "#0b1020",
-      color: "#ffffff",
+      backgroundColor: BG,
+      color: FOREGROUND,
       display: "flex",
       flexDirection: "column",
       height: HEIGHT,
       justifyContent: "space-between",
-      padding: 80,
+      padding: 72,
       width: WIDTH,
     },
   });