blume 0.2.0 → 0.4.0

package/src/core/schema.ts

@@ -365,6 +365,13 @@ export type ContentSourceConfig = z.infer<typeof contentSourceSchema>;
 
 const contentConfigSchema = z
   .object({
+    /**
+     * Extra top-level directories (relative to the project root) served as
+     * static assets at the site root, alongside `public/`. Lets projects keep
+     * root-served asset folders in place — e.g. a Mintlify migration keeps
+     * `images/` where it is instead of relocating it under `public/`.
+     */
+    assets: z.array(z.string()).default([]),
     defaultType: z.string().default("doc"),
     exclude: z.array(z.string()).default(["**/_*", "**/.*"]),
     include: z.array(z.string()).default(["**/*.{md,mdx}"]),
@@ -462,38 +469,6 @@ const sidebarVariantSchema = z
   })
   .strict();
 
-const navbarLinkTypeSchema = z.enum(["github", "discord"]);
-
-const navbarLinkSchema = z
-  .object({
-    href: z.string(),
-    icon: iconName.optional(),
-    label: z.string().optional(),
-    type: navbarLinkTypeSchema.optional(),
-  })
-  .strict()
-  .refine((value) => value.label !== undefined || value.type !== undefined, {
-    message: "Navbar links require either label or type.",
-  });
-
-const navbarPrimarySchema = z
-  .object({
-    href: z.string(),
-    label: z.string().optional(),
-    type: z.enum(["button", "github", "discord"]).default("button"),
-  })
-  .strict()
-  .refine((value) => value.label !== undefined || value.type !== "button", {
-    message: "Navbar primary button links require a label.",
-  });
-
-const navbarConfigSchema = z
-  .object({
-    links: z.array(navbarLinkSchema).default([]),
-    primary: navbarPrimarySchema.optional(),
-  })
-  .strict();
-
 const variablesConfigSchema = z
   .record(z.string().regex(/^[A-Za-z0-9-]+$/u), z.string())
   .default({});
@@ -528,12 +503,6 @@ const themeConfigSchema = z
   })
   .strict();
 
-const iconsConfigSchema = z
-  .object({
-    library: z.enum(["fontawesome", "lucide", "tabler"]).default("lucide"),
-  })
-  .strict();
-
 /** Public credentials for the Algolia search backend (sync key is an env var). */
 const algoliaSearchSchema = z
   .object({
@@ -661,56 +630,9 @@ const aiConfigSchema = z
   })
   .strict();
 
-const contextualOptionSchema = z.union([
-  z.string(),
-  z
-    .object({
-      description: z.string().optional(),
-      href: z.string().optional(),
-      icon: iconName.optional(),
-      title: z.string(),
-    })
-    .passthrough(),
-]);
-
-const contextualConfigSchema = z
-  .object({
-    display: z.enum(["header", "toc"]).default("header"),
-    options: z.array(contextualOptionSchema).default([]),
-  })
-  .strict();
-
-const footerConfigSchema = z
-  .object({
-    links: z
-      .array(
-        z
-          .object({
-            header: z.string().optional(),
-            items: z
-              .array(
-                z
-                  .object({
-                    href: z.string(),
-                    label: z.string(),
-                  })
-                  .strict()
-              )
-              .default([]),
-          })
-          .strict()
-      )
-      .max(4)
-      .default([]),
-    socials: z.record(z.string(), z.string()).default({}),
-  })
-  .strict();
-
 const chromeVariantSchema = z
   .object({
     banner: bannerConfigSchema.optional(),
-    footer: footerConfigSchema.optional(),
-    navbar: navbarConfigSchema.optional(),
     path: z.string(),
   })
   .strict();
@@ -980,12 +902,6 @@ const markdownConfigSchema = z
   })
   .strict();
 
