@writedocs/generator 0.4.9 → 0.4.10

package/src/lib/mintlify-convert.js

@@ -0,0 +1,599 @@
+// Converts a Mintlify docs.json into a writedocs.json - `writedocs convert
+// --mintlify` (src/cli/convert.js). Plain JavaScript so the CLI can load it
+// from an installed package (see lib/icons.js's comment).
+//
+// convertMintlifyConfig() is a pure function: Mintlify config in, writedocs
+// config plus a list of notes out. A note is anything that couldn't be
+// carried over as-is - dropped, approximated, or needing a manual step - so
+// the author gets one complete list instead of discovering each difference
+// on their own. loadMintlifyConfig() reads docs.json from disk and resolves
+// its `$ref`s first.
+import fs from 'node:fs';
+import path from 'node:path';
+import { iconExists } from './icons.js';
+
+// ---------------------------------------------------------------------
+// Reading docs.json
+// ---------------------------------------------------------------------
+
+/** Reads a Mintlify docs.json and resolves every `$ref` in it, the way
+ *  Mintlify does: a `$ref` is a path to another JSON file, relative to the
+ *  file it's in; an object reference is merged under any sibling keys (the
+ *  siblings win); a non-object reference replaces the whole value. */
+export function loadMintlifyConfig(file) {
+  const root = path.dirname(path.resolve(file));
+  const seen = new Set();
+  function readJson(p) {
+    const abs = path.resolve(p);
+    if (seen.has(abs)) throw new Error(`Circular $ref: ${path.relative(root, abs)}`);
+    seen.add(abs);
+    try {
+      return resolve(JSON.parse(fs.readFileSync(abs, 'utf-8')), path.dirname(abs));
+    } finally {
+      seen.delete(abs);
+    }
+  }
+  function resolve(value, dir) {
+    if (Array.isArray(value)) return value.map((v) => resolve(v, dir));
+    if (!value || typeof value !== 'object') return value;
+    if (typeof value.$ref === 'string') {
+      const target = readJson(path.join(dir, value.$ref));
+      const { $ref, ...siblings } = value;
+      if (target && typeof target === 'object' && !Array.isArray(target)) {
+        return { ...target, ...resolve(siblings, dir) };
+      }
+      return target;
+    }
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolve(v, dir)]));
+  }
+  return readJson(file);
+}
+
+// ---------------------------------------------------------------------
+// Notes
+// ---------------------------------------------------------------------
+
+function pathString(trail) {
+  return trail.reduce((s, part) => (typeof part === 'number' ? `${s}[${part}]` : s ? `${s}.${part}` : part), '');
+}
+
+class Notes {
+  constructor() {
+    this.byKey = new Map();
+  }
+  /** `key` groups repeats of the same kind of note into one entry. */
+  add(key, trail, message, suggestion) {
+    const where = pathString(trail);
+    const existing = this.byKey.get(key);
+    if (existing) existing.where.push(where);
+    else this.byKey.set(key, { where: [where], message, suggestion });
+  }
+  list() {
+    return [...this.byKey.values()];
+  }
+}
+
+// ---------------------------------------------------------------------
+// Navigation
+// ---------------------------------------------------------------------
+
+const ENDPOINT_RE = /^(?:(\S+?\.(?:json|ya?ml))\s+)?(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|WEBHOOK)\s+\S+/i;
+
+// Structural keys, handled for every navigation item - anything else on an
+// item that isn't in that item type's own list below is reported.
+const STRUCTURAL = ['pages', 'groups', 'tabs', 'anchors', 'dropdowns', 'products', 'versions', 'languages', 'menu', 'href', 'openapi', 'hidden'];
+
+const LANGUAGE_NAMES = {
+  ar: 'العربية', ca: 'Català', cn: '简体中文', 'zh-Hant': '繁體中文', cs: 'Čeština', da: 'Dansk', de: 'Deutsch',
+  en: 'English', es: 'Español', fi: 'Suomi', fr: 'Français', 'fr-CA': 'Français (Canada)', he: 'עברית',
+  hi: 'हिन्दी', hu: 'Magyar', id: 'Bahasa Indonesia', it: 'Italiano', ja: '日本語', 'ja-JP': '日本語', jp: '日本語',
+  ko: '한국어', lv: 'Latviešu', nl: 'Nederlands', no: 'Norsk', pl: 'Polski', pt: 'Português', 'pt-BR': 'Português (Brasil)',
+  ro: 'Română', ru: 'Русский', sv: 'Svenska', tr: 'Türkçe', uk: 'Українська', uz: 'Oʻzbek', vi: 'Tiếng Việt', zh: '中文',
+};
+
+function slugify(value) {
+  return String(value)
+    .toLowerCase()
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'api';
+}
+
+/** A Mintlify page reference as a writedocs page id: no leading slash, no
+ *  extension, and a folder's index page by the folder's path ("cli/index"
+ *  -> "cli") - which is how writedocs ids index pages (fileIdForPath() in
+ *  lib/pages.js). */
+function pagePath(ref) {
+  return String(ref).trim().replace(/^\.?\//, '').replace(/\.mdx?$/i, '').replace(/\/index$/, '');
+}
+
+class NavConverter {
+  constructor(notes, defaultSpec) {
+    this.notes = notes;
+    this.defaultSpec = defaultSpec;
+    this.usedApiPaths = new Set();
+  }
+
+  /** An OpenAPI reference as writedocs can use it: a local file path, or
+   *  null (with a note) when it's a URL or missing. */
+  spec(value, trail) {
+    let src = value;
+    if (Array.isArray(src)) {
+      if (src.length > 1) {
+        this.notes.add('openapi-multi', trail, 'More than one OpenAPI spec on one navigation item - only the first is used.', 'Split the item so each spec has its own group.');
+      }
+      src = src[0];
+    }
+    if (src && typeof src === 'object') src = src.source;
+    if (typeof src !== 'string' || !src.trim()) return null;
+    if (/^https?:\/\//i.test(src)) {
+      this.notes.add('openapi-url', trail, `OpenAPI spec is a URL (${src}) - writedocs reads specs from files in the project.`, 'Download the spec into the project, then add an openapi group for it: { "group": "...", "openapi": { "src": "spec.json", "path": "/api" } }.');
+      return null;
+    }
+    return src.trim().replace(/^\.?\//, '');
+  }
+
+  apiPath(name) {
+    const base = `/${slugify(name)}`;
+    let candidate = base;
+    for (let n = 2; this.usedApiPaths.has(candidate); n++) candidate = `${base}-${n}`;
+    this.usedApiPaths.add(candidate);
+    return candidate;
+  }
+
+  openapiGroup(name, src) {
+    return { group: name, openapi: { src, path: this.apiPath(name) } };
+  }
+
+  reportExtraKeys(item, own, kind, trail) {
+    for (const key of Object.keys(item)) {
+      if (own.includes(key) || STRUCTURAL.includes(key)) continue;
+      this.notes.add(`nav-key:${kind}:${key}`, [...trail, key], `\`${key}\` on ${kind}s has no writedocs equivalent - dropped.`);
+    }
+  }
+
+  /** A Mintlify navigation node's children, as writedocs children
+   *  ({ pages } | { tabs } | ... | { href }), or null if it has none. */
+  children(node, trail, spec) {
+    const ownSpec = node.openapi !== undefined ? this.spec(node.openapi, [...trail, 'openapi']) : spec;
+    if (node.pages || node.groups) {
+      const pages = [
+        ...this.items(node.pages ?? [], [...trail, 'pages'], ownSpec),
+        ...this.items(node.groups ?? [], [...trail, 'groups'], ownSpec),
+      ];
+      return { pages };
+    }
+    if (node.tabs) return this.list('tabs', node.tabs, [...trail, 'tabs'], ownSpec, (t, tr) => this.container(t, tr, ownSpec, 'tab', 'tab', ['tab', 'icon']));
+    if (node.anchors) {
+      this.notes.add('anchors', [...trail, 'anchors'], "Anchors became tabs - writedocs has no sidebar anchors.", 'For a plain external link, a global dropdown or a topbar link may fit better.');
+      return this.list('tabs', node.anchors, [...trail, 'anchors'], ownSpec, (a, tr) => this.container({ ...a, tab: a.anchor, anchor: undefined }, tr, ownSpec, 'tab', 'anchor', ['tab', 'anchor', 'icon']));
+    }
+    if (node.menu) {
+      this.notes.add('menu', [...trail, 'menu'], "A tab's or product's menu became a list of dropdowns inside it.");
+      return this.list('dropdowns', node.menu, [...trail, 'menu'], ownSpec, (m, tr) => this.container({ ...m, dropdown: m.item, item: undefined }, tr, ownSpec, 'dropdown', 'menu item', ['dropdown', 'item', 'icon']));
+    }
+    if (node.dropdowns) return this.list('dropdowns', node.dropdowns, [...trail, 'dropdowns'], ownSpec, (d, tr) => this.container(d, tr, ownSpec, 'dropdown', 'dropdown', ['dropdown', 'icon']));
+    if (node.products) return this.list('products', node.products, [...trail, 'products'], ownSpec, (p, tr) => this.container(p, tr, ownSpec, 'product', 'product', ['product', 'icon', 'description']));
+    if (node.versions) return this.list('versions', node.versions, [...trail, 'versions'], ownSpec, (v, tr) => this.container(v, tr, ownSpec, 'version', 'version', ['version', 'tag', 'default']));
+    if (node.languages) return this.list('languages', node.languages, [...trail, 'languages'], ownSpec, (l, tr) => this.language(l, tr, ownSpec));
+    if (typeof node.href === 'string') return { href: node.href };
+    // An item with only an OpenAPI spec: Mintlify generates every endpoint.
+    if (node.openapi !== undefined && ownSpec) {
+      const label = node.tab ?? node.anchor ?? node.dropdown ?? node.product ?? node.item ?? node.version ?? node.language ?? 'API reference';
+      return { pages: [this.openapiGroup(label, ownSpec)] };
+    }
+    return null;
+  }
+
+  list(key, items, trail, spec, convert) {
+    const converted = items.map((item, i) => convert(item, [...trail, i])).filter(Boolean);
+    return converted.length ? { [key]: converted } : null;
+  }
+
+  /** A tab/anchor/dropdown/menu item/product/version. */
+  container(item, trail, spec, nameKey, kind, own) {
+    const name = item[nameKey];
+    if (item.hidden) {
+      this.notes.add(`hidden:${kind}`, trail, `Hidden ${kind}s were left out of the navigation - writedocs has no hidden ${kind}s.`, "Their pages still build and are reachable by URL, like a page that isn't in the navigation.");
+      return null;
+    }
+    this.reportExtraKeys(item, own, kind, trail);
+    const children = this.children(item, trail, spec);
+    if (!children) {
+      this.notes.add(`empty:${kind}`, trail, `A ${kind} with no pages, groups or link was left out.`);
+      return null;
+    }
+    const out = { [nameKey]: name };
+    if (item.icon && typeof item.icon === 'string') out.icon = item.icon;
+    if (nameKey === 'product' && item.description) out.description = item.description;
+    if (nameKey === 'version') {
+      if (item.tag) out.tag = item.tag;
+      if (item.default) out.default = true;
+    }
+    return { ...out, ...children };
+  }
+
+  language(item, trail, spec) {
+    if (item.hidden) {
+      this.notes.add('hidden:language', trail, 'Hidden languages were left out of the navigation.', 'Their pages still build and are reachable by URL.');
+      return null;
+    }
+    for (const key of ['banner', 'footer', 'navbar']) {
+      if (item[key]) {
+        this.notes.add(`language:${key}`, [...trail, key], `A per-language \`${key}\` isn't supported - writedocs has one ${key} for the whole site.`, `Only the top-level \`${key}\` was converted.`);
+      }
+    }
+    this.reportExtraKeys(item, ['language', 'default', 'banner', 'footer', 'navbar'], 'language', trail);
+    const children = this.children(item, trail, spec);
+    if (!children) {
+      this.notes.add('empty:language', trail, 'A language with no pages was left out.');
+      return null;
+    }
+    const out = { language: item.language };
+    if (LANGUAGE_NAMES[item.language]) out.label = LANGUAGE_NAMES[item.language];
+    return { ...out, ...children };
+  }
+
+  /** A `pages`/`groups` array: page paths and groups. */
+  items(list, trail, spec) {
+    const out = [];
+    list.forEach((item, i) => {
+      const tr = [...trail, i];
+      if (typeof item === 'string') {
+        if (ENDPOINT_RE.test(item.trim())) {
+          this.notes.add('endpoint-outside-group', tr, 'An API endpoint listed outside a group was left out.', 'Put the endpoints in a group with an `openapi` spec - writedocs generates a page for every endpoint in it.');
+          return;
+        }
+        out.push(pagePath(item));
+      } else if (item && typeof item === 'object' && typeof item.group === 'string') {
+        const group = this.group(item, tr, spec);
+        if (group) out.push(group);
+      } else if (item && typeof item === 'object' && typeof item.href === 'string') {
+        out.push({ label: item.label ?? item.title ?? item.href, href: item.href });
+      } else {
+        this.notes.add('unknown-page-entry', tr, 'A navigation entry that is neither a page path nor a group was left out.');
+      }
+    });
+    return out;
+  }
+
+  group(g, trail, spec) {
+    if (g.hidden) {
+      this.notes.add('hidden:group', trail, 'Hidden groups were left out of the navigation.', 'Their pages still build and are reachable by URL.');
+      return null;
+    }
+    this.reportExtraKeys(g, ['group', 'root', 'pages'], 'group', trail);
+    const ownSpec = g.openapi !== undefined ? this.spec(g.openapi, [...trail, 'openapi']) : spec;
+    const pages = [];
+    let endpoints = 0;
+    (g.pages ?? []).forEach((item, i) => {
+      if (typeof item === 'string' && ENDPOINT_RE.test(item.trim())) {
+        endpoints++;
+        return;
+      }
+      pages.push(...this.items([item], [...trail, 'pages', i], ownSpec));
+    });
+    const wantsApi = endpoints > 0 || (g.openapi !== undefined && (g.pages ?? []).length === 0);
+    if (wantsApi) {
+      if (ownSpec) {
+        if (endpoints > 0) {
+          this.notes.add('endpoint-selection', [...trail, 'pages'], 'Groups that listed individual API endpoints now generate a page for every endpoint in their OpenAPI spec - writedocs has no per-endpoint selection.', 'To show only some endpoints, split the spec, or write those pages by hand with `openapi: "METHOD /path"` frontmatter.');
+        }
+        if (pages.length === 0 && !g.root) return this.openapiGroup(g.group, ownSpec);
+        pages.push(this.openapiGroup('Endpoints', ownSpec));
+      } else if (endpoints > 0) {
+        this.notes.add('endpoint-no-spec', [...trail, 'pages'], 'API endpoints listed without a usable OpenAPI spec were left out.', 'Add an `openapi` group with a spec file in the project.');
+      }
+    }
+    if (pages.length === 0 && !g.root) {
+      this.notes.add('empty:group', trail, 'A group with no pages was left out.');
+      return null;
+    }
+    const out = { group: g.group };
+    if (g.root) out.page = pagePath(g.root);
+    out.pages = pages;
+    return out;
+  }
+}
+
+function convertNavigation(nav, notes, topbarLinks, defaultSpec) {
+  const trail = ['navigation'];
+  const conv = new NavConverter(notes, defaultSpec);
+  if (Array.isArray(nav)) {
+    notes.add('legacy-navigation', trail, 'docs.json navigation is an array - that is the older mint.json shape.', 'Run `npx mint upgrade` in the Mintlify project first, then convert again.');
+    return { navigation: [], api: conv };
+  }
+  const children = nav ? conv.children(nav, trail, defaultSpec) : null;
+  let navigation = children ?? { pages: [] };
+  if (!children) notes.add('empty-navigation', trail, 'No navigation could be converted.');
+
+  // `global` links: writedocs' global dropdowns are its equivalent of
+  // Mintlify's global anchors (config-schema.ts), but they only exist
+  // alongside a root division, not a plain page list - there they become
+  // topbar links instead.
+  const globalLinks = [];
+  const g = nav?.global ?? {};
+  for (const [key, nameKey] of [['anchors', 'anchor'], ['tabs', 'tab'], ['dropdowns', 'dropdown'], ['products', 'product']]) {
+    (g[key] ?? []).forEach((item, i) => {
+      if (item.hidden) return;
+      if (typeof item.href !== 'string') {
+        notes.add('global-no-href', ['navigation', 'global', key, i], 'Global navigation items without an `href` were left out.');
+        return;
+      }
+      globalLinks.push({ label: item[nameKey], href: item.href, icon: item.icon });
+    });
+  }
+  for (const key of ['languages', 'versions']) {
+    if (g[key]?.length) notes.add(`global-${key}`, ['navigation', 'global', key], `Global ${key} (links to other sites) aren't supported - left out.`);
+  }
+  if (children?.pages) {
+    navigation = children.pages;
+    for (const link of globalLinks) topbarLinks.push(link.icon ? link : { label: link.label, href: link.href });
+    if (globalLinks.length) {
+      notes.add('global-to-topbar', ['navigation', 'global'], 'Global anchors became topbar links - writedocs only has global dropdowns alongside tabs, versions, languages, dropdowns or products.');
+    }
+  } else if (globalLinks.length) {
+    navigation = {
+      global: { dropdowns: globalLinks.map((l) => ({ dropdown: l.label, ...(l.icon ? { icon: l.icon } : {}), href: l.href })) },
+      ...navigation,
+    };
+  }
+  return { navigation, api: conv };
+}
+
+// ---------------------------------------------------------------------
+// Everything else
+// ---------------------------------------------------------------------
+
+const SOCIAL_ICONS = { x: 'x-twitter', website: 'globe' };
+
+function lightDark(value) {
+  if (typeof value === 'string') return { light: value, dark: value };
+  if (value && typeof value === 'object') return { light: value.light, dark: value.dark };
+  return null;
+}
+
+/**
+ * Mintlify docs.json (with `$ref`s already resolved) -> { config, notes }.
+ * `config` is a writedocs.json object; `notes` is a list of
+ * { where: string[], message, suggestion? }.
+ */
+export function convertMintlifyConfig(docs) {
+  const notes = new Notes();
+  const out = { name: docs.name ?? 'Documentation' };
+  if (!docs.name) notes.add('name', ['name'], 'docs.json has no `name` - used "Documentation".');
+  if (docs.description) out.description = docs.description;
+
+  // styles
+  const styles = {};
+  const colors = {};
+  if (docs.colors?.primary) colors.primary = docs.colors.primary;
+  if (docs.colors?.light) colors.dark = { primary: docs.colors.light };
+  if (docs.colors?.dark) notes.add('colors.dark', ['colors', 'dark'], '`colors.dark` (buttons and hover states) has no writedocs equivalent - dropped.', 'writedocs uses `colors.primary` for those.');
+  if (Object.keys(colors).length) styles.colors = colors;
+  if (typeof docs.logo === 'string') styles.logo = docs.logo;
+  else if (docs.logo && typeof docs.logo === 'object') {
+    styles.logo = {};
+    if (docs.logo.light) styles.logo.light = docs.logo.light;
+    if (docs.logo.dark) styles.logo.dark = docs.logo.dark;
+    if (docs.logo.href) notes.add('logo.href', ['logo', 'href'], '`logo.href` isn\'t supported - the logo always links to the home page.');
+  }
+  if (typeof docs.favicon === 'string') styles.favicon = docs.favicon;
+  else if (docs.favicon?.light) {
+    styles.favicon = docs.favicon.light;
+    if (docs.favicon.dark) notes.add('favicon.dark', ['favicon', 'dark'], 'writedocs has one favicon - used `favicon.light`, dropped `favicon.dark`.');
+  }
+  if (docs.fonts && typeof docs.fonts === 'object') {
+    const font = (f) => {
+      const o = { family: f.family };
+      for (const k of ['weight', 'source', 'format']) if (f[k] !== undefined) o[k] = f[k];
+      return o;
+    };
+    if (docs.fonts.family) {
+      styles.fonts = font(docs.fonts);
+      if (docs.fonts.heading?.family) styles.fonts.heading = font(docs.fonts.heading);
+      if (docs.fonts.body?.family) styles.fonts.body = font(docs.fonts.body);
+    } else if (docs.fonts.body?.family || docs.fonts.heading?.family) {
+      styles.fonts = font(docs.fonts.body ?? docs.fonts.heading);
+      if (docs.fonts.heading?.family && docs.fonts.body?.family) styles.fonts.heading = font(docs.fonts.heading);
+    }
+  }
+  const cb = docs.styling?.codeblocks;
+  if (cb !== undefined && cb !== 'system') {
+    const theme = typeof cb === 'string' ? cb : cb?.theme;
+    if (theme === 'dark') styles.codeblocks = { light: 'github-dark', dark: 'github-dark' };
+    else if (typeof theme === 'string') styles.codeblocks = { light: theme, dark: theme };
+    else if (theme && typeof theme === 'object') styles.codeblocks = { light: theme.light, dark: theme.dark };
+    if (cb?.languages) notes.add('codeblock-languages', ['styling', 'codeblocks', 'languages'], 'Custom code block languages aren\'t supported - dropped.');
+  }
+  const bg = docs.background;
+  if (bg) {
+    const background = {};
+    const c = lightDark(bg.color);
+    if (c) background.colors = c;
+    const img = lightDark(bg.image);
+    if (img) background.images = img;
+    if (Object.keys(background).length) styles.background = background;
+    if (bg.decoration) notes.add('background.decoration', ['background', 'decoration'], `\`background.decoration\` ("${bg.decoration}") isn't supported - dropped.`);
+  }
+  if (Object.keys(styles).length) out.styles = styles;
+
+  // navigation (also collects topbar links from `global`)
+  const topbarLinks = [];
+  const defaultSpec = docs.api?.openapi;
+  const navNotesSpec = defaultSpec !== undefined ? new NavConverter(notes).spec(defaultSpec, ['api', 'openapi']) : null;
+  const { navigation } = convertNavigation(docs.navigation, notes, topbarLinks, navNotesSpec);
+  out.navigation = navigation;
+
+  // topbar
+  const navbar = docs.navbar ?? {};
+  const linkFor = (l) => {
+    if (l.type === 'github' || l.type === 'discord') {
+      return { label: l.label ?? (l.type === 'github' ? 'GitHub' : 'Discord'), href: l.href, icon: l.type };
+    }
+    const link = { label: l.label, href: l.href };
+    if (typeof l.icon === 'string') link.icon = l.icon;
+    return link;
+  };
+  for (const l of navbar.links ?? []) if (l?.href && (l.label || l.type || l.icon)) topbarLinks.push(linkFor(l));
+  if (navbar.primary?.href) {
+    topbarLinks.push(linkFor(navbar.primary));
+    notes.add('navbar.primary', ['navbar', 'primary'], 'The navbar\'s primary button became a regular topbar link - writedocs has no call-to-action button style.');
+  }
+  if (topbarLinks.length) out.topbar = { links: topbarLinks };
+
+  // footer + socials
+  const socials = docs.footer?.socials;
+  if (socials && typeof socials === 'object') {
+    out.socials = {};
+    for (const [key, url] of Object.entries(socials)) {
+      const icon = iconExists(key) && !SOCIAL_ICONS[key] ? key : SOCIAL_ICONS[key] ?? key;
+      if (!iconExists(icon)) notes.add(`social:${key}`, ['footer', 'socials', key], `No icon for the "${key}" social link - it shows without one.`);
+      out.socials[icon] = url;
+    }
+  }
+  if (Array.isArray(docs.footer?.links) && docs.footer.links.length) {
+    out.footer = {
+      columns: docs.footer.links.map((col) => ({
+        ...(col.header ? { title: col.header } : {}),
+        links: (col.items ?? []).filter((i) => i?.href && i.label).map((i) => ({ label: i.label, href: i.href })),
+      })),
+    };
+  }
+
+  // banner
+  if (docs.banner?.content) {
+    out.banner = { content: docs.banner.content };
+    if (docs.banner.dismissible) out.banner.dismissible = true;
+    if (['info', 'warning', 'critical'].includes(docs.banner.type)) out.banner.type = docs.banner.type;
+    if (docs.banner.color) notes.add('banner.color', ['banner', 'color'], '`banner.color` isn\'t supported - the banner uses its `type`\'s color.');
+  }
+
+  // 404
+  const e404 = docs.errors?.['404'];
+  if (e404?.title || e404?.description) {
+    out.notFound = {};
+    if (e404.title) out.notFound.title = e404.title;
+    if (e404.description) out.notFound.description = e404.description;
+  }
+  if (e404 && e404.redirect !== false) {
+    notes.add('404-redirect', ['errors', '404', 'redirect'], 'Mintlify redirects a missing page to the home page; writedocs shows a 404 page instead.');
+  }
+
+  // redirects
+  if (Array.isArray(docs.redirects) && docs.redirects.length) {
+    // Mintlify redirects can match a path pattern (`/old/:slug`, `/old/*`);
+    // writedocs redirects are exact paths - a pattern would become a
+    // literal page path (and `:` can't even be a folder name on Windows).
+    const isPattern = (p) => /(^|\/):[A-Za-z_]|\*/.test(p);
+    const patterns = docs.redirects.filter((r) => r?.source && r?.destination && (isPattern(r.source) || isPattern(r.destination)));
+    out.redirects = docs.redirects
+      .filter((r) => r?.source && r?.destination && !patterns.includes(r))
+      .map((r) => ({ source: r.source, destination: r.destination }));
+    if (out.redirects.length === 0) delete out.redirects;
+    if (patterns.length) {
+      const examples = patterns.slice(0, 2).map((r) => `${r.source} -> ${r.destination}`).join('; ');
+      notes.add('redirect-patterns', ['redirects'], `${patterns.length} redirect${patterns.length === 1 ? '' : 's'} with a path parameter or wildcard (e.g. ${examples}) ${patterns.length === 1 ? 'was' : 'were'} left out - writedocs redirects match one exact path.`, 'Add an exact redirect for each old page that still gets traffic.');
+    }
+    if (docs.redirects.some((r) => r?.permanent === false)) {
+      notes.add('redirect-permanent', ['redirects'], '`permanent: false` on redirects has no effect - every writedocs redirect is the same kind.');
+    }
+  }
+
+  // variables
+  if (docs.variables && typeof docs.variables === 'object' && Object.keys(docs.variables).length) {
+    out.variables = { ...docs.variables };
+    const hyphenated = Object.keys(docs.variables).filter((k) => k.includes('-'));
+    if (hyphenated.length) {
+      notes.add('variables-hyphen', ['variables'], `Variables with a hyphen (${hyphenated.join(', ')}) can't be written as {{name}} in writedocs pages.`, 'Write them as [[name]] in your pages instead.');
+    }
+  }
+
+  // SEO
+  const meta = docs.seo?.metatags ?? {};
+  const seo = {};
+  const ignoredMeta = [];
+  for (const [k, v] of Object.entries(meta)) {
+    if (k === 'og:image') seo.ogImage = v;
+    else if (k === 'og:type') seo.ogType = v;
+    else if (k === 'twitter:card' && ['summary', 'summary_large_image'].includes(v)) seo.twitterCard = v;
+    else if (k === 'keywords') seo.keywords = String(v).split(',').map((s) => s.trim()).filter(Boolean);
+    else if (k === 'robots' && /noindex/i.test(String(v))) seo.noindex = true;
+    else ignoredMeta.push(k);
+  }
+  if (Object.keys(seo).length) out.seo = seo;
+  if (ignoredMeta.length) {
+    notes.add('metatags', ['seo', 'metatags'], `These meta tags aren't supported and were dropped: ${ignoredMeta.join(', ')}.`, 'writedocs sets canonical, og:title/description/url and twitter tags itself; a verification tag can go in a custom head script.');
+  }
+  if (docs.seo?.indexing === 'all') notes.add('seo.indexing', ['seo', 'indexing'], '`seo.indexing: "all"` has no equivalent - writedocs indexes every page that isn\'t marked noindex.');
+
+  // context menu
+  const options = docs.contextual?.options;
+  if (Array.isArray(options) && options.length) {
+    const openIn = options.filter((o) => ['chatgpt', 'claude', 'perplexity'].includes(o));
+    out.contextMenu = { openIn };
+    const other = options.filter((o) => typeof o !== 'string' || !['copy', 'view', 'chatgpt', 'claude', 'perplexity'].includes(o));
+    if (other.length) {
+      notes.add('contextual', ['contextual', 'options'], `Context menu options writedocs doesn't have were dropped: ${other.map((o) => (typeof o === 'string' ? o : o.title ?? 'custom')).join(', ')}.`, 'writedocs\' page menu always has copy and view-as-Markdown, plus open in ChatGPT, Claude and Perplexity.');
+    }
+  }
+
+  // API playground
+  if (docs.api?.playground?.proxy === false) out.api = { proxy: false };
+  if (docs.api?.playground?.display && docs.api.playground.display !== 'interactive') {
+    notes.add('api.playground.display', ['api', 'playground', 'display'], `\`api.playground.display: "${docs.api.playground.display}"\` isn't supported - the playground is always interactive.`);
+  }
+  for (const key of ['params', 'url', 'examples', 'mdx', 'asyncapi']) {
+    if (docs.api?.[key] !== undefined) notes.add(`api.${key}`, ['api', key], `\`api.${key}\` has no writedocs equivalent - dropped.`);
+  }
+
+  // integrations
+  const integrations = {};
+  const ig = docs.integrations ?? {};
+  if (ig.ga4?.measurementId) integrations.ga4 = { measurementId: ig.ga4.measurementId };
+  if (ig.gtm?.tagId) integrations.googleTagManager = { containerId: ig.gtm.tagId };
+  if (ig.plausible?.domain) {
+    integrations.plausible = { domain: ig.plausible.domain };
+    if (ig.plausible.server) integrations.plausible.src = `${ig.plausible.server.replace(/\/+$/, '')}/js/script.js`;
+  }
+  if (ig.fathom?.siteId) integrations.fathom = { siteId: ig.fathom.siteId };
+  if (ig.posthog?.apiKey) {
+    integrations.posthog = { apiKey: ig.posthog.apiKey };
+    if (ig.posthog.apiHost) integrations.posthog.apiHost = ig.posthog.apiHost;
+  }
+  if (Object.keys(integrations).length) out.integrations = integrations;
+  const otherIntegrations = Object.keys(ig).filter((k) => !['ga4', 'gtm', 'plausible', 'fathom', 'posthog', 'telemetry', 'cookies'].includes(k));
+  if (otherIntegrations.length) {
+    notes.add('integrations', ['integrations'], `These integrations have no writedocs equivalent and were dropped: ${otherIntegrations.join(', ')}.`, 'Most can be added as a custom script in writedocs.json\'s `scripts.head`.');
+  }
+
+  // Settings with no equivalent at all
+  const unsupported = {
+    appearance: 'Light/dark mode defaults (`appearance`) aren\'t configurable - readers choose with the theme toggle.',
+    interaction: '`interaction` settings aren\'t supported.',
+    thumbnails: 'Social thumbnails (`thumbnails`) aren\'t generated - set `seo.ogImage` for a social preview image.',
+    metadata: '`metadata` (last-modified timestamps) isn\'t supported.',
+    markdown: '`markdown` export settings aren\'t supported.',
+    search: '`search` settings aren\'t supported.',
+  };
+  for (const [key, message] of Object.entries(unsupported)) if (docs[key] !== undefined) notes.add(key, [key], message);
+  if (docs.styling?.eyebrows) notes.add('styling.eyebrows', ['styling', 'eyebrows'], '`styling.eyebrows` isn\'t supported - writedocs shows breadcrumbs.');
+  if (docs.icons?.library === 'tabler') {
+    notes.add('icons.library', ['icons', 'library'], 'Icon names are looked up in Lucide, then Font Awesome - not Tabler.', 'Tabler names that don\'t exist there can be written as "tabler:name".');
+  }
+
+  return { config: out, notes: notes.list() };
+}
+
+/** Formats notes for the terminal - same layout as `writedocs validate`. */
+export function formatNotes(notes) {
+  return notes
+    .map((n) => {
+      const where = n.where.length > 3 ? `${n.where.slice(0, 3).join(', ')} and ${n.where.length - 3} more` : n.where.join(', ');
+      const lines = [`  ${where}`, `    ${n.message}`];
+      if (n.suggestion) lines.push(`    ${n.suggestion}`);
+      return lines.join('\n');
+    })
+    .join('\n\n');
+}

package/src/lib/openapi-ref.js

@@ -0,0 +1,44 @@
+// A page's `openapi` frontmatter, in either form writedocs accepts:
+//
+//   openapi: "GET /pets/{petId}"                  - an operation in one of
+//                                                   writedocs.json's openapi
+//                                                   groups
+//   openapi: "/admin-openapi.json POST /v1/jobs"  - Mintlify's form: the spec
+//                                                   file first (relative to
+//                                                   the content directory)
+//
+// Everything that reads the field - the API playground, the sidebar's method
+// badge, hand-written-override matching, and generate-api-pages.js, which
+// processes every spec a page names this way - goes through here, so the two
+// forms mean the same thing everywhere. Plain JavaScript: generate-api-pages
+// runs under plain Node.
+
+const METHOD = /^(get|post|put|patch|delete|head|options|trace|webhook)$/i;
+
+/** { spec, method, path } - `spec` is null for the short form, and has no
+ *  leading slash otherwise. Null when the value isn't an operation at all. */
+export function parseOpenApiRef(value) {
+  if (typeof value !== 'string') return null;
+  const parts = value.trim().split(/\s+/);
+  if (parts.length === 2 && METHOD.test(parts[0])) {
+    return { spec: null, method: parts[0].toUpperCase(), path: parts[1] };
+  }
+  if (parts.length === 3 && METHOD.test(parts[1])) {
+    return { spec: parts[0].replace(/^\.?\//, ''), method: parts[1].toUpperCase(), path: parts[2] };
+  }
+  return null;
+}
+
+/** The folder name (under writedocsTempDir()/openapi/_pages/) holding the
+ *  operations of a spec that pages name in their frontmatter - shared by
+ *  generate-api-pages.js, which writes it, and findOperationFile(), which
+ *  reads it. */
+export function specDirName(spec) {
+  return String(spec).replace(/^\.?\//, '').replace(/[^a-zA-Z0-9]+/g, '_');
+}
+
+/** "METHOD /path" - the key an operation is known by, whichever spec it's in. */
+export function openApiOperationKey(value) {
+  const ref = parseOpenApiRef(value);
+  return ref ? `${ref.method} ${ref.path}` : null;
+}