@writedocs/generator 0.4.8 → 0.4.9

package/src/lib/config.ts

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { createRequire } from 'node:module';
+import { EXCLUDED_TOP_LEVEL_DIRS } from './pages.js';
 import matter from 'gray-matter';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
 import {
@@ -267,92 +267,9 @@ export type IconResolution =
   | { kind: 'image'; src: string } // an image URL or site path, rendered as <img>
   | { kind: 'text'; value: string }; // literal text/emoji, rendered as-is
 
-const DEFAULT_ICON_COLLECTION = 'lucide';
-
-// Where a bare icon name is looked up, in order. Lucide stays first so no
-// existing site's icons change; Font Awesome comes after because it's
-// Mintlify's default library - Mintlify content writes `icon="gear"` or
-// `icon="discord"`, names Lucide doesn't have, and astro-icon fails the
-// whole build on a name it can't find. Solid before brands, same as
-// Mintlify's own lookup.
-const BARE_ICON_COLLECTIONS = [DEFAULT_ICON_COLLECTION, 'fa6-solid', 'fa6-brands'];
-
-// Loaded lazily, once per collection, from the installed @iconify-json/*
-// packages (the same data astro-icon itself renders from). Resolved
-// against this package, not the site being built - WRITEDOCS_PACKAGE_ROOT
-// is set by run-astro.js; outside that subprocess, this file's own URL
-// still sits inside the package.
-interface IconifyCollection {
-  icons?: Record<string, { body: string; width?: number; height?: number }>;
-  aliases?: Record<string, { parent: string; width?: number; height?: number }>;
-  width?: number;
-  height?: number;
-}
-const iconCollections = new Map<string, IconifyCollection | null>();
-function loadIconCollection(collection: string): IconifyCollection | null {
-  if (!iconCollections.has(collection)) {
-    const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT;
-    const require = createRequire(packageRoot ? path.join(packageRoot, 'package.json') : import.meta.url);
-    let data: IconifyCollection | null = null;
-    try {
-      data = require(`@iconify-json/${collection}/icons.json`);
-    } catch {
-      data = null;
-    }
-    iconCollections.set(collection, data);
-  }
-  return iconCollections.get(collection) ?? null;
-}
-function collectionHasIcon(collection: string, name: string): boolean {
-  const data = loadIconCollection(collection);
-  return Boolean(data && (data.icons?.[name] || data.aliases?.[name]));
-}
-
-/** A standalone <svg> for an icon string, or null if it isn't an installed
- *  Iconify icon (emoji/text, or a name no collection has). For the few
- *  places that build HTML outside an Astro component and so can't use
- *  astro-icon's <Icon> - a code block's title bar is built as HAST inside
- *  a Shiki transformer (see shiki-code-block.js). Follows one level of
- *  Iconify alias, which is all the installed collections use. */
-export function iconSvg(icon: string): string | null {
-  const resolved = resolveIcon(icon);
-  if (resolved.kind !== 'iconify') return null;
-  const [collection, name] = resolved.name.split(':');
-  const data = loadIconCollection(collection);
-  if (!data) return null;
-  const alias = data.aliases?.[name];
-  const entry = data.icons?.[alias ? alias.parent : name];
-  if (!entry) return null;
-  const width = entry.width ?? alias?.width ?? data.width ?? 16;
-  const height = entry.height ?? alias?.height ?? data.height ?? 16;
-  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}">${entry.body}</svg>`;
-}
-
-/** Resolves a writedocs.json `icon` string into either an Iconify icon id or
- *  literal text, covering three forms:
- *  - "collection:icon-name" (e.g. "mdi:server", "simple-icons:github")
- *    - used as-is against whatever @iconify-json/* collections are
- *    installed (see astro.config.mjs / package.json).
- *  - a bare name using only letters/digits/hyphens (e.g. "smartphone",
- *    "book-open") - looked up in BARE_ICON_COLLECTIONS order (lucide,
- *    then Font Awesome solid, then brands), using the first collection
- *    that has it. A name none of them has still resolves to "lucide:...",
- *    so the build error names the same collection it always did.
- *  - an image URL or path - "https://...", "//...", "/icons/x.svg",
- *    "./x.png" - rendered as an <img>. Mintlify accepts these for any
- *    icon; before this they were printed as literal text.
- *  - anything else (an emoji, a symbol, arbitrary text) - rendered
- *    verbatim, preserving the original "just paste an emoji" behavior
- *    from before icon-library support existed. */
-export function resolveIcon(icon: string): IconResolution {
-  if (/^(?:https?:)?\/\/|^\.{0,2}\//i.test(icon)) return { kind: 'image', src: icon };
-  if (/^[a-z0-9-]+:[a-z0-9-]+$/i.test(icon)) return { kind: 'iconify', name: icon };
-  if (/^[a-z0-9-]+$/i.test(icon)) {
-    const collection = BARE_ICON_COLLECTIONS.find((c) => collectionHasIcon(c, icon)) ?? DEFAULT_ICON_COLLECTION;
-    return { kind: 'iconify', name: `${collection}:${icon}` };
-  }
-  return { kind: 'text', value: icon };
-}
+// The implementation lives in lib/icons.js - plain JavaScript, because
+// `writedocs validate` loads it with plain Node (see that file's comment).
+export { resolveIcon, iconExists, iconSvg } from './icons.js';
 
 // ---------------------------------------------------------------------
 // OpenAPI navigation expansion - turns a group's `openapi: { src, path }`
@@ -560,59 +477,9 @@ export function loadDocsConfig(contentDir: string): DocsConfig {
 // hand-authored `guides/dist-notes.mdx` isn't mistaken for the build
 // output directory `dist/` just because a folder two levels down happens
 // to also be named `dist`).
-const EXCLUDED_TOP_LEVEL_DIRS = new Set(['node_modules', 'dist', '.astro', '.writedocs', 'public', '.git']);
-
-/** Recursively finds every .md/.mdx file under `contentDir` that has a
- *  frontmatter block, skipping the handful of build/dependency
- *  directories a real content directory tends to also contain (see
- *  EXCLUDED_TOP_LEVEL_DIRS above) - docs/ is scanned exactly like any
- *  other folder, no special-casing. Returns POSIX-relative paths (from
- *  `contentDir`) suitable to hand straight to Astro's `glob()` loader as
- *  a literal `pattern` array - see content.config.ts's `pages`
- *  collection, and [...slug].astro, which needs the identical list to
- *  decide whether calling `getCollection('pages')` is worth doing at all
- *  (see content.config.ts's own comment on why an empty collection still
- *  needs to exist, just backed by a no-op loader, to avoid Astro's "does
- *  not exist or is empty" warning). Also reused directly by
- *  astro.config.mjs's noindex/sitemap scan, so that scan always sees
- *  exactly the same file set that actually becomes a page - no risk of
- *  the two drifting apart. Synchronous and re-run from scratch wherever
- *  it's called rather than cached and shared across modules - consistent
- *  with how loadDocsConfig() itself is already called repeatedly across
- *  this codebase instead of threaded through as shared state, and cheap
- *  enough in practice (a docs site's own file count) not to matter. */
-export function findAllPages(contentDir: string): string[] {
-  const results: string[] = [];
-  function walk(dir: string, relBase: string) {
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      const abs = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
-        walk(abs, rel);
-        continue;
-      }
-      if (!entry.isFile() || !/\.mdx?$/i.test(entry.name)) continue;
-      let raw: string;
-      try {
-        raw = fs.readFileSync(abs, 'utf-8');
-      } catch {
-        continue;
-      }
-      const { data } = matter(raw);
-      if (Object.keys(data).length === 0) continue; // no frontmatter at all - not a page
-      results.push(rel);
-    }
-  }
-  walk(contentDir, '');
-  return results;
-}
+// EXCLUDED_TOP_LEVEL_DIRS and findAllPages() live in lib/pages.js - plain
+// JavaScript, so `writedocs validate` can find a site's pages with plain Node.
+export { findAllPages } from './pages.js';
 
 /** Any `.css`/`.js` file anywhere in the project - root or any subfolder,
  *  `public/` included - auto-loaded site-wide with zero `writedocs.json`

package/src/lib/content-check.js

@@ -0,0 +1,232 @@
+// `writedocs validate`'s content pass: everything in a site's pages that
+// would break the build or silently degrade it, found in one run instead of
+// one build failure at a time. Plain JavaScript, loaded by plain Node from
+// an installed package (see lib/icons.js's comment on why not TypeScript).
+//
+// Errors - the build would fail:
+//   - a page's frontmatter doesn't match the page schema (the same
+//     pageFrontmatterSchema the build uses) or isn't valid YAML
+//   - an .mdx file doesn't parse as MDX
+//   - writedocs.json's navigation lists a page that doesn't exist
+// Warnings - the build succeeds, but not as written:
+//   - an unknown component (the build shows only its content - see
+//     lib/mdx-unknown-components.js)
+//   - an icon name no installed icon set has (the build leaves it out -
+//     see AppIcon.astro), in a component's `icon`, a page's `icon`, or
+//     writedocs.json
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { visit } from 'unist-util-visit';
+import { findAllPages, fileIdForPath } from './pages.js';
+import { iconExists } from './icons.js';
+import { findUnknownComponents } from './mdx-unknown-components.js';
+import { pageFrontmatterSchema, createJsonLocator } from './config-schema.js';
+
+/** An issue: { file, line?, message, suggestion? } - `file` relative to the
+ *  content directory, POSIX slashes. */
+function issue(file, line, message, suggestion) {
+  return { file, line, message, suggestion };
+}
+
+function lineOfFrontmatterKey(frontmatterText, key) {
+  const lines = frontmatterText.split('\n');
+  const re = new RegExp(`^["']?${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']?\\s*:`);
+  const i = lines.findIndex((l) => re.test(l));
+  // +2: the opening `---` line, and 1-based numbering.
+  return i === -1 ? 2 : i + 2;
+}
+
+function unknownIconMessage(icon) {
+  return {
+    message: `Unknown icon "${icon}" - no installed icon set has it, so the build leaves it out.`,
+    suggestion:
+      'Use a Lucide or Font Awesome (free) name, a "collection:name" pair such as "mdi:server", an emoji, or an image path.',
+  };
+}
+
+let mdxProcessor = null;
+async function parseMdx(text) {
+  if (!mdxProcessor) {
+    const { createProcessor } = await import('@mdx-js/mdx');
+    mdxProcessor = createProcessor({ format: 'mdx' });
+  }
+  return mdxProcessor.parse(text);
+}
+
+async function checkPage(contentDir, rel, errors, warnings) {
+  const raw = fs.readFileSync(path.join(contentDir, rel), 'utf-8').replace(/\r\n/g, '\n');
+  let parsed;
+  try {
+    // An options object bypasses gray-matter's cache, which keeps an empty
+    // result even for input that threw - findAllPages() already parsed
+    // this file once, so the cache would hide a YAML error here.
+    parsed = matter(raw, {});
+  } catch (err) {
+    // gray-matter hands js-yaml the frontmatter with its leading newline, so
+    // js-yaml's 0-based line is already one past the opening `---`.
+    const line = typeof err?.mark?.line === 'number' ? err.mark.line + 1 : 1;
+    errors.push(issue(rel, line, `The frontmatter isn't valid YAML: ${err.reason ?? err.message}`, 'A value containing ": " must be quoted.'));
+    return;
+  }
+
+  // The frontmatter's own text, for line numbers - read from the file, not
+  // gray-matter's `matter` property, which is missing on the results it
+  // returns from its cache (findAllPages() already parsed every page once).
+  const frontmatterText = raw.match(/^---[^\n]*\n([\s\S]*?)\n---/)?.[1] ?? '';
+
+  // Frontmatter against the same schema the build uses.
+  const result = pageFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    for (const i of result.error.issues) {
+      const key = String(i.path[0] ?? '');
+      const where = i.path.length ? `\`${i.path.join('.')}\`: ` : '';
+      errors.push(issue(rel, key ? lineOfFrontmatterKey(frontmatterText, key) : 2, `Frontmatter ${where}${i.message}`));
+    }
+  }
+  if (typeof parsed.data.icon === 'string' && !iconExists(parsed.data.icon)) {
+    const { message, suggestion } = unknownIconMessage(parsed.data.icon);
+    warnings.push(issue(rel, lineOfFrontmatterKey(frontmatterText, 'icon'), message, suggestion));
+  }
+
+  // The rest only applies to MDX - a .md page is plain Markdown, no JSX.
+  if (!/\.mdx$/i.test(rel) || !parsed.content.trim()) return;
+  const bodyStart = raw.lastIndexOf(parsed.content);
+  const lineOffset = bodyStart > 0 ? raw.slice(0, bodyStart).split('\n').length - 1 : 0;
+  let tree;
+  try {
+    tree = await parseMdx(parsed.content);
+  } catch (err) {
+    // Some MDX errors carry their position only inside the message, as
+    // "(line:column-line:column)".
+    const fromReason = /\((\d+):\d+(?:-\d+:\d+)?\)/.exec(err.reason ?? '')?.[1];
+    const line = err.line ?? err.place?.start?.line ?? err.place?.line ?? (fromReason ? Number(fromReason) : undefined);
+    errors.push(
+      issue(
+        rel,
+        line ? line + lineOffset : undefined,
+        // The position in the message counts from the end of the
+        // frontmatter; the file:line above is the real one.
+        `This page doesn't parse as MDX: ${String(err.reason ?? err.message).replace(/\s*\(\d+:\d+(?:-\d+:\d+)?\)$/, '')}`
+      )
+    );
+    return;
+  }
+  for (const { name, line } of findUnknownComponents(tree)) {
+    warnings.push(
+      issue(
+        rel,
+        line ? line + lineOffset : undefined,
+        `Unknown component <${name}> - the build shows only its content.`,
+        'Remove it, use a writedocs component instead, or define it in a snippet.'
+      )
+    );
+  }
+  visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
+    const attr = node.attributes?.find((a) => a.type === 'mdxJsxAttribute' && a.name === 'icon');
+    if (!attr || typeof attr.value !== 'string' || iconExists(attr.value)) return;
+    const { message, suggestion } = unknownIconMessage(attr.value);
+    const line = node.position?.start?.line;
+    warnings.push(issue(rel, line ? line + lineOffset : undefined, message, suggestion));
+  });
+}
+
+/** Every page a navigation references: strings inside arrays, and `page`
+ *  fields (a group's own page). Returns [{ id, path }] with the JSON path
+ *  for line lookup. */
+function navigationReferences(navigation) {
+  const refs = [];
+  (function walk(node, trail) {
+    if (Array.isArray(node)) {
+      node.forEach((item, i) => {
+        if (typeof item === 'string') refs.push({ id: item, path: [...trail, i] });
+        else walk(item, [...trail, i]);
+      });
+    } else if (node && typeof node === 'object') {
+      for (const [key, value] of Object.entries(node)) {
+        if (key === 'page' && typeof value === 'string') refs.push({ id: value, path: [...trail, key] });
+        else if (key !== 'openapi' && key !== 'href') walk(value, [...trail, key]);
+      }
+    }
+  })(navigation, ['navigation']);
+  return refs;
+}
+
+/** Every `icon` string in writedocs.json, plus the `socials` keys (each
+ *  one doubles as its icon - see SiteFooter.astro). */
+function configIcons(config) {
+  const found = [];
+  (function walk(node, trail) {
+    if (Array.isArray(node)) node.forEach((item, i) => walk(item, [...trail, i]));
+    else if (node && typeof node === 'object') {
+      for (const [key, value] of Object.entries(node)) {
+        if (key === 'icon' && typeof value === 'string') found.push({ icon: value, path: [...trail, key] });
+        else walk(value, [...trail, key]);
+      }
+    }
+  })(config, []);
+  if (config?.socials && typeof config.socials === 'object') {
+    for (const key of Object.keys(config.socials)) found.push({ icon: key, path: ['socials', key] });
+  }
+  return found;
+}
+
+/**
+ * Checks a content directory. `configText` is writedocs.json's raw text, or
+ * null when it isn't valid JSON (then only the pages themselves are
+ * checked). Returns { pages, errors, warnings }.
+ */
+export async function checkContent(contentDir, configText) {
+  const errors = [];
+  const warnings = [];
+  const pages = findAllPages(contentDir);
+  for (const rel of pages) await checkPage(contentDir, rel, errors, warnings);
+
+  let config = null;
+  if (configText !== null) {
+    try {
+      config = JSON.parse(configText);
+    } catch {
+      config = null;
+    }
+  }
+  if (config) {
+    const locate = createJsonLocator(configText);
+    const ids = new Set(pages.map(fileIdForPath));
+    for (const ref of navigationReferences(config.navigation)) {
+      if (ids.has(ref.id)) continue;
+      const withoutFrontmatter = ['.mdx', '.md'].some((ext) => fs.existsSync(path.join(contentDir, `${ref.id}${ext}`)));
+      errors.push(
+        issue(
+          'writedocs.json',
+          locate(ref.path)?.line,
+          `The navigation lists page "${ref.id}", but there's no page with that path.`,
+          withoutFrontmatter
+            ? `${ref.id} exists but has no frontmatter, so it isn't a page - add a frontmatter block with at least a title.`
+            : `Create ${ref.id}.mdx, or fix the path (it's relative to the folder writedocs.json is in, without the extension).`
+        )
+      );
+    }
+    for (const { icon, path: jsonPath } of configIcons(config)) {
+      if (iconExists(icon)) continue;
+      const { message, suggestion } = unknownIconMessage(icon);
+      warnings.push(issue('writedocs.json', locate(jsonPath)?.line, message, suggestion));
+    }
+  }
+
+  const byLocation = (a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0);
+  errors.sort(byLocation);
+  warnings.sort(byLocation);
+  return { pages: pages.length, errors, warnings };
+}
+
+/** Same layout as formatValidationIssuesDetailed() for writedocs.json. */
+export function formatContentIssues(issues) {
+  return issues
+    .map((i) => {
+      const lines = [`  ${i.file}${i.line ? `:${i.line}` : ''}`, `    ${i.message}`];
+      if (i.suggestion) lines.push(`    ${i.suggestion}`);
+      return lines.join('\n');
+    })
+    .join('\n\n');
+}