-const stylingConfigSchema = z
-  .object({
-    eyebrows: z.enum(["breadcrumbs", "section"]).default("section"),
-  })
-  .strict();
-
 /**
  * A single spec rendered by the API reference (Scalar). `spec` is a local path
  * or an `http(s)` URL; Scalar auto-detects OpenAPI vs AsyncAPI documents.
@@ -1037,6 +953,33 @@ const asyncapiConfigSchema = z
   .strict();
 
 /** Full user-facing config schema. All fields optional with defaults. */
+/**
+ * Table-of-contents config. `true`/`false` toggles it; an object narrows the
+ * heading range. Normalized to `{ enabled, minLevel, maxLevel }` (default: on,
+ * H2–H3, matching the historical hardcoded range).
+ */
+const tocConfigSchema = z
+  .union([
+    z.boolean(),
+    z
+      .object({
+        maxHeadingLevel: z.number().int().min(1).max(6).optional(),
+        minHeadingLevel: z.number().int().min(1).max(6).optional(),
+      })
+      .strict(),
+  ])
+  .default(true)
+  .transform((value) => {
+    if (typeof value === "boolean") {
+      return { enabled: value, maxLevel: 3, minLevel: 2 };
+    }
+    return {
+      enabled: true,
+      maxLevel: value.maxHeadingLevel ?? 3,
+      minLevel: value.minHeadingLevel ?? 2,
+    };
+  });
+
 export const blumeConfigSchema = z
   .object({
     ai: aiConfigSchema.default({}),
@@ -1044,7 +987,6 @@ export const blumeConfigSchema = z
     asyncapi: asyncapiConfigSchema.default({}),
     banner: bannerConfigSchema.optional(),
     content: contentConfigSchema.default({}),
-    contextual: contextualConfigSchema.default({}),
     deployment: deploymentConfigSchema.default({}),
     description: z.string().optional(),
     /**
@@ -1064,23 +1006,20 @@ export const blumeConfigSchema = z
     export: exportConfigSchema.default(false),
     favicon: faviconConfigSchema.optional(),
     feedback: z.boolean().default(true),
-    footer: footerConfigSchema.default({}),
     github: githubConfigSchema.optional(),
     i18n: i18nConfigSchema.optional(),
-    icons: iconsConfigSchema.default({}),
     lastModified: lastModifiedConfigSchema.default(false),
     logo: logoConfigSchema.optional(),
     markdown: markdownConfigSchema.default({}),
     mcp: mcpConfigSchema.default({}),
-    navbar: navbarConfigSchema.default({}),
     navigation: navigationConfigSchema.default({}),
     openapi: openapiConfigSchema.default({}),
     redirects: z.array(redirectSchema).default([]),
     search: searchConfigSchema.default({}),
     seo: seoConfigSchema.default({}),
-    styling: stylingConfigSchema.default({}),
     theme: themeConfigSchema.default({}),
     title: z.string().default("Documentation"),
+    toc: tocConfigSchema,
     variables: variablesConfigSchema,
   })
   .strict();

package/src/core/sources/mdx-remote.ts

@@ -1,5 +1,6 @@
 import { BlumeError } from "../diagnostics.ts";
 import matter from "../frontmatter.ts";
+import type { Diagnostic } from "../types.ts";
 import {
   hashText,
   loadWithCache,
@@ -105,7 +106,7 @@ const enumerateGithub = async (
   github: { owner: string; repo: string; ref: string; path: string },
   include: string[],
   doFetch: typeof fetch
-): Promise<RemoteRef[]> => {
+): Promise<{ refs: RemoteRef[]; truncated: boolean }> => {
   const { owner, repo, ref } = github;
   const base = github.path.replaceAll(/^\/|\/$/gu, "");
   const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${ref}?recursive=1`;
@@ -113,9 +114,12 @@ const enumerateGithub = async (
   if (!res.ok) {
     throw new Error(`${treeUrl} -> ${res.status}`);
   }
-  const body = (await res.json()) as { tree?: GithubTreeEntry[] };
+  const body = (await res.json()) as {
+    tree?: GithubTreeEntry[];
+    truncated?: boolean;
+  };
   const prefix = base ? `${base}/` : "";
-  return (body.tree ?? [])
+  const refs = (body.tree ?? [])
     .filter((node) => node.type === "blob" && node.path.startsWith(prefix))
     .map((node) => node.path.slice(prefix.length))
     .filter((rel) => matchesInclude(rel, include))
@@ -124,6 +128,9 @@ const enumerateGithub = async (
       fetchUrl: `https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${prefix}${rel}`,
       ref: rel,
     }));
+  // GitHub caps the recursive tree response (~100k entries / 7MB) and flags it
+  // with `truncated`; ignoring it would silently import only part of the repo.
+  return { refs, truncated: body.truncated === true };
 };
 
 /**
@@ -139,19 +146,23 @@ export const mdxRemoteSource = (
   const cache = snapshotCache(ctx.cacheDir);
   let snapshot = new Map<string, SourceEntry>();
 
-  const enumerate = async (): Promise<RemoteRef[]> => {
+  const enumerate = async (): Promise<{
+    refs: RemoteRef[];
+    truncated: boolean;
+  }> => {
     if (options.github) {
       return await enumerateGithub(options.github, options.include, doFetch);
     }
     if (options.files && options.url) {
       const base = options.url.replace(/\/$/u, "");
-      return options.files
+      const refs = options.files
         .filter((ref) => matchesInclude(ref, options.include))
         .map((ref) => ({
           editUrl: `${base}/${ref}`,
           fetchUrl: `${base}/${ref}`,
           ref,
         }));
+      return { refs, truncated: false };
     }
     throw new BlumeError({
       code: "BLUME_SOURCE_MISCONFIGURED",
@@ -179,17 +190,52 @@ export const mdxRemoteSource = (
   };
 
   const load = async (): Promise<SourceLoadResult> => {
+    const skipped: Diagnostic[] = [];
     const result = await loadWithCache(
       options.name,
       cache,
       async () => {
-        const refs = await enumerate();
-        return await Promise.all(refs.map(fetchEntry));
+        const { refs, truncated } = await enumerate();
+        if (truncated) {
+          skipped.push({
+            code: "BLUME_SOURCE_TRUNCATED",
+            message: `Source "${options.name}" hit GitHub's tree listing limit; some files were not enumerated. Narrow the source path or split the repo.`,
+            severity: "warning",
+          });
+        }
+        const settled = await Promise.all(
+          refs.map(async (ref) => {
+            try {
+              return await fetchEntry(ref);
+            } catch (error) {
+              skipped.push({
+                code: "BLUME_SOURCE_FETCH_FAILED",
+                message: `Source "${options.name}" skipped "${ref.ref}" (${(error as Error).message}); the rest were imported.`,
+                severity: "warning",
+              });
+              return null;
+            }
+          })
+        );
+        const entries = settled.filter(
+          (entry): entry is SourceEntry => entry !== null
+        );
+        // Only a total wipeout is a hard failure — let loadWithCache fall back
+        // to cache or fail loudly rather than silently importing nothing. A
+        // partial failure keeps the healthy pages and warns about the rest.
+        if (refs.length > 0 && entries.length === 0) {
+          skipped.length = 0;
+          throw new Error(`all ${refs.length} remote file(s) failed to fetch`);
+        }
+        return entries;
       },
       ctx.refresh ?? true
     );
     snapshot = new Map(result.entries.map((entry) => [entry.ref, entry]));
-    return result;
+    return {
+      ...result,
+      diagnostics: [...result.diagnostics, ...skipped],
+    };
   };
 
   const read = async (ref: string): Promise<string> => {

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";
 
@@ -135,8 +137,13 @@ export const extractLinks = (body: string): PageLink[] => {
       if (target === undefined || match.index === undefined) {
         continue;
       }
+      // Locate the target from the `](` boundary rather than searching for the
+      // target text from the match start — otherwise a label that contains the
+      // same text (e.g. `[/a/b](/a/b)`) reports the column inside the label. The
+      // label can't contain `]`, so `](` is unambiguous.
+      const targetOffset = match.index + match[0].indexOf("](") + "](".length;
       links.push({
-        column: line.indexOf(target, match.index) + 1,
+        column: targetOffset + 1,
         line: lineNumber,
         target,
       });
@@ -146,6 +153,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 +224,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 +266,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/notion.ts

@@ -1,3 +1,5 @@
+import { setTimeout as sleep } from "node:timers/promises";
+
 import { join } from "pathe";
 
 import { BlumeError } from "../diagnostics.ts";
@@ -136,6 +138,44 @@ const blockField = (block: NotionBlock): NotionRichText[] =>
   ((block[block.type] as { rich_text?: NotionRichText[] })?.rich_text ??
     []) as NotionRichText[];
 
+const RATE_LIMITED = 429;
+const MAX_RETRIES = 4;
+const BASE_DELAY_MS = 500;
+const SECOND_MS = 1000;
+
+/**
+ * Retry a Notion API call on a `429 rate_limited`, honoring the `Retry-After`
+ * header and otherwise backing off exponentially. A large workspace fans out
+ * many concurrent block-children requests, so without this a single 429 would
+ * reject the batch and abort the whole import.
+ */
+const withNotionRetry = async <T>(call: () => Promise<T>): Promise<T> => {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
+    try {
+      // oxlint-disable-next-line no-await-in-loop -- sequential retry attempts
+      return await call();
+    } catch (error) {
+      lastError = error;
+      const { status } = error as { status?: number };
+      if (status !== RATE_LIMITED || attempt === MAX_RETRIES) {
+        throw error;
+      }
+      const retryAfter = Number(
+        (error as { headers?: Record<string, string> }).headers?.["retry-after"]
+      );
+      const wait =
+        retryAfter > 0 ? retryAfter * SECOND_MS : BASE_DELAY_MS * 2 ** attempt;
+      // oxlint-disable-next-line no-await-in-loop -- back off before retrying
+      await sleep(wait);
+    }
+  }
+  // Unreachable — the loop always returns or rethrows — but keeps types honest.
+  throw lastError instanceof Error
+    ? lastError
+    : new Error("Notion request failed after retries.");
+};
+
 /** Paginate a Notion list endpoint via recursion (no await-in-loop). */
 const collectAll = async <T>(
   page: (cursor?: string) => Promise<NotionList<T>>,
@@ -251,7 +291,9 @@ export const notionSource = (
     blockId: string
   ): Promise<NotionBlock[]> =>
     collectAll((cursor) =>
-      client.blocks.children.list({ block_id: blockId, start_cursor: cursor })
+      withNotionRetry(() =>
+        client.blocks.children.list({ block_id: blockId, start_cursor: cursor })
+      )
     );
 
   // `render` is injected (rather than referenced) so this stays a forward-free
@@ -396,10 +438,12 @@ export const notionSource = (
       async () => {
         const client = await resolveClient();
         const pages = await collectAll((cursor) =>
-          client.databases.query({
-            database_id: options.database,
-            start_cursor: cursor,
-          })
+          withNotionRetry(() =>
+            client.databases.query({
+              database_id: options.database,
+              start_cursor: cursor,
+            })
+          )
         );
         const built = await Promise.all(
           pages.map((page) => toEntry(client, page))

package/src/core/sources/sanity.ts

@@ -140,7 +140,11 @@ export const sanitySource = (
       asString(getPath(doc, fields.slug ?? "slug.current")) ??
       asString(doc._id) ??
       "untitled";
-    const slug = slugify(slugValue) || "untitled";
+    // Fall back to the unique `_id` when a slug (e.g. a non-ASCII `slug.current`)
+    // slugifies to empty, so distinct documents don't all collapse to the same
+    // `untitled.md` ref and silently overwrite each other.
+    const slug =
+      slugify(slugValue) || slugify(asString(doc._id) ?? "") || "untitled";
 
     const data: Record<string, unknown> = {};
     const title = asString(getPath(doc, fields.title ?? "title"));

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/deploy/rss.ts

@@ -1,5 +1,6 @@
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { PageRecord } from "../core/types.ts";
+import { escapeXml } from "./xml.ts";
 
 /** A single feed entry derived from a content page. */
 export interface RssItem {
@@ -85,14 +86,6 @@ export const buildRssFeeds = (project: BlumeProject): RssFeed[] => {
   return feeds;
 };
 
-const escapeXml = (value: string): string =>
-  value
-    .replaceAll("&", "&")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("'", "&apos;");
-
 const renderItem = (item: RssItem): string => {
   const parts = [
     `    <title>${escapeXml(item.title)}</title>`,

package/src/deploy/sitemap.ts

@@ -1,4 +1,16 @@
 import type { BlumeProject } from "../core/project-graph.ts";
+import { escapeXml } from "./xml.ts";
+
+/** A `<lastmod>` element (W3C date) when the page has a valid modified date. */
+const lastmodTag = (value: string | undefined): string => {
+  if (!value) {
+    return "";
+  }
+  const date = new Date(value);
+  return Number.isNaN(date.getTime())
+    ? ""
+    : `<lastmod>${date.toISOString().slice(0, 10)}</lastmod>`;
+};
 
 /**
  * Build a sitemap.xml from the route manifest. Returns null when the sitemap is
@@ -17,7 +29,14 @@ export const buildSitemap = (project: BlumeProject): string | null => {
       (page) =>
         !(page.meta.draft || page.meta.sidebar.hidden || page.meta.seo.noindex)
     )
-    .map((page) => `  <url><loc>${base}${page.route}</loc></url>`)
+    // `<loc>` must be a well-formed, XML-escaped URL: percent-encode the path,
+    // then escape XML metacharacters (notably `&`) so a route like
+    // `/Tips & Tricks` doesn't produce invalid XML that gets the whole sitemap
+    // rejected.
+    .map(
+      (page) =>
+        `  <url><loc>${escapeXml(encodeURI(`${base}${page.route}`))}</loc>${lastmodTag(page.lastModified)}</url>`
+    )
     .toSorted();
 
   return `<?xml version="1.0" encoding="UTF-8"?>

package/src/deploy/xml.ts

@@ -0,0 +1,8 @@
+/** Escape a string for safe inclusion in XML text or attribute content. */
+export const escapeXml = (value: string): string =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");

package/src/markdown/directives.ts

@@ -3,7 +3,8 @@ import type { MdastNode, MdastVisitorContext } from "./mdast.ts";
 
 interface DirectiveNode extends MdastNode {
   attributes?: Record<string, string | null | undefined> | null;
-  children: MdastNode[];
+  // Satteri gives an empty container directive (`:::note\n:::`) `children: null`.
+  children?: MdastNode[] | null;
   name: string;
 }
 
@@ -38,11 +39,18 @@ interface TextNode extends MdastNode {
   value?: string;
 }
 
-/** Concatenate the plain text of a node's immediate phrasing children. */
-const textOf = (node: MdastNode): string =>
-  ((node.children as TextNode[] | undefined) ?? [])
-    .map((child) => child.value ?? "")
-    .join("");
+/**
+ * Concatenate the plain text of a node, recursing through phrasing children so
+ * formatted labels keep every word — `:::note[Read **this**]` yields
+ * `Read this`, not `Read ` (the bolded run dropped).
+ */
+const textOf = (node: MdastNode): string => {
+  const { children } = node as { children?: MdastNode[] };
+  if (children && children.length > 0) {
+    return children.map(textOf).join("");
+  }
+  return (node as TextNode).value ?? "";
+};
 
 /**
  * Satteri MDAST plugin mapping container directives (`:::note`, `:::warning`,
@@ -57,7 +65,7 @@ export const directiveToCalloutPlugin = () => ({
       return;
     }
 
-    const children = [...node.children];
+    const children = [...(node.children ?? [])];
     let title = node.attributes?.title ?? undefined;
 
     // A leading `:::name[Label]` parses to a paragraph flagged `directiveLabel`.