package/src/lib/icons.js

@@ -0,0 +1,109 @@
+// Icon strings - writedocs.json's `icon` fields (TabItem, DropdownItem,
+// ProductItem, Card, ...) and every component/frontmatter `icon` prop - are
+// plain strings with no schema-level distinction between "an emoji, paste
+// it verbatim", "an image path" and "an icon-set name, look it up".
+// Resolved here rather than validated in the schema, since all are valid
+// uses of the same string field and the right rendering only becomes
+// obvious once you look at the value's shape.
+//
+// Plain JavaScript, not TypeScript, on purpose: `writedocs validate` loads
+// this with plain Node to check icon names, and Node refuses to strip types
+// from any file under node_modules - so a .ts version would work from the
+// checkout and fail for everyone who installs the package. lib/config.ts
+// re-exports these for everything that runs inside Astro.
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const DEFAULT_ICON_COLLECTION = 'lucide';
+
+// Where a bare icon name is looked up, in order. Lucide stays first so no
+// existing site's icons change; Font Awesome comes after because it's
+// Mintlify's default library - Mintlify content writes `icon="gear"` or
+// `icon="discord"`, names Lucide doesn't have. Solid before brands, same as
+// Mintlify's own lookup.
+const BARE_ICON_COLLECTIONS = [DEFAULT_ICON_COLLECTION, 'fa6-solid', 'fa6-brands'];
+
+// Loaded lazily, once per collection, from the installed @iconify-json/*
+// packages (the same data astro-icon itself renders from). Resolved
+// against this package, not the site being built - WRITEDOCS_PACKAGE_ROOT
+// is set by run-astro.js; outside that subprocess, this file's own URL
+// still sits inside the package.
+const iconCollections = new Map();
+function loadIconCollection(collection) {
+  if (!iconCollections.has(collection)) {
+    const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT;
+    const require = createRequire(packageRoot ? path.join(packageRoot, 'package.json') : import.meta.url);
+    let data = null;
+    try {
+      data = require(`@iconify-json/${collection}/icons.json`);
+    } catch {
+      data = null;
+    }
+    iconCollections.set(collection, data);
+  }
+  return iconCollections.get(collection) ?? null;
+}
+function collectionHasIcon(collection, name) {
+  const data = loadIconCollection(collection);
+  return Boolean(data && (data.icons?.[name] || data.aliases?.[name]));
+}
+
+/** Resolves an icon string into an Iconify icon id, an image, or literal
+ *  text, covering four forms:
+ *  - "collection:icon-name" (e.g. "mdi:server", "simple-icons:github")
+ *    - used as-is against whatever @iconify-json/* collections are
+ *    installed (see astro.config.mjs / package.json).
+ *  - a bare name using only letters/digits/hyphens (e.g. "smartphone",
+ *    "book-open") - looked up in BARE_ICON_COLLECTIONS order (lucide,
+ *    then Font Awesome solid, then brands), using the first collection
+ *    that has it. A name none of them has resolves to "lucide:..." -
+ *    iconExists() is how callers tell it doesn't exist.
+ *  - an image URL or path - "https://...", "//...", "/icons/x.svg",
+ *    "./x.png" - rendered as an <img>. Mintlify accepts these for any
+ *    icon.
+ *  - anything else (an emoji, a symbol, arbitrary text) - rendered
+ *    verbatim, preserving the original "just paste an emoji" behavior
+ *    from before icon-library support existed.
+ *
+ *  Returns { kind: 'iconify', name } | { kind: 'image', src } | { kind: 'text', value }. */
+export function resolveIcon(icon) {
+  if (/^(?:https?:)?\/\/|^\.{0,2}\//i.test(icon)) return { kind: 'image', src: icon };
+  if (/^[a-z0-9-]+:[a-z0-9-]+$/i.test(icon)) return { kind: 'iconify', name: icon };
+  if (/^[a-z0-9-]+$/i.test(icon)) {
+    const collection = BARE_ICON_COLLECTIONS.find((c) => collectionHasIcon(c, icon)) ?? DEFAULT_ICON_COLLECTION;
+    return { kind: 'iconify', name: `${collection}:${icon}` };
+  }
+  return { kind: 'text', value: icon };
+}
+
+/** False only for an icon *name* that no installed collection has (e.g.
+ *  "gearz", or "mdi:not-a-real-icon") - text, emoji and image icons always
+ *  exist, as far as this can tell. astro-icon fails the whole build on a
+ *  missing name, so AppIcon.astro checks this first and renders nothing
+ *  (with a warning) instead; `writedocs validate` reports the same names. */
+export function iconExists(icon) {
+  const resolved = resolveIcon(icon);
+  if (resolved.kind !== 'iconify') return true;
+  const [collection, name] = resolved.name.split(':');
+  return collectionHasIcon(collection, name);
+}
+
+/** A standalone <svg> for an icon string, or null if it isn't an installed
+ *  Iconify icon (emoji/text, or a name no collection has). For the few
+ *  places that build HTML outside an Astro component and so can't use
+ *  astro-icon's <Icon> - a code block's title bar is built as HAST inside
+ *  a Shiki transformer (see shiki-code-block.js). Follows one level of
+ *  Iconify alias, which is all the installed collections use. */
+export function iconSvg(icon) {
+  const resolved = resolveIcon(icon);
+  if (resolved.kind !== 'iconify') return null;
+  const [collection, name] = resolved.name.split(':');
+  const data = loadIconCollection(collection);
+  if (!data) return null;
+  const alias = data.aliases?.[name];
+  const entry = data.icons?.[alias ? alias.parent : name];
+  if (!entry) return null;
+  const width = entry.width ?? alias?.width ?? data.width ?? 16;
+  const height = entry.height ?? alias?.height ?? data.height ?? 16;
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${width} ${height}">${entry.body}</svg>`;
+}

package/src/lib/mdx-inject-builtins.js

@@ -7,7 +7,7 @@ import { parse as acornParse } from 'acorn';
 // literal list rather than importing that map here, since this runs inside
 // astro.config.mjs's markdown pipeline, a different module graph than
 // [...slug].astro's own.
-const BUILTIN_COMPONENT_NAMES = [
+export const BUILTIN_COMPONENT_NAMES = [
   'Callout',
   'Note',
   'Info',

package/src/lib/mdx-unknown-components.js

@@ -0,0 +1,96 @@
+import path from 'node:path';
+import { visit } from 'unist-util-visit';
+import { BUILTIN_COMPONENT_NAMES } from './mdx-inject-builtins.js';
+
+// Which JSX elements in an MDX file are components writedocs can't resolve
+// - neither a built-in nor something the file imports or defines itself.
+// MDX fails the whole build on one ("Expected component `X` to be
+// defined"), which turned every custom component in a migrated Mintlify
+// project into a build-breaking hunt, one component per build. Shared by
+// the build (remarkUnknownComponentFallback below) and `writedocs
+// validate` (lib/content-check.js), so both agree on exactly which
+// elements are unknown. Plain JavaScript so validate can load it with
+// plain Node.
+
+// Dotted built-ins: the root and the parts it has (see
+// src/components/compound.ts). `<Tree.Leaf>` is unknown even though
+// `Tree` isn't.
+const BUILTIN_MEMBERS = {
+  Tree: ['Folder', 'File'],
+  FileTree: ['Folder', 'File'],
+  Color: ['Row', 'Item'],
+  GitHub: ['Repo'],
+};
+
+function localBindings(tree) {
+  const names = new Set();
+  visit(tree, 'mdxjsEsm', (node) => {
+    for (const stmt of node.data?.estree?.body ?? []) {
+      if (stmt.type === 'ImportDeclaration') {
+        for (const s of stmt.specifiers) if (s.local?.name) names.add(s.local.name);
+      } else if (stmt.type === 'ExportNamedDeclaration') {
+        const decl = stmt.declaration;
+        if (decl?.type === 'VariableDeclaration') {
+          for (const d of decl.declarations) if (d.id?.type === 'Identifier') names.add(d.id.name);
+        } else if (decl?.id?.name) {
+          names.add(decl.id.name); // export function X / export class X
+        }
+        for (const s of stmt.specifiers ?? []) if (s.exported?.name) names.add(s.exported.name);
+      }
+    }
+  });
+  return names;
+}
+
+/** Every JSX element in an MDX tree that names a component this file can't
+ *  resolve, in document order: [{ node, name, line, column }]. Lowercase
+ *  names are plain HTML elements and never count. */
+export function findUnknownComponents(tree) {
+  const bound = localBindings(tree);
+  const unknown = [];
+  visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
+    if (!node.name) return; // a fragment, <>...</>
+    const [root, ...members] = node.name.split('.');
+    if (!/^[A-Z]/.test(root)) return; // <div>, <svg>, <foo.bar> - HTML or a lowercase member expression
+    if (bound.has(root)) return;
+    if (BUILTIN_COMPONENT_NAMES.includes(root)) {
+      if (members.length === 0) return;
+      if (members.length === 1 && BUILTIN_MEMBERS[root]?.includes(members[0])) return;
+    }
+    unknown.push({
+      node,
+      name: node.name,
+      line: node.position?.start?.line,
+      column: node.position?.start?.column,
+    });
+  });
+  return unknown;
+}
+
+/**
+ * Remark plugin: an unknown component renders its children and nothing
+ * else - the element becomes a fragment - with a warning naming the file
+ * and line, instead of failing the build. The site still builds and reads
+ * sensibly (the component's text is still there), and the warning, plus
+ * `writedocs validate`, say what to fix.
+ */
+export function remarkUnknownComponentFallback() {
+  return (tree, file) => {
+    const found = findUnknownComponents(tree);
+    if (found.length === 0) return;
+    const contentDir = process.env.WRITEDOCS_CONTENT_DIR;
+    const filePath = file.path
+      ? contentDir
+        ? path.relative(contentDir, file.path).split(path.sep).join('/')
+        : file.path
+      : '(unknown file)';
+    for (const { node, name, line } of found) {
+      console.warn(
+        `[writedocs] ${filePath}${line ? `:${line}` : ''} - unknown component <${name}>, showing only its content. ` +
+          'Remove it, or define it in a snippet.'
+      );
+      node.name = null;
+      node.attributes = [];
+    }
+  };
+}