@thallylabs/migrate 0.2.9 → 0.2.11

package/dist/index.js

@@ -31,6 +31,20 @@ import { unified as unified2 } from "unified";
 
 // src/frontmatter.ts
 import { parse as parseYaml } from "yaml";
+function salvageFrontmatterLines(matter) {
+  const data = {};
+  for (const line of matter.split(/\r?\n/)) {
+    if (!/^[A-Za-z_][\w-]*:\s?/.test(line)) continue;
+    try {
+      const parsedLine = parseYaml(line);
+      if (parsedLine && typeof parsedLine === "object" && !Array.isArray(parsedLine)) {
+        Object.assign(data, parsedLine);
+      }
+    } catch {
+    }
+  }
+  return data;
+}
 function parseFrontmatter(raw) {
   const source = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
   const opening = /^---([^\r\n]*)\r?\n/.exec(source);
@@ -45,14 +59,23 @@ function parseFrontmatter(raw) {
   if (matter.trim() === "" || !["", "yaml", "yml"].includes(language)) {
     return { content, data: {} };
   }
-  const parsed = parseYaml(matter);
-  return {
-    content,
-    data: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
-  };
+  try {
+    const parsed = parseYaml(matter);
+    return {
+      content,
+      data: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+    };
+  } catch (err) {
+    return {
+      content,
+      data: salvageFrontmatterLines(matter),
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
 }
 
 // src/mdx.ts
+import { posix } from "path";
 import { compileSync } from "@mdx-js/mdx";
 import { nameToEmoji } from "gemoji";
 import remarkGfm from "remark-gfm";
@@ -232,8 +255,9 @@ function unwrapDocusaurusMdxCodeBlocks(body) {
   }
   return isMdxCodeBlock ? body : output.join("\n");
 }
-function normalizeExplicitHeadingIds(body) {
-  return replaceOutsideCode(body, (segment) => segment.split("\n").map((line) => {
+function normalizeExplicitHeadingIds(raw) {
+  const { front, body } = splitFrontmatterBlock(raw);
+  return front + replaceOutsideCode(body, (segment) => segment.split("\n").map((line) => {
     if (!/^[ \t]{0,3}#{1,6}[ \t]+/.test(line)) return line;
     const trimmed = line.trimEnd();
     if (trimmed.endsWith("}")) {
@@ -275,6 +299,7 @@ function removeGlobalDocusaurusImports(body) {
 }
 var JS_LITERAL_KEYWORDS = /* @__PURE__ */ new Set(["true", "false", "null", "undefined"]);
 var BARE_IDENTIFIER_PATH = /^[\p{ID_Start}$_][\p{ID_Continue}$‌‍]*(?:\.[\p{ID_Start}$_][\p{ID_Continue}$‌‍]*)*$/u;
+var BARE_OBJECT_SHORTHAND = /^\{\s*([\p{ID_Start}$_][\p{ID_Continue}$‌‍]*)\s*\}$/u;
 var SAFE_BUILTIN_ROOTS = /* @__PURE__ */ new Set([
   "Math",
   "JSON",
@@ -499,12 +524,13 @@ function escapeFernLiteralBraces(raw) {
       const end = node.position?.end.offset;
       const root2 = value.split(".")[0];
       const safeBuiltinPath = value.includes(".") && SAFE_BUILTIN_ROOTS.has(root2);
-      const isTemplatePlaceholder = /^\{\s*[A-Za-z_$][\w$.-]*\s*\}$/.test(value);
+      const isBareIdentifier = BARE_IDENTIFIER_PATH.test(value) && !JS_LITERAL_KEYWORDS.has(value) && !declared.has(root2) && !safeBuiltinPath;
+      const shorthandMatch = value.match(BARE_OBJECT_SHORTHAND);
+      const isDoubleBraceTemplate = shorthandMatch !== null && !declared.has(shorthandMatch[1]);
       const isIssueList = /^[A-Za-z][A-Za-z0-9]*-\d+(?:\s*,\s*[A-Za-z][A-Za-z0-9]*-\d+)*$/.test(value);
-      if ((isTemplatePlaceholder || isIssueList) && start !== void 0 && end !== void 0) {
-        edits.push({ start, end, value: body.slice(start, end).replace(/\\/g, "\\\\").replace(/[{}]/g, "\\$&") });
-      } else if (BARE_IDENTIFIER_PATH.test(value) && !JS_LITERAL_KEYWORDS.has(value) && !declared.has(root2) && !safeBuiltinPath && start !== void 0 && end !== void 0) {
-        edits.push({ start, end, value: `\\{${value}\\}` });
+      if ((isBareIdentifier || isDoubleBraceTemplate || isIssueList) && start !== void 0 && end !== void 0) {
+        const rawSpan = body.slice(start, end);
+        edits.push({ start, end, value: rawSpan.replace(/\\/g, "\\\\").replace(/[{}]/g, "\\$&") });
       }
       return;
     }
@@ -644,6 +670,66 @@ function replaceOutsideCode(body, transform) {
   const { masked, unmask } = maskCode(body);
   return unmask(transform(masked));
 }
+function rewriteFernRelativePageLinks(body, currentSourcePath, routesBySourcePath) {
+  const rewrite = (target) => {
+    if (!target || target.startsWith("/") || target.startsWith("#") || target.startsWith("?") || target.includes("\\") || /[\u0000-\u001f\u007f]/.test(target) || /^[A-Za-z][A-Za-z\d+.-]*:/.test(target)) return target;
+    const suffixAt = target.search(/[?#]/);
+    const pathname = suffixAt < 0 ? target : target.slice(0, suffixAt);
+    const suffix = suffixAt < 0 ? "" : target.slice(suffixAt);
+    if (!pathname || pathname.startsWith("//") || pathname.split("/").some((part) => /%2f|%5c/i.test(part))) return target;
+    const source = posix.normalize(posix.join(posix.dirname(currentSourcePath.replace(/\\/g, "/")), pathname));
+    const candidates = /\.mdx?$/i.test(source) ? [source] : [source, `${source}.mdx`, `${source}.md`, `${source}/index.mdx`, `${source}/index.md`];
+    const route = candidates.map((candidate) => routesBySourcePath.get(candidate)).find(Boolean);
+    return route ? `/${route.replace(/^\/+/, "")}${suffix}` : target;
+  };
+  return replaceOutsideCode(body, (text) => text.replace(
+    /(\]\()(<[^>\n]+>|[^\s)]+)(?=\s|\))/g,
+    (_match, opening, target) => `${opening}${target.startsWith("<") && target.endsWith(">") ? `<${rewrite(target.slice(1, -1))}>` : rewrite(target)}`
+  ).replace(
+    /(\b(?:href|to)\s*=\s*)(["'])([^"'\n]+)\2/g,
+    (_match, opening, quote, target) => `${opening}${quote}${rewrite(target)}${quote}`
+  ).replace(
+    /(\b(?:href|to)\s*=\s*\{\s*)(["'])([^"'\n]+)\2(?=\s*\})/g,
+    (_match, opening, quote, target) => `${opening}${quote}${rewrite(target)}${quote}`
+  ));
+}
+function normalizeFernFileTrees(body) {
+  return replaceOutsideCode(body, (whole) => whole.replace(
+    /<FileTree\s*>\s*\n([\s\S]*?)\n\s*<\/FileTree>/g,
+    (original, contents) => {
+      const lines = contents.split(/\r?\n/).filter((line) => line.trim());
+      if (!lines.length) return original;
+      const nodes = [];
+      for (const line of lines) {
+        const match = /^( *)(?:-|\*|\+)\s+(.+?)\s*$/.exec(line);
+        if (!match || match[1].length % 2 !== 0 || match[2].includes("\0")) return original;
+        nodes.push({ indent: match[1].length / 2, name: match[2], isFolder: match[2].endsWith("/") });
+      }
+      const output = ["<Tree>"];
+      const folders = [];
+      for (const node of nodes) {
+        while (folders.length > node.indent) {
+          output.push("</Folder>");
+          folders.pop();
+        }
+        if (node.indent > folders.length || node.indent > 0 && folders.length === 0) return original;
+        const name = `{${JSON.stringify(node.name)}}`;
+        if (node.isFolder) {
+          output.push(`<Folder name=${name} defaultOpen>`);
+          folders.push(node.indent);
+        } else {
+          output.push(`<File name=${name} />`);
+        }
+      }
+      while (folders.length) {
+        output.push("</Folder>");
+        folders.pop();
+      }
+      output.push("</Tree>");
+      return output.join("\n");
+    }
+  ));
+}
 function normalizeHtmlComments(body) {
   return replaceOutsideCode(body, (whole) => whole.replace(/<!--([\s\S]*?)-->/g, (_match, comment) => `{/*${comment}*/}`));
 }
@@ -1013,7 +1099,7 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   const runMintlify = platform === "mintlify";
   const runDocusaurus = platform === "docusaurus";
   const sourceBody = runDocusaurus && unwrapMdxCodeBlocks ? unwrapDocusaurusMdxCodeBlocks(body) : body;
-  let rewritten = normalizeDocusaurusAdmonitions(normalizeExplicitHeadingIds(runFern ? normalizeFernCallouts(sourceBody) : sourceBody));
+  let rewritten = normalizeDocusaurusAdmonitions(normalizeExplicitHeadingIds(runFern ? normalizeFernFileTrees(normalizeFernCallouts(sourceBody)) : sourceBody));
   if (runDocusaurus) {
     rewritten = replaceOutsideCode(rewritten, (segment) => segment.replace(
       /:([+\w-]+):/g,
@@ -1092,7 +1178,8 @@ function parseMarkdownPage(input) {
     noindex: parsed.data.noindex === true || parsed.data.noindex === "true" ? true : void 0,
     openapi: typeof parsed.data.openapi === "string" ? parsed.data.openapi.trim() : void 0,
     body,
-    source: input.source
+    source: input.source,
+    ...parsed.error ? { frontmatterError: parsed.error } : {}
   };
 }
 
@@ -1145,6 +1232,11 @@ function mintlifyLocalizedReference(value, locale, defaultPageIds = /* @__PURE__
     const candidateId = pageIdFromReference(candidate, true);
     if (candidateId && defaultPageIds.has(candidateId)) return candidate;
   }
+  const segments = reference.split("/");
+  const localeIndex = segments.findIndex((segment) => segment.toLowerCase() === locale.toLowerCase());
+  if (localeIndex > 0) {
+    return [...segments.slice(0, localeIndex), ...segments.slice(localeIndex + 1)].join("/");
+  }
   return value;
 }
 function resolveWithin(root, candidate) {
@@ -1493,9 +1585,14 @@ function implicitReactImports(source) {
   visit(source);
   const hooks = [...REACT_GLOBALS].filter((name) => references.has(name) && !bindings.has(name)).sort();
   const usesMintlifyComponents = references.has("MintlifyComponents") && !bindings.has("MintlifyComponents");
+  const implicitComponents = MINTLIFY_COMPONENT_MODULES.map(({ module, names }) => {
+    const needed = names.filter((name) => references.has(name) && !bindings.has(name));
+    return needed.length ? `import { ${needed.join(", ")} } from '${module}';` : "";
+  }).filter(Boolean);
   return [
     references.has("React") && !bindings.has("React") ? "import * as React from 'react';" : "",
     hooks.length ? `import { ${hooks.join(", ")} } from 'react';` : "",
+    ...implicitComponents,
     usesMintlifyComponents ? mintlifyComponentsShim() : ""
   ].filter(Boolean).join("\n");
 }
@@ -1598,6 +1695,19 @@ function declarationsReferenceBrowserGlobal(body) {
   }
   return found;
 }
+function neutralizeUnresolvableImportsWithoutAst(content, currentFile, warn) {
+  const importPattern = /^import\s+(?:\{\s*(?:default\s+as\s+)?([A-Z][A-Za-z0-9_]*)\s*\}|([A-Z][A-Za-z0-9_]*))\s+from\s+(['"])((?:@site\/|\.\.?\/|\/)[^'"]+)\3\s*;?[ \t]*$/gm;
+  const dropped = [];
+  let result = content.replace(importPattern, (_match, namedComponent, defaultComponent, _quote, specifier) => {
+    dropped.push({ name: namedComponent ?? defaultComponent, specifier });
+    return "";
+  });
+  for (const { name, specifier } of dropped) {
+    warn(`Component import ${JSON.stringify(specifier)} could not be resolved because this page has invalid MDX (see the previous warning), so the import and its usage were removed to keep the site building.`, currentFile);
+    result = result.replace(new RegExp(`<${name}(?:\\s[^>]*)?/>`, "g"), `{/* Removed <${name}>: unresolved during fallback migration */}`).replace(new RegExp(`<${name}(?:\\s[^>]*)?>[\\s\\S]*?<\\/${name}>`, "g"), `{/* Removed <${name}>: unresolved during fallback migration */}`);
+  }
+  return result;
+}
 function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIdentity) {
   const root = resolve2(siteRoot);
   const confined = resolve2(confinementRoot);
@@ -1792,16 +1902,17 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
   function transform(raw, currentFile) {
     const parsedFrontmatter = parseFrontmatter(raw).content;
     const frontmatter = raw.slice(0, raw.length - parsedFrontmatter.length);
-    const content = normalizeIndentedFences(normalizeHtmlComments(parsedFrontmatter));
+    const content = normalizeExplicitHeadingIds(normalizeIndentedFences(normalizeHtmlComments(parsedFrontmatter)));
     let tree;
     try {
       tree = parser.parse(content);
     } catch {
       warn("Custom component analysis could not parse this MDX; its source was preserved for manual migration.", currentFile);
-      return raw;
+      return frontmatter + neutralizeUnresolvableImportsWithoutAst(content, currentFile, warn);
     }
     const aliases = /* @__PURE__ */ new Map();
     const unsupportedImports = /* @__PURE__ */ new Map();
+    const droppedMdxDataBindings = /* @__PURE__ */ new Set();
     const edits = [];
     const declarations = [];
     const moduleImports = [];
@@ -1901,14 +2012,31 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
           }
           continue;
         }
-        if (/\.mdx?$/.test(specifier)) continue;
+        if (/\.mdx?$/.test(specifier)) {
+          if (bindings.length > 0 && bindings.every((binding) => !/^[A-Z]/.test(binding.local))) {
+            warn(`MDX named import of ${JSON.stringify(rawSpecifier)} isn't a component and has no equivalent in the migrated site (for example Docusaurus's generated 'toc' export), so it was removed, along with any '...${bindings.map((binding) => binding.local).join(", '...")}' spread of it.`, currentFile);
+            edits.push({ start: node.position.start.offset + statement.getStart(ast), end: node.position.start.offset + statement.end, value: "" });
+            for (const binding of bindings) droppedMdxDataBindings.add(binding.local);
+          }
+          continue;
+        }
         if (bindings.length && RESCUABLE_ASSET_EXTENSIONS.has(extname(specifier).toLowerCase()) && !bindings.some((binding) => usedAsJsxTagName(binding.local))) {
           try {
             const href = copyPublicAsset(resolveDependency(specifier, currentFile));
             edits.push({
               start: node.position.start.offset + statement.getStart(ast),
               end: node.position.start.offset + statement.end,
-              value: bindings.map((binding) => `const ${binding.local} = ${JSON.stringify(href)};`).join("\n")
+              // `export`, not a bare `const`: this replaces an `import`
+              // statement in place, and the final MDX compile (a fresh
+              // parse of this text, not a reuse of this pass's own AST)
+              // only recognizes a top-level JS block as ESM — evaluated and
+              // its bindings put in scope — when it starts with `import` or
+              // `export`. A bare `const` there is just prose to that parser
+              // and renders as literal paragraph text instead, leaving
+              // every reference to this binding a `ReferenceError` at
+              // render (reproduced against hasura/graphql-engine's
+              // databases/overview.mdx, which binds asset URLs this way).
+              value: bindings.map((binding) => `export const ${binding.local} = ${JSON.stringify(href)};`).join("\n")
             });
             warn(`Asset import ${JSON.stringify(rawSpecifier)} was copied to ${href} and bound to that URL instead of importing it as a component.`, currentFile);
             continue;
@@ -1976,7 +2104,9 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
             edits.push({
               start: importStart,
               end: importEnd,
-              value: bindings.map((binding) => `const ${binding.local} = ${JSON.stringify(rescuedAssetHref)};`).join("\n")
+              // See the identical `export const` note on the other asset
+              // rescue above — same reason.
+              value: bindings.map((binding) => `export const ${binding.local} = ${JSON.stringify(rescuedAssetHref)};`).join("\n")
             });
             warn(`Asset import ${JSON.stringify(rawSpecifier)} could not be copied as a component; it was copied to ${rescuedAssetHref} and bound to that URL instead.`, currentFile);
           } else {
@@ -1986,6 +2116,27 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
         }
       }
     }
+    if (droppedMdxDataBindings.size > 0) {
+      for (const node of esmNodes) {
+        let stripDroppedSpreads2 = function(inner) {
+          if (ts.isSpreadElement(inner) && ts.isIdentifier(inner.expression) && droppedMdxDataBindings.has(inner.expression.text)) {
+            const start = nodeStart + inner.getStart(ast);
+            let end = nodeStart + inner.end;
+            const following = nodeText.slice(inner.end).match(/^\s*,/);
+            if (following) end += following[0].length;
+            edits.push({ start, end, value: "" });
+            return;
+          }
+          ts.forEachChild(inner, stripDroppedSpreads2);
+        };
+        var stripDroppedSpreads = stripDroppedSpreads2;
+        if (node.value === void 0 || node.position?.start.offset === void 0) continue;
+        const nodeStart = node.position.start.offset;
+        const nodeText = node.value;
+        const ast = sourceFile(nodeText, "inline.tsx");
+        for (const statement of ast.statements) stripDroppedSpreads2(statement);
+      }
+    }
     walk(tree, (node) => {
       for (const attribute of node.attributes ?? []) {
         if (attribute.type !== "mdxJsxAttribute" || !attribute.value || typeof attribute.value !== "object") continue;
@@ -2242,14 +2393,14 @@ import { customComponents as ${name} } from ${JSON.stringify(registryPath)}
 
 // src/docusaurus.ts
 import { existsSync as existsSync3, lstatSync as lstatSync3, readFileSync as readFileSync3 } from "fs";
-import { extname as extname3, posix } from "path";
+import { extname as extname3, posix as posix2 } from "path";
 import JSON5 from "json5";
 import { parse as parseYaml2 } from "yaml";
 
 // src/navigation.ts
 import { existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as readFileSync2, realpathSync } from "fs";
 import { dirname as dirname2, extname as extname2, relative as relative3 } from "path";
-var MAX_MINTLIFY_CONFIG_BYTES = 2e6;
+var MAX_MINTLIFY_CONFIG_BYTES = 2e7;
 function addMintlifyDirectoryRedirects(config, pages) {
   const pageIds = new Set(pages.map((page) => page.id));
   const redirects = [...config.redirects ?? []];
@@ -2297,15 +2448,10 @@ function addMintlifyDirectoryRedirects(config, pages) {
       }
     }
   }
-  for (const redirect of config.redirects ?? []) {
-    const destination = redirect.destination.split(/[?#]/, 1)[0].replace(/\/:[A-Za-z_][A-Za-z0-9_]*\*\/?$/, "");
-    if (!destination.startsWith("/") || destination.startsWith("//") || /[:*()[\]{}]/.test(destination)) continue;
-    const directory = trimEdgeSlashes(destination);
-    if (!directory || pageIds.has(directory)) continue;
+  for (const [directory, landing] of firstDescendantByDirectory) {
+    if (pageIds.has(directory)) continue;
     const source = `/${directory}`;
     if (hasAuthoredRedirect(source)) continue;
-    const landing = firstDescendantByDirectory.get(directory);
-    if (!landing) continue;
     redirects.push({ source, destination: `/${landing.id}`, permanent: false });
     redirectSources.add(source);
   }
@@ -2356,6 +2502,18 @@ var LANGUAGE_LABELS = {
 function objectValue(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
+function withFlattenedProductGroups(container) {
+  if (!Array.isArray(container.productGroups)) return container;
+  const flattened = container.productGroups.flatMap((entry) => {
+    const group = objectValue(entry);
+    return group && Array.isArray(group.products) ? group.products : [];
+  });
+  if (flattened.length === 0) return container;
+  return {
+    ...container,
+    products: [...Array.isArray(container.products) ? container.products : [], ...flattened]
+  };
+}
 function projectedHref(value) {
   if (typeof value !== "string") return void 0;
   const href = value.trim();
@@ -2443,12 +2601,23 @@ function mintlifyNavigationApiReferences(config) {
   const references = [];
   const containerKeys = ["tabs", "anchors", "products", "dropdowns", "versions", "menus", "languages"];
   const nestedKeys = ["groups", "pages"];
-  function visit(node, tabLabel) {
-    if (typeof node.openapi === "string" && node.openapi.trim()) {
-      references.push({ value: node.openapi.trim(), kind: "openapi", tabLabel });
-    }
-    if (typeof node.asyncapi === "string" && node.asyncapi.trim()) {
-      references.push({ value: node.asyncapi.trim(), kind: "asyncapi", tabLabel });
+  function visit(rawNode, tabLabel) {
+    const node = withFlattenedProductGroups(rawNode);
+    for (const kind of ["openapi", "asyncapi"]) {
+      const value = node[kind];
+      if (typeof value === "string" && value.trim()) {
+        references.push({ value: value.trim(), kind, tabLabel });
+        continue;
+      }
+      const object = objectValue(value);
+      if (object && typeof object.source === "string" && object.source.trim()) {
+        references.push({
+          value: object.source.trim(),
+          kind,
+          tabLabel,
+          ...typeof object.directory === "string" && object.directory.trim() ? { directory: object.directory.trim() } : {}
+        });
+      }
     }
     for (const key of containerKeys) {
       const entries = node[key];
@@ -2509,8 +2678,19 @@ function registerReference(value, context) {
   }
   return navigationId;
 }
+var OPENAPI_OPERATION_REF = /^(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+\S/;
 function convertPage(value, context) {
-  if (typeof value === "string") return registerReference(value, context);
+  if (typeof value === "string") {
+    if (OPENAPI_OPERATION_REF.test(value)) {
+      warnOnce(
+        context,
+        "openapi-operation-list",
+        'One or more navigation groups hand-pick or reorder individual OpenAPI operations (e.g. "GET /users"); Thally always renders every operation of a bound spec and has no manual-selection equivalent, so that list was dropped. The operations themselves are still available through the bound API reference.'
+      );
+      return null;
+    }
+    return registerReference(value, context);
+  }
   const object = objectValue(value);
   if (!object) return null;
   if (typeof object.page === "string") return registerReference(object.page, context);
@@ -2553,8 +2733,9 @@ function convertNavigationValues(values, context) {
   });
 }
 function convertContainerToTabs(containerValue, context, fallbackTab, trace, depth = 0) {
-  const container = objectValue(containerValue);
-  if (!container) return [];
+  const rawContainer = objectValue(containerValue);
+  if (!rawContainer) return [];
+  const container = withFlattenedProductGroups(rawContainer);
   const containerKeys = ["tabs", "anchors", "products", "dropdowns", "versions", "menus"];
   for (const key of containerKeys) {
     if (!Array.isArray(container[key])) continue;
@@ -2776,6 +2957,47 @@ function isRedirectPathSafe(rawSource, rawDestination) {
   }
   return true;
 }
+function mintlifyDefaultVersionPrefixes(config) {
+  const navigation = objectValue(config.navigation) ?? config;
+  const prefixes = /* @__PURE__ */ new Set();
+  function collect(container) {
+    if (Array.isArray(container.versions)) {
+      const entries = container.versions.map((value) => objectValue(value)).filter((value) => value !== null);
+      const defaultEntry = entries.find((entry) => entry.default === true) ?? entries[0];
+      if (defaultEntry && typeof defaultEntry.version === "string" && defaultEntry.version.trim()) {
+        prefixes.add(defaultEntry.version.trim());
+      }
+    }
+    if (Array.isArray(container.languages)) {
+      for (const value of container.languages) {
+        const language = objectValue(value);
+        if (language) collect(language);
+      }
+    }
+  }
+  collect(navigation);
+  return prefixes;
+}
+function mintlifyAllVersionPrefixes(config) {
+  const navigation = objectValue(config.navigation) ?? config;
+  const prefixes = /* @__PURE__ */ new Set();
+  function collect(container) {
+    if (Array.isArray(container.versions)) {
+      for (const value of container.versions) {
+        const entry = objectValue(value);
+        if (entry && typeof entry.version === "string" && entry.version.trim()) prefixes.add(entry.version.trim());
+      }
+    }
+    if (Array.isArray(container.languages)) {
+      for (const value of container.languages) {
+        const language = objectValue(value);
+        if (language) collect(language);
+      }
+    }
+  }
+  collect(navigation);
+  return prefixes;
+}
 function projectMintlifyNavigation(config, options = {}) {
   const warnings = [];
   const references = [];
@@ -3021,7 +3243,7 @@ function pruneMissingNavigationPages(config, availableIds) {
 }
 
 // src/docusaurus.ts
-var MAX_CONFIG_BYTES = 1e6;
+var MAX_CONFIG_BYTES = 2e7;
 var CATEGORY_FILENAMES = ["_category_.json", "_category_.yml", "_category_.yaml"];
 var SIDEBAR_FILENAMES = [
   "sidebars.json",
@@ -3063,19 +3285,19 @@ function storageIdForRoute(routeId) {
 function titleCase2(value) {
   return stripNumberPrefix(value).replace(/sidebar$/i, "").split(/[-_]/).filter(Boolean).map((word) => ["api", "cli", "sdk", "ui"].includes(word.toLowerCase()) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
-function routeFromSlug(slug, fallback, sourceDirectory) {
-  if (slug === "/") return "introduction";
-  if (slug.startsWith("/")) return docusaurusRouteId(slug);
-  const fallbackDirectory = sourceDirectory ?? (fallback === "introduction" ? "" : posix.dirname(fallback));
-  const resolved = posix.normalize(posix.join(fallbackDirectory, slug));
+function routeFromSlug(slug2, fallback, sourceDirectory) {
+  if (slug2 === "/") return "introduction";
+  if (slug2.startsWith("/")) return docusaurusRouteId(slug2);
+  const fallbackDirectory = sourceDirectory ?? (fallback === "introduction" ? "" : posix2.dirname(fallback));
+  const resolved = posix2.normalize(posix2.join(fallbackDirectory, slug2));
   if (resolved === ".." || resolved.startsWith("../")) return null;
   return docusaurusRouteId(resolved);
 }
 function resolveDocusaurusPageIdentity(sourcePath, frontmatter, fallback) {
   const sourceDocId = normalizeDocId(sourcePath);
-  const sourceDirectory = posix.dirname(sourceDocId);
+  const sourceDirectory = posix2.dirname(sourceDocId);
   const configuredId = typeof frontmatter.id === "string" && frontmatter.id.trim() ? stripNumberPrefix(frontmatter.id.trim()) : null;
-  const docId = configuredId ? normalizeDocId(sourceDirectory === "." ? configuredId : posix.join(sourceDirectory, configuredId)) : sourceDocId;
+  const docId = configuredId ? normalizeDocId(sourceDirectory === "." ? configuredId : posix2.join(sourceDirectory, configuredId)) : sourceDocId;
   const defaultNavigationId = defaultDocusaurusRouteId(docId) ?? fallback.navigationId;
   const configuredSlug = typeof frontmatter.slug === "string" ? frontmatter.slug.trim() : "";
   const navigationId = configuredSlug ? routeFromSlug(
@@ -3097,6 +3319,105 @@ function resolveDocusaurusPageIdentity(sourcePath, frontmatter, fallback) {
 function sourceReferenceKey(value) {
   return value.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\.(?:mdx?)$/i, "").replace(/\/$/, "");
 }
+function sourceHeadings(body) {
+  const headings = [];
+  const lines = body.split("\n");
+  let fence = null;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (marker) {
+      if (!fence) fence = marker[1];
+      else if (marker[1][0] === fence[0] && marker[1].length >= fence.length && /^\s*$/.test(line.slice(marker[0].length))) fence = null;
+      continue;
+    }
+    if (fence) continue;
+    const heading = line.match(/^ {0,3}(#{2,6})\s+(.+?)\s*#*\s*$/);
+    if (!heading) continue;
+    const preceding = lines[index - 1]?.match(/^<a id="([\p{L}\p{N}_.:$-]{1,120})"><\/a>$/u);
+    const plainText = !/[<>{}\[\]`*_]/.test(heading[2]);
+    const generatedId = plainText ? heading[2].normalize("NFC").toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/(^-|-$)/g, "") : null;
+    headings.push({ index, level: heading[1].length, id: preceding?.[1] ?? generatedId });
+  }
+  return headings;
+}
+function addDocusaurusTranslatedHeadingAliases(pages) {
+  const byRoute = new Map(pages.map((page) => [page.navigationId, page]));
+  for (const page of pages) {
+    const locale = page.source.match(/(?:^|[/#])i18n\/([A-Za-z]{2,8}(?:-[A-Za-z0-9]{2,8})*)\/docusaurus-plugin-content-docs\//)?.[1];
+    if (!locale) continue;
+    const originalRoute = page.navigationId === locale ? "introduction" : page.navigationId.startsWith(`${locale}/`) ? page.navigationId.slice(locale.length + 1) : null;
+    if (!originalRoute) continue;
+    const original = byRoute.get(originalRoute);
+    if (!original) continue;
+    const originalHeadings = sourceHeadings(original.body);
+    const translatedHeadings = sourceHeadings(page.body);
+    if (!originalHeadings.length || originalHeadings.length !== translatedHeadings.length || originalHeadings.some((heading, index) => heading.level !== translatedHeadings[index].level)) continue;
+    const occupied = new Set(translatedHeadings.map((heading) => heading.id).filter((id) => !!id));
+    for (const match of page.body.matchAll(/<a\s+id="([^"]+)"/g)) occupied.add(match[1]);
+    const originalIdCounts = /* @__PURE__ */ new Map();
+    for (const heading of originalHeadings) {
+      if (heading.id) originalIdCounts.set(heading.id, (originalIdCounts.get(heading.id) ?? 0) + 1);
+    }
+    const aliases = /* @__PURE__ */ new Map();
+    for (let index = 0; index < originalHeadings.length; index++) {
+      const id = originalHeadings[index].id;
+      if (!id || occupied.has(id) || originalIdCounts.get(id) !== 1) continue;
+      aliases.set(translatedHeadings[index].index, id);
+      occupied.add(id);
+    }
+    if (aliases.size) page.body = page.body.split("\n").flatMap((line, index) => {
+      const alias = aliases.get(index);
+      return alias ? [`<a id="${alias}"></a>`, line] : [line];
+    }).join("\n");
+  }
+}
+function expandDocusaurusDocCardLists(pages, config, sourceRoutes) {
+  const pageByRoute = new Map(pages.map((page) => [page.navigationId, page]));
+  const containsRoute = (items, route) => items.some((item) => typeof item === "string" ? item === route : containsRoute(item.pages, route));
+  const findGroup = (items, route) => {
+    for (const item of items) {
+      if (typeof item === "string" || !containsRoute(item.pages, route)) continue;
+      return findGroup(item.pages, route) ?? item;
+    }
+    return void 0;
+  };
+  const firstRoute = (items) => {
+    for (const item of items) {
+      if (typeof item === "string") return item;
+      const candidate = firstRoute(item.pages);
+      if (candidate) return candidate;
+    }
+    return void 0;
+  };
+  for (const page of pages) {
+    if (!sourceRoutes.has(page.navigationId)) continue;
+    const group = config.tabs.map((tab) => findGroup([
+      ...tab.pages ?? [],
+      ...tab.groups ?? []
+    ], page.navigationId)).find(Boolean);
+    if (!group) {
+      page.body = page.body.replace(/<div data-thally-doc-card-list=""\s*\/>/g, "");
+      continue;
+    }
+    const cards = group.pages.flatMap((item) => {
+      if (typeof item === "string") {
+        if (item === page.navigationId) return [];
+        const target = pageByRoute.get(item);
+        return [{ title: target?.title ?? item.split("/").at(-1) ?? item, route: item }];
+      }
+      const slug2 = slugifySegment(item.group);
+      const routes = [...item.pages].flatMap((child) => typeof child === "string" ? [child] : []);
+      const route = routes.find((candidate) => candidate === slug2 || candidate.endsWith(`/${slug2}`)) ?? firstRoute(item.pages);
+      return route ? [{ title: item.group, route }] : [];
+    });
+    const markup = cards.length ? `<CardGroup>
+${cards.map(({ title, route }) => `  <Card title={${JSON.stringify(title)}} href={${JSON.stringify(`/${route === "introduction" ? "" : route}`)}} />`).join("\n")}
+</CardGroup>` : "";
+    page.body = page.body.replace(/<div data-thally-doc-card-list=""\s*\/>/g, markup);
+    if (markup && !page.body.includes(markup)) page.body = [page.body.trim(), markup].filter(Boolean).join("\n\n");
+  }
+}
 function rewriteDocusaurusLinks(body, current, descriptors, options = {}) {
   const routes = /* @__PURE__ */ new Map();
   for (const descriptor of descriptors) {
@@ -3107,18 +3428,31 @@ function rewriteDocusaurusLinks(body, current, descriptors, options = {}) {
     const sourceRoute = pageIdFromReference(sourceKey);
     if (sourceRoute) routes.set(sourceRoute, descriptor.navigationId);
   }
-  const currentDirectory = posix.dirname(sourceReferenceKey(current.sourcePath));
+  const currentDirectory = posix2.dirname(sourceReferenceKey(current.sourcePath));
+  function copiedAssetTarget(target) {
+    if (!target.startsWith("/") || target.startsWith("//") || target.includes("\\")) return null;
+    const suffixIndex = target.search(/[?#]/);
+    const path = suffixIndex >= 0 ? target.slice(0, suffixIndex) : target;
+    const suffix = suffixIndex >= 0 ? target.slice(suffixIndex) : "";
+    if (path.startsWith("/docs/") && options.assetPaths?.has(path.slice("/docs/".length))) {
+      return `/${path.slice("/docs/".length)}${suffix}`;
+    }
+    return options.assetPaths?.has(path.slice(1)) ? target : null;
+  }
   function rewriteTarget(target) {
-    if (!target || target.startsWith("#") || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(target)) return target;
+    if (!target || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(target)) return target;
+    if (target.startsWith("#")) return target;
     const suffixIndex = target.search(/[?#]/);
     const path = suffixIndex >= 0 ? target.slice(0, suffixIndex) : target;
     const suffix = suffixIndex >= 0 ? target.slice(suffixIndex) : "";
+    const copiedAsset = copiedAssetTarget(target);
+    if (copiedAsset) return copiedAsset;
     const candidates = path.startsWith("/") ? [
       sourceReferenceKey(path),
       sourceReferenceKey(path).replace(/^docs\//, ""),
       sourceReferenceKey(path).replace(/^docs\/(?:next|current|latest)\//, "")
     ] : [
-      sourceReferenceKey(posix.normalize(posix.join(currentDirectory, path))),
+      sourceReferenceKey(posix2.normalize(posix2.join(currentDirectory, path))),
       sourceReferenceKey(path)
     ];
     const route = candidates.map((candidate) => routes.get(candidate)).find(Boolean);
@@ -3140,7 +3474,7 @@ function rewriteDocusaurusLinks(body, current, descriptors, options = {}) {
       return line;
     }
     if (codeFence) return line;
-    return line.replace(/(\]\()([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(target)}`).replace(/(\bhref=")([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(target)}${suffix}`).replace(/^(\s{0,3}\[[^\]]+\]:\s*)(<[^>]+>|\S+)/, (_match, prefix, destination) => {
+    return line.replace(/(\]\()([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(target)}`).replace(/(\bhref=")([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(target)}${suffix}`).replace(/(\bsrc=")([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${copiedAssetTarget(target) ?? target}${suffix}`).replace(/^(\s{0,3}\[[^\]]+\]:\s*)(<[^>]+>|\S+)/, (_match, prefix, destination) => {
       const bracketed = destination.startsWith("<") && destination.endsWith(">");
       const target = bracketed ? destination.slice(1, -1) : destination;
       const rewritten = rewriteTarget(target);
@@ -3161,7 +3495,7 @@ function readDocusaurusSiteOrigin(repositoryRoot) {
 }
 function readBoundedText(path) {
   if (lstatSync3(path).size > MAX_CONFIG_BYTES) {
-    throw new Error("Docusaurus sidebar config exceeded the 1 MB static-parser limit.");
+    throw new Error("The Docusaurus sidebar config is larger than 20 MB and could not be imported.");
   }
   return readFileSync3(path, "utf8");
 }
@@ -3418,7 +3752,7 @@ function readDocusaurusRedirects(repositoryRoot, warnings) {
 }
 function readCategoryMetadata(contentRoot, directory) {
   for (const filename of CATEGORY_FILENAMES) {
-    const path = resolveWithin(contentRoot, posix.join(directory, filename));
+    const path = resolveWithin(contentRoot, posix2.join(directory, filename));
     if (!existsSync3(path) || !lstatSync3(path).isFile()) continue;
     try {
       const raw = readBoundedText(path);
@@ -3463,7 +3797,7 @@ function generatedIndexPage(label, linkValue, context) {
   if (link.type !== "generated-index") return null;
   const fallback = `category/${slugifySegment(label)}`;
   const unprefixedNavigationId = typeof link.slug === "string" ? routeFromSlug(link.slug, fallback) ?? fallback : fallback;
-  const navigationId = context.routePrefix && unprefixedNavigationId !== context.routePrefix && !unprefixedNavigationId.startsWith(`${context.routePrefix}/`) ? posix.join(context.routePrefix, unprefixedNavigationId) : unprefixedNavigationId;
+  const navigationId = context.routePrefix && unprefixedNavigationId !== context.routePrefix && !unprefixedNavigationId.startsWith(`${context.routePrefix}/`) ? posix2.join(context.routePrefix, unprefixedNavigationId) : unprefixedNavigationId;
   if (!context.generatedIds.has(navigationId) && !context.descriptors.some((page) => page.navigationId === navigationId)) {
     const description = typeof link.description === "string" ? link.description : `Browse the ${label} documentation.`;
     context.generatedPages.push({
@@ -3601,7 +3935,7 @@ function staticStringField(source, name, bindings) {
   }
 }
 function readDocusaurusSiteSettings(repositoryRoot) {
-  const empty = { docsRouteBasePath: "docs", navbarLinks: [], footerLinks: [] };
+  const empty = { docsRouteBasePath: "docs", defaultColorMode: "light", navbarLinks: [], footerLinks: [] };
   const configPath = findDocusaurusConfigPath(repositoryRoot);
   if (!configPath) return empty;
   const source = readBoundedText(configPath);
@@ -3611,6 +3945,10 @@ function readDocusaurusSiteSettings(repositoryRoot) {
   const docsRouteBasePath = classicDocs && staticStringField(classicDocs, "routeBasePath") || "docs";
   const themeStart = propertyStart(source, "themeConfig");
   const theme = themeStart < 0 ? null : matchingObjectLiteral(source, themeStart);
+  const colorModeStart = theme ? propertyStart(theme, "colorMode") : -1;
+  const colorMode = colorModeStart < 0 ? null : matchingObjectLiteral(theme, colorModeStart);
+  const configuredColorMode = colorMode ? staticStringField(colorMode, "defaultMode") : void 0;
+  const defaultColorMode = configuredColorMode === "dark" ? "dark" : "light";
   const navbarStart = theme ? propertyStart(theme, "navbar") : -1;
   const navbar = navbarStart < 0 ? null : matchingObjectLiteral(theme, navbarStart);
   const logoStart = navbar ? propertyStart(navbar, "logo") : -1;
@@ -3646,6 +3984,8 @@ function readDocusaurusSiteSettings(repositoryRoot) {
   return {
     name: staticStringField(source, "title"),
     description: staticStringField(source, "tagline"),
+    ...navbar && staticStringField(navbar, "title") ? { navbarTitle: staticStringField(navbar, "title") } : {},
+    defaultColorMode,
     docsRouteBasePath,
     ...logo && staticStringField(logo, "src") ? {
       logo: {
@@ -3670,32 +4010,47 @@ function autogeneratedItems(dirName, context) {
   const childDirectories = /* @__PURE__ */ new Set();
   for (const descriptor of inDirectory) {
     const source = descriptor.sourcePath.replace(/\.(?:mdx?)$/i, "");
-    const relativePath = normalizedDir ? posix.relative(normalizedDir, source) : source;
+    const relativePath = normalizedDir ? posix2.relative(normalizedDir, source) : source;
     const segments = relativePath.split("/").filter(Boolean);
     if (segments.length <= 1) directPages.push(descriptor);
     else childDirectories.add(segments[0]);
   }
-  const items = directPages.sort(descriptorSort).map((descriptor) => {
-    context.referencedNavigationIds.add(descriptor.navigationId);
-    return descriptor.navigationId;
-  });
+  const pages = directPages.map((descriptor) => ({
+    // An index document is the category landing page in Docusaurus. Thally
+    // renders it as a child link, so put it before the category's other docs.
+    position: descriptor.sidebarPosition ?? (/(?:^|\/)(?:index|readme)\.mdx?$/i.test(descriptor.sourcePath) ? -1 : Number.MAX_SAFE_INTEGER),
+    sortKey: descriptor.sourcePath,
+    item: descriptor.navigationId
+  }));
   const groups = [...childDirectories].map((segment) => {
-    const directory = normalizedDir ? posix.join(normalizedDir, segment) : segment;
+    const directory = normalizedDir ? posix2.join(normalizedDir, segment) : segment;
     const metadata = readCategoryMetadata(context.contentRoot, directory);
-    const pages = autogeneratedItems(directory, context);
+    const pages2 = autogeneratedItems(directory, context);
+    if (pages2.length === 1 && typeof pages2[0] === "string" && !metadata.label && metadata.position === void 0 && !metadata.link) {
+      const onlyPage = context.descriptors.find((descriptor) => descriptor.navigationId === pages2[0]);
+      if (onlyPage && /(?:^|\/)(?:index|readme)\.mdx?$/i.test(onlyPage.sourcePath)) {
+        return {
+          position: onlyPage.sidebarPosition ?? Number.MAX_SAFE_INTEGER,
+          sortKey: segment,
+          item: pages2[0]
+        };
+      }
+    }
     const landing = generatedIndexPage(metadata.label ?? titleCase2(segment), metadata.link, context);
-    if (landing && !pages.includes(landing)) pages.unshift(landing);
+    if (landing && !pages2.includes(landing)) pages2.unshift(landing);
     return {
       position: metadata.position ?? Number.MAX_SAFE_INTEGER,
-      segment,
-      group: {
+      sortKey: segment,
+      item: {
         group: metadata.label ?? titleCase2(segment),
-        pages
+        pages: pages2
       }
     };
-  }).sort((left, right) => left.position - right.position || left.segment.localeCompare(right.segment, void 0, { numeric: true }));
-  items.push(...groups.map((entry) => entry.group));
-  return items;
+  });
+  return [...pages, ...groups].sort((left, right) => left.position - right.position || left.sortKey.localeCompare(right.sortKey, void 0, { numeric: true })).map(({ item }) => {
+    if (typeof item === "string") context.referencedNavigationIds.add(item);
+    return item;
+  });
 }
 function convertItems(value, context) {
   if (typeof value === "string") {
@@ -3772,7 +4127,7 @@ import { existsSync as existsSync4, lstatSync as lstatSync4, readFileSync as rea
 import { basename as basename2, dirname as dirname3, extname as extname4, relative as relative4 } from "path";
 import { load } from "cheerio";
 import { parse as parseYaml3 } from "yaml";
-var MAX_CONFIG_BYTES2 = 2e6;
+var MAX_CONFIG_BYTES2 = 2e7;
 function announcementMarkdown(message) {
   const document = load(message);
   document("script, style, iframe, object, embed, svg, math").remove();
@@ -3807,7 +4162,7 @@ function titleCase3(value) {
 }
 function readBoundedYaml(path) {
   if (lstatSync4(path).size > MAX_CONFIG_BYTES2) {
-    throw new Error("Fern config exceeded the 2 MB static-parser limit.");
+    throw new Error("The Fern config is larger than 20 MB and could not be imported.");
   }
   return parseYaml3(readFileSync4(path, "utf8"));
 }
@@ -3869,7 +4224,7 @@ function registerPageAt(rawPath, base, context, navTitle, hidden = false) {
   let sourcePath;
   try {
     const absolute = resolveWithinRoot(
-      context.pathPrefix ? resolveWithin(context.fernRoot, context.pathPrefix) : context.fernRoot,
+      context.pathPrefix ? resolveWithinRoot(context.fernRoot, context.pathPrefix, context.repositoryRoot) : context.fernRoot,
       rawPath.trim(),
       context.repositoryRoot
     );
@@ -3898,7 +4253,7 @@ function registerFolder(object, parentSegments, context) {
   let folder;
   try {
     folder = resolveWithinRoot(
-      context.pathPrefix ? resolveWithin(context.fernRoot, context.pathPrefix) : context.fernRoot,
+      context.pathPrefix ? resolveWithinRoot(context.fernRoot, context.pathPrefix, context.repositoryRoot) : context.fernRoot,
       rawPath,
       context.repositoryRoot
     );
@@ -3984,18 +4339,31 @@ function convertNode(node, parentSegments, context) {
     };
   }
   if (typeof object.link === "string") {
-    warnOnce2(
-      context,
-      "fern-link",
-      'Fern navigation "link" entries are external and cannot be nested inside a Thally group; add them to the navbar manually.'
-    );
+    const label = object.link.trim();
+    const rawHref = typeof object.href === "string" ? object.href.trim() : "";
+    let href;
+    if (/^https?:\/\//i.test(rawHref) && !/[\\\u0000-\u0020\u007f]/.test(rawHref)) {
+      try {
+        const url = new URL(rawHref);
+        if (["http:", "https:"].includes(url.protocol) && !url.username && !url.password) href = url.toString();
+      } catch {
+      }
+    }
+    if (label && href && object.hidden !== true && !context.hiddenInherited) {
+      if (!context.externalLinks.some((link) => link.label === label && link.href === href)) {
+        context.externalLinks.push({ label, href });
+      }
+    } else if (!href && object.hidden !== true && !context.hiddenInherited) {
+      warnOnce2(context, `fern-link-${rawHref}`, `Fern navigation link "${label}" has an unsafe or invalid external URL and was skipped.`);
+    }
     return null;
   }
   if (typeof object.api === "string") {
+    const ownSegment = segmentFor(object, object.api, context);
     context.apiSections.push({
       name: typeof object["api-name"] === "string" ? object["api-name"] : object.api,
       nameExplicit: typeof object["api-name"] === "string",
-      routeSegments: parentSegments
+      routeSegments: ownSegment ? [...parentSegments, ownSegment] : parentSegments
     });
     return null;
   }
@@ -4037,7 +4405,7 @@ function resolveVersionedNavigation(config, configDir, fernRoot, context) {
   }
   if (!chosen || typeof chosen.path !== "string") return config;
   try {
-    const versionPath = resolveWithinRoot(configDir, chosen.path, fernRoot);
+    const versionPath = resolveWithinRoot(configDir, chosen.path, context.repositoryRoot);
     if (!existsSync4(versionPath) || !lstatSync4(versionPath).isFile()) {
       warnOnce2(context, "fern-version-not-file", `Fern version file "${chosen.path}" is not a regular file and was skipped.`);
       return config;
@@ -4189,6 +4557,7 @@ function projectFernNavigation(input) {
     changelogIndexes: [],
     warnings: [],
     warningKeys: /* @__PURE__ */ new Set(),
+    externalLinks: [],
     bareRouteRedirects: [],
     segmentAliases: /* @__PURE__ */ new Map(),
     pathPrefix: "",
@@ -4209,6 +4578,11 @@ function projectFernNavigation(input) {
     const label = typeof link?.text === "string" ? link.text : typeof link?.label === "string" ? link.label : link?.type === "github" ? "GitHub" : void 0;
     return href && label ? [{ label, href, ...link?.type === "github" ? { type: "github" } : {} }] : [];
   }) : [];
+  for (const link of context.externalLinks) {
+    if (!navbarLinks.some((existing) => existing.label === link.label && existing.href === link.href)) {
+      navbarLinks.push(link);
+    }
+  }
   const announcement = objectValue3(config.announcement);
   const announcementMessage = typeof announcement?.message === "string" ? announcement.message.trim() : "";
   const bannerContent = announcementMarkdown(announcementMessage);
@@ -4269,7 +4643,16 @@ function projectFernNavigation(input) {
       return section;
     }
     const distinguishingSegment = section.routeSegments.at(-1);
-    const tabLabel = distinguishingSegment ? `${section.tabLabel}: ${titleCase3(distinguishingSegment)}` : section.tabLabel;
+    let tabLabel = distinguishingSegment ? `${section.tabLabel}: ${titleCase3(distinguishingSegment)}` : section.tabLabel;
+    if (!tabLabel || tabLabel === `${section.tabLabel}: ${section.tabLabel}` || claimedTabLabels.has(tabLabel)) {
+      let ordinal = 2;
+      let candidate = `${section.tabLabel} (${ordinal})`;
+      while (claimedTabLabels.has(candidate)) {
+        ordinal += 1;
+        candidate = `${section.tabLabel} (${ordinal})`;
+      }
+      tabLabel = candidate;
+    }
     claimedTabLabels.add(tabLabel);
     return { ...section, tabLabel };
   });
@@ -4319,11 +4702,14 @@ var ASSET_EXTENSIONS = /* @__PURE__ */ new Set([
   ".ico",
   ".jpeg",
   ".jpg",
+  ".m4a",
   ".mp3",
   ".mp4",
+  ".ogg",
   ".pdf",
   ".png",
   ".svg",
+  ".wav",
   ".webm",
   ".webp"
 ]);
@@ -4511,9 +4897,92 @@ function readDocusaurusConfigSource(projectRoot) {
   if (!path || lstatSync5(path).size > 1e6) return "";
   return readFileSync5(path, "utf8");
 }
+function matchingBraceIndex(source, openBraceIndex) {
+  let depth = 0;
+  for (let i = openBraceIndex; i < source.length; i++) {
+    const ch = source[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const quote = ch;
+      i++;
+      while (i < source.length && source[i] !== quote) {
+        if (source[i] === "\\") i++;
+        i++;
+      }
+      continue;
+    }
+    if (ch === "/" && source[i + 1] === "/") {
+      const newline = source.indexOf("\n", i);
+      i = newline === -1 ? source.length : newline;
+      continue;
+    }
+    if (ch === "/" && source[i + 1] === "*") {
+      const end = source.indexOf("*/", i + 2);
+      i = end === -1 ? source.length : end + 1;
+      continue;
+    }
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+function topLevelStringProperty(objectBody, key) {
+  let depth = 0;
+  const keyPattern = new RegExp(`^${key}\\s*:\\s*(['"])`);
+  for (let i = 0; i < objectBody.length; i++) {
+    const ch = objectBody[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const quote = ch;
+      i++;
+      while (i < objectBody.length && objectBody[i] !== quote) {
+        if (objectBody[i] === "\\") i++;
+        i++;
+      }
+      continue;
+    }
+    if (ch === "/" && objectBody[i + 1] === "/") {
+      const newline = objectBody.indexOf("\n", i);
+      i = newline === -1 ? objectBody.length : newline;
+      continue;
+    }
+    if (ch === "/" && objectBody[i + 1] === "*") {
+      const end = objectBody.indexOf("*/", i + 2);
+      i = end === -1 ? objectBody.length : end + 1;
+      continue;
+    }
+    if (ch === "{" || ch === "[" || ch === "(") {
+      depth++;
+      continue;
+    }
+    if (ch === "}" || ch === "]" || ch === ")") {
+      depth--;
+      continue;
+    }
+    if (depth === 0) {
+      const match = keyPattern.exec(objectBody.slice(i));
+      if (match) {
+        const quote = match[1];
+        const valueStart = i + match[0].length;
+        const valueEnd = objectBody.indexOf(quote, valueStart);
+        if (valueEnd !== -1) return objectBody.slice(valueStart, valueEnd);
+      }
+    }
+  }
+  return void 0;
+}
 function primaryDocusaurusDocsDirectory(projectRoot) {
   const source = readDocusaurusConfigSource(projectRoot);
-  const configured = source.match(/\bdocs\s*:\s*\{[\s\S]{0,4000}?\bpath\s*:\s*(['"])([^'"]+)\1/)?.[2];
+  const docsKeyMatch = source.match(/\bdocs\s*:\s*\{/);
+  let configured;
+  if (docsKeyMatch?.index !== void 0) {
+    const openBrace = docsKeyMatch.index + docsKeyMatch[0].length - 1;
+    const closeBrace = matchingBraceIndex(source, openBrace);
+    if (closeBrace !== -1) {
+      configured = topLevelStringProperty(source.slice(openBrace + 1, closeBrace), "path");
+    }
+  }
   return trimTrailingSlashes(configured?.replace(/^\.\//, "") ?? "") || "docs";
 }
 function docusaurusArchiveRoots(projectRoot, repositoryDir, warnings) {
@@ -4565,7 +5034,7 @@ function docusaurusArchiveRoots(projectRoot, repositoryDir, warnings) {
 function additionalDocusaurusPluginRoots(repositoryDir, projectRoot, warnings) {
   const source = readDocusaurusConfigSource(projectRoot);
   const plugins = [];
-  const matcher = /['"]@docusaurus\/plugin-content-docs['"][\s\S]{0,3000}?\bpath\s*:\s*(['"])([^'"]+)\1[\s\S]{0,1000}?\brouteBasePath\s*:\s*(['"])([^'"]+)\3/g;
+  const matcher = /['"](?:@docusaurus\/plugin-)?content-docs['"][\s\S]{0,3000}?\bpath\s*:\s*(['"])([^'"]+)\1[\s\S]{0,1000}?\brouteBasePath\s*:\s*(['"])([^'"]+)\3/g;
   for (const match of source.matchAll(matcher)) {
     const localPath = trimTrailingSlashes(match[2].replace(/^\.\//, ""));
     const routePrefix = trimEdgeSlashes(match[4]);
@@ -4803,8 +5272,10 @@ function detectRepositoryDocsDir(repositoryDir) {
   }
   return "";
 }
-function scanFiles(root, confinementRoot = root, warnings) {
+var MAX_RANKED_WALK_FILES = MAX_SOURCE_FILES * 20;
+function scanFiles(root, confinementRoot = root, warnings, rank) {
   const files = [];
+  const walkCap = rank ? MAX_RANKED_WALK_FILES : MAX_SOURCE_FILES;
   let confinementReal;
   try {
     confinementReal = realpathSync2(confinementRoot);
@@ -4813,7 +5284,7 @@ function scanFiles(root, confinementRoot = root, warnings) {
   }
   const visitedRealPaths = /* @__PURE__ */ new Set();
   function visit(directory, logicalDirectory = directory) {
-    if (files.length >= MAX_SOURCE_FILES) return;
+    if (files.length >= walkCap) return;
     let directoryReal;
     try {
       directoryReal = realpathSync2(directory);
@@ -4829,7 +5300,7 @@ function scanFiles(root, confinementRoot = root, warnings) {
       return;
     }
     for (const entry of entries) {
-      if (files.length >= MAX_SOURCE_FILES) return;
+      if (files.length >= walkCap) return;
       if (isIgnoredContentDirectory(entry.name)) {
         if (warnings && entry.isDirectory() && !entry.isSymbolicLink() && containsMarkdown(resolveWithin(directory, entry.name))) {
           warnings.push({
@@ -4866,8 +5337,44 @@ function scanFiles(root, confinementRoot = root, warnings) {
     }
   }
   visit(root);
+  if (rank && files.length >= walkCap) {
+    warnings?.push({
+      code: "limit-reached",
+      message: `Stopped scanning after ${walkCap} files, so the rest of the repository was not looked at. Run the migration on a smaller part of the repository with --docs-dir.`
+    });
+  }
   return files;
 }
+function selectGroupWithinBudget(scanned, rank, warnings, allVersionPrefixes, label) {
+  if (scanned.length <= MAX_SOURCE_FILES) return scanned;
+  const ranked = scanned.map((file) => ({ file, priority: rank(file.relativePath) })).sort((left, right) => left.priority - right.priority || (left.file.relativePath < right.file.relativePath ? -1 : left.file.relativePath > right.file.relativePath ? 1 : 0));
+  const dropped = ranked.slice(MAX_SOURCE_FILES).map(({ file }) => file);
+  if (warnings) {
+    const droppedPages = label === "file" ? dropped.filter((file) => isDocumentationExtension(file.relativePath)) : dropped;
+    const noun = label === "file" ? "page" : "image or media file";
+    const droppedVersions = /* @__PURE__ */ new Set();
+    for (const file of dropped) {
+      const firstSegment = file.relativePath.split("/", 1)[0];
+      if (allVersionPrefixes.has(firstSegment)) droppedVersions.add(firstSegment);
+    }
+    const examples = droppedPages.slice(0, 3).map((file) => file.relativePath);
+    const rest = droppedPages.length - examples.length;
+    warnings.push({
+      code: "limit-reached",
+      message: `This repository has more than ${MAX_SOURCE_FILES} ${label === "file" ? "files" : "assets"}, so only the first ${MAX_SOURCE_FILES} (in navigation order, default version first) were migrated. ${droppedPages.length} ${noun}(s) were left out` + (examples.length > 0 ? `: ${examples.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}` : "") + (droppedVersions.size > 0 ? ` (versions: ${[...droppedVersions].slice(0, 5).join(", ")}${droppedVersions.size > 5 ? `, and ${droppedVersions.size - 5} more` : ""})` : "") + (label === "file" ? ". To include them, run the migration on a smaller part of the repository with --docs-dir." : ". Copy them into public/ manually if your pages use them.")
+    });
+  }
+  return ranked.slice(0, MAX_SOURCE_FILES).map(({ file }) => file);
+}
+function selectFilesWithinBudget(scanned, rank, warnings, allVersionPrefixes) {
+  const isAsset = (file) => ASSET_EXTENSIONS.has(extname5(file.relativePath).toLowerCase());
+  const assetFiles = scanned.filter(isAsset);
+  const otherFiles = scanned.filter((file) => !isAsset(file));
+  return [
+    ...selectGroupWithinBudget(otherFiles, rank, warnings, allVersionPrefixes, "file"),
+    ...selectGroupWithinBudget(assetFiles, rank, warnings, allVersionPrefixes, "asset")
+  ];
+}
 function readMintignoreMatcher(mintlifyRoot) {
   const path = resolveWithin(mintlifyRoot, MINTIGNORE_FILENAME);
   if (!existsSync5(path) || !lstatSync5(path).isFile()) return null;
@@ -4942,7 +5449,7 @@ function mintlifyTopLevelApiReferences(config) {
   }
   return references;
 }
-function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings) {
+function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
   if (!mintlifyConfig) return [];
   const references = [
     ...mintlifyTopLevelApiReferences(mintlifyConfig),
@@ -4962,13 +5469,19 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings) {
       });
       continue;
     }
-    if (/^https?:\/\//i.test(reference.value)) {
+    if (/^https:\/\//i.test(reference.value)) {
+      remoteSpecs.push({ url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {} });
       warnings.push({
         code: "unsupported-config",
-        message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} was not downloaded. Download it manually, add it to public/, and set its API source in docs.json to the local path.`
+        message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} requires a network download before this import is complete.`,
+        source: reference.value
       });
       continue;
     }
+    if (/^http:\/\//i.test(reference.value)) {
+      warnings.push({ code: "unsupported-config", message: `The OpenAPI spec "${reference.value}"${tabSuffix} uses insecure HTTP and was not imported.`, source: reference.value });
+      continue;
+    }
     const key = reference.value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/");
     const match = files.find((file) => file.relativePath === key);
     if (!match) {
@@ -4978,10 +5491,159 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings) {
       });
       continue;
     }
-    specs.push({ filename: basename3(match.relativePath), content: readFileSync5(match.absolutePath), tabLabel: reference.tabLabel });
+    if (reference.directory) {
+      warnings.push({
+        code: "unsupported-config",
+        message: `The OpenAPI spec "${reference.value}"${tabSuffix} was limited to pages under "${reference.directory}" in the source, but Thally's API reference always covers a whole tab, so it was migrated as the tab's full API reference. Update any links to "${reference.directory}/..." pages manually.`
+      });
+    }
+    specs.push({
+      filename: basename3(match.relativePath),
+      content: readFileSync5(match.absolutePath),
+      tabLabel: reference.tabLabel,
+      sourcePath: match.relativePath,
+      directory: reference.directory
+    });
+  }
+  const filenameOwners = /* @__PURE__ */ new Map();
+  for (const spec of specs) {
+    const groupKey = spec.tabLabel ?? "\0default";
+    const owner = filenameOwners.get(spec.filename);
+    if (owner !== void 0 && owner !== groupKey) {
+      let disambiguated = spec.sourcePath.replace(/\//g, "-");
+      while (filenameOwners.has(disambiguated) && filenameOwners.get(disambiguated) !== groupKey) {
+        disambiguated = `${groupKey.replace(/\W+/g, "-")}-${disambiguated}`;
+      }
+      spec.filename = disambiguated;
+    }
+    filenameOwners.set(spec.filename, groupKey);
   }
   return specs;
 }
+var OPENAPI_HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
+var FERN_CRUD_METHOD_NAMES = {
+  findall: "list",
+  findone: "get",
+  remove: "delete"
+};
+function mintlifyOperationSlugSegment(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+function thallyOperationSlugSegments(path, method) {
+  const cleaned = path.split("/").filter(Boolean).map((segment) => segment.replace(/[{}]/g, "").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").toLowerCase());
+  if (!cleaned.length) cleaned.push("root");
+  cleaned.push(method.toLowerCase());
+  return cleaned;
+}
+function slugifyApiSpecId(value) {
+  return value.toLowerCase().replace(/[^a-z0-9/]+/g, "-").replace(/(^-|-$)+/g, "").replace(/\//g, "-") || value.toLowerCase();
+}
+function parseOpenApiOperationsForLinking(content) {
+  let document;
+  try {
+    document = parseYaml4(content.toString("utf8"));
+  } catch {
+    return [];
+  }
+  const paths = document && typeof document === "object" ? document.paths : null;
+  if (!paths || typeof paths !== "object") return [];
+  const operations = [];
+  for (const [path, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== "object") continue;
+    for (const method of OPENAPI_HTTP_METHODS) {
+      const operation = pathItem[method];
+      if (!operation || typeof operation !== "object") continue;
+      const op = operation;
+      const tags = Array.isArray(op.tags) ? op.tags.filter((tag) => typeof tag === "string") : [];
+      operations.push({
+        method,
+        path,
+        tag: tags[0],
+        summary: typeof op.summary === "string" ? op.summary : void 0,
+        operationId: typeof op.operationId === "string" ? op.operationId : void 0
+      });
+    }
+  }
+  return operations;
+}
+function apiOperationLinkMap(sources, docsConfig) {
+  const map = /* @__PURE__ */ new Map();
+  const prefixLandings = /* @__PURE__ */ new Map();
+  const apiTabs = docsConfig.tabs.filter((tab) => !tab.hidden && tab.api);
+  apiTabs.forEach((tab, index) => {
+    const source = sources.find((entry) => tab.api?.source === `/${entry.filename}`);
+    if (!source || !source.prefix) return;
+    const specId = index === 0 ? "default" : slugifyApiSpecId(tab.tab);
+    const prefix = source.prefix.replace(/^\/+|\/+$/g, "").toLowerCase();
+    if (prefix) prefixLandings.set(prefix, specId === "default" ? "/api" : `/api/${specId}`);
+    for (const operation of parseOpenApiOperationsForLinking(source.content)) {
+      const thallyHref = `/api/${specId}/${thallyOperationSlugSegments(operation.path, operation.method).join("/")}`;
+      const leafCandidates = /* @__PURE__ */ new Set();
+      if (operation.operationId) {
+        const parts = operation.operationId.split(/[_.]/).filter(Boolean);
+        const lastPart = parts.at(-1) ?? operation.operationId;
+        const conventional = FERN_CRUD_METHOD_NAMES[lastPart.toLowerCase()];
+        if (conventional) leafCandidates.add(conventional);
+        leafCandidates.add(mintlifyOperationSlugSegment(lastPart));
+      }
+      if (operation.summary) leafCandidates.add(mintlifyOperationSlugSegment(operation.summary));
+      if (operation.operationId) leafCandidates.add(mintlifyOperationSlugSegment(operation.operationId));
+      leafCandidates.add(mintlifyOperationSlugSegment(`${operation.method} ${operation.path}`));
+      const tagSegment = mintlifyOperationSlugSegment(operation.tag ?? "default");
+      for (const leaf of leafCandidates) {
+        if (!leaf) continue;
+        const tagged = `${source.prefix}/${tagSegment}/${leaf}`.replace(/^\/+|\/+$/g, "").toLowerCase();
+        const flat = `${source.prefix}/${leaf}`.replace(/^\/+|\/+$/g, "").toLowerCase();
+        if (!map.has(tagged)) map.set(tagged, thallyHref);
+        if (!map.has(flat)) map.set(flat, thallyHref);
+      }
+    }
+  });
+  return { operationLinks: map, prefixLandings };
+}
+function rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings) {
+  if (operationLinks.size === 0 && prefixLandings.size === 0) return;
+  const unmatched = /* @__PURE__ */ new Set();
+  for (const page of pages) {
+    page.body = rewriteApiOperationLinks(page.body, operationLinks, prefixLandings, unmatched);
+  }
+  if (unmatched.size === 0) return;
+  const sorted = [...unmatched].sort();
+  warnings.push({
+    code: "unsupported-config",
+    message: `${sorted.length} link(s) to API endpoints matched no endpoint in the OpenAPI spec, so they now point to the API section's overview page instead: ${sorted.slice(0, 10).join(", ")}${sorted.length > 10 ? `, and ${sorted.length - 10} more` : ""}. Update those links if you want them to reach a specific endpoint.`
+  });
+}
+function rewriteApiOperationLinks(body, linkMap, prefixLandings, unmatched) {
+  if (linkMap.size === 0 && prefixLandings.size === 0) return body;
+  const orderedPrefixes = [...prefixLandings.entries()].sort((a, b) => b[0].length - a[0].length);
+  let codeFence = null;
+  return body.split("\n").map((line) => {
+    const fence = line.match(/^\s*(`{3,}|~{3,})/);
+    if (fence) {
+      if (!codeFence) codeFence = fence[1][0];
+      else if (fence[1][0] === codeFence) codeFence = null;
+      return line;
+    }
+    if (codeFence) return line;
+    const rewriteTarget = (target) => {
+      const suffixIndex = target.search(/[?#]/);
+      const path = (suffixIndex >= 0 ? target.slice(0, suffixIndex) : target).replace(/^\/+/, "").toLowerCase();
+      const suffix = suffixIndex >= 0 ? target.slice(suffixIndex) : "";
+      const mapped = linkMap.get(path);
+      if (mapped) return `${mapped}${suffix}`;
+      for (const [prefix, landing] of orderedPrefixes) {
+        if (path === prefix) return `${landing}${suffix}`;
+        if (path.startsWith(`${prefix}/`)) {
+          unmatched.add(target);
+          return `${landing}${suffix}`;
+        }
+      }
+      return target;
+    };
+    return line.replace(/(\]\()\/([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(`/${target}`)}`).replace(/(\bhref=")\/([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(`/${target}`)}${suffix}`);
+  }).join("\n");
+}
 var MAX_FERN_GENERATORS_BYTES = 2e6;
 function fernGeneratorsOpenApiPaths(config) {
   const api = config.api;
@@ -5364,9 +6026,9 @@ function addDatedHeadingAliases(body, date) {
     if (open) return [line];
     const heading = line.match(/^#{2,6}\s+(.+?)\s*#*\s*$/);
     if (!heading) return [line];
-    const slug = heading[1].replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[`*_]/g, "").normalize("NFKD").toLowerCase().replace(/[^\p{L}\p{N}\s-]/gu, "").trim().replace(/\s+/g, "-");
-    const id = `${date}-${slug}`;
-    if (!slug || existingIds.has(id)) return [line];
+    const slug2 = heading[1].replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[`*_]/g, "").normalize("NFKD").toLowerCase().replace(/[^\p{L}\p{N}\s-]/gu, "").trim().replace(/\s+/g, "-");
+    const id = `${date}-${slug2}`;
+    if (!slug2 || existingIds.has(id)) return [line];
     existingIds.add(id);
     return [`<a id="${id}" />`, "", line];
   }).join("\n");
@@ -5598,17 +6260,27 @@ ${result.slice(prefix.length)}`;
   }
   return depth === 0 ? hoistMdxImports(result) : result;
 }
-function injectOpenApiSpecs(config, specs) {
+function injectOpenApiSpecs(config, specs, warnings) {
   let tabs = config.tabs.map((tab) => ({ ...tab }));
   for (const spec of specs) {
     const apiTab = spec.tabLabel ? tabs.find((tab) => tab.tab === spec.tabLabel) : tabs.find((tab) => tab.tab.toLowerCase().includes("api"));
-    if (apiTab) apiTab.api = {
-      source: `/${spec.filename}`,
-      // An API-only tab needs generated endpoint navigation; an authored
-      // page tab keeps its own groups alongside the bound spec.
-      ...apiTab.groups?.length || apiTab.pages?.length ? { navigation: false } : {}
-    };
-    else tabs = [...tabs, { tab: spec.tabLabel ?? "API Reference", api: { source: `/${spec.filename}` } }];
+    if (apiTab) {
+      if (apiTab.api && warnings) {
+        warnings.push({
+          code: "unsupported-config",
+          message: `Tab "${apiTab.tab}" already uses another OpenAPI spec, and Thally supports one API spec per tab, so "/${spec.filename}" was not added. Put it in its own tab to include it.`
+        });
+        continue;
+      }
+      apiTab.api = {
+        source: `/${spec.filename}`,
+        // An API-only tab needs generated endpoint navigation; an authored
+        // page tab keeps its own groups alongside the bound spec.
+        ...apiTab.groups?.length || apiTab.pages?.length ? { navigation: false } : {}
+      };
+    } else {
+      tabs = [...tabs, { tab: spec.tabLabel ?? "API Reference", api: { source: `/${spec.filename}` } }];
+    }
   }
   return { ...config, tabs };
 }
@@ -5648,6 +6320,8 @@ function migrateRepository(options) {
   const componentRoot = mintlifyProjectRoot ?? docusaurusProjectRoot ?? fernProjectRoot ?? repositoryDir;
   const componentMigrator = platform === "mintlify" || platform === "docusaurus" || platform === "fern" ? createComponentMigrator(componentRoot, repositoryDir, warnings, componentSourceIdentity(options.sourceUrl, repositoryDir, componentRoot)) : void 0;
   let docsConfig = { tabs: [] };
+  let defaultVersionPrefixes = /* @__PURE__ */ new Set();
+  let allVersionPrefixes = /* @__PURE__ */ new Set();
   const referenceMap = /* @__PURE__ */ new Map();
   const exactReferenceMap = /* @__PURE__ */ new Map();
   const referenceOrder = /* @__PURE__ */ new Map();
@@ -5657,6 +6331,7 @@ function migrateRepository(options) {
   let fernBasePath = "";
   let fernVersionPath = "";
   let fernApiSections = [];
+  const fernExternalSourcePaths = /* @__PURE__ */ new Set();
   let fernChangelogIndexes = [];
   const fernReferencedPaths = /* @__PURE__ */ new Set();
   const fernSourceLinkAliases = /* @__PURE__ */ new Map();
@@ -5667,6 +6342,8 @@ function migrateRepository(options) {
       const config = readMintlifyConfig(mintlifyProjectRoot ?? repositoryDir);
       if (config) {
         mintlifyConfig = config;
+        defaultVersionPrefixes = mintlifyDefaultVersionPrefixes(config);
+        allVersionPrefixes = mintlifyAllVersionPrefixes(config);
         const projected = projectMintlifyNavigation(config);
         docsConfig = projected.docsConfig;
         warnings.push(...projected.warnings);
@@ -5717,6 +6394,7 @@ function migrateRepository(options) {
           const exactKey = exactReferenceKey(descriptor.sourcePath);
           if (!exactReferenceMap.has(exactKey)) exactReferenceMap.set(exactKey, { navigationId: descriptor.navigationId });
           if (!referenceOrder.has(key)) referenceOrder.set(key, index);
+          if (descriptor.sourcePath.startsWith("../")) fernExternalSourcePaths.add(descriptor.sourcePath);
         }
       }
     } catch (error) {
@@ -5741,15 +6419,35 @@ function migrateRepository(options) {
     throw new Error(`Documentation directory does not exist: ${configuredDocsDir || "."}`);
   }
   const mintignoreMatcher = platform === "mintlify" && mintlifyProjectRoot ? readMintignoreMatcher(mintlifyProjectRoot) : null;
-  const files = mintignoreMatcher ? scanFiles(contentRoot, repositoryDir, warnings).filter((file) => !mintignoreMatcher.ignores(file.relativePath)) : scanFiles(contentRoot, repositoryDir, warnings);
+  const lastReferencedIndexByVersionLocale = /* @__PURE__ */ new Map();
+  for (const [key, index] of referenceOrder) {
+    const blockKey = key.split("/").slice(0, 2).join("/");
+    const current = lastReferencedIndexByVersionLocale.get(blockKey);
+    if (current === void 0 || index > current) lastReferencedIndexByVersionLocale.set(blockKey, index);
+  }
+  const discoveryRank = referenceOrder.size > 0 ? (relativePath) => {
+    const referencedIndex = referenceOrder.get(normalizedReferenceKey(relativePath));
+    if (referencedIndex !== void 0) return referencedIndex;
+    const blockKey = relativePath.split("/").slice(0, 2).join("/");
+    const versionCeiling = lastReferencedIndexByVersionLocale.get(blockKey);
+    return versionCeiling !== void 0 ? versionCeiling + 1 : Number.MAX_SAFE_INTEGER;
+  } : void 0;
+  const scannedFiles = scanFiles(contentRoot, repositoryDir, warnings, discoveryRank);
+  const mintignoreFilteredFiles = mintignoreMatcher ? scannedFiles.filter((file) => !mintignoreMatcher.ignores(file.relativePath)) : scannedFiles;
+  const discoveryBudgetApplied = discoveryRank !== void 0 && mintignoreFilteredFiles.length > MAX_SOURCE_FILES;
+  const files = discoveryRank ? selectFilesWithinBudget(mintignoreFilteredFiles, discoveryRank, warnings, allVersionPrefixes) : mintignoreFilteredFiles;
   if (platform === "fern" && fernProjectRoot) {
-    const scanned = new Set(files.map((file) => file.absolutePath));
-    for (const sourcePath of fernReferencedPaths) {
+    const discovered2 = new Set(files.map((file) => file.relativePath));
+    for (const sourcePath of fernExternalSourcePaths) {
+      if (discovered2.has(sourcePath)) continue;
       try {
         const absolutePath = resolveWithinRoot(fernProjectRoot, sourcePath, repositoryDir);
-        if (scanned.has(absolutePath) || !existsSync5(absolutePath) || !lstatSync5(absolutePath).isFile()) continue;
-        files.push({ absolutePath, relativePath: sourcePath });
-        scanned.add(absolutePath);
+        if (existsSync5(absolutePath) && lstatSync5(absolutePath).isFile()) {
+          files.push({ absolutePath, relativePath: sourcePath });
+          discovered2.add(sourcePath);
+        } else {
+          warnings.push({ code: "missing-page", message: "A Fern navigation path could not be read within this repository.", source: sourcePath });
+        }
       } catch {
         warnings.push({ code: "missing-page", message: "A Fern navigation path could not be read within this repository.", source: sourcePath });
       }
@@ -5757,6 +6455,7 @@ function migrateRepository(options) {
   }
   const pages = [];
   const assets = [];
+  const remoteApiSpecs = [];
   const referencedAssetPaths = /* @__PURE__ */ new Map();
   const addAssetReference = (assetPath, referencingPage) => {
     const referrers = referencedAssetPaths.get(assetPath);
@@ -5764,6 +6463,7 @@ function migrateRepository(options) {
     else referencedAssetPaths.set(assetPath, /* @__PURE__ */ new Set([referencingPage]));
   };
   const docusaurusDescriptors = [];
+  const docusaurusDocCardRoutes = /* @__PURE__ */ new Set();
   const seenPageIds = /* @__PURE__ */ new Set();
   const fernIdRenames = /* @__PURE__ */ new Map();
   let skipped = 0;
@@ -5833,6 +6533,9 @@ function migrateRepository(options) {
       mintlifyProjectRoot ?? docusaurusProjectRoot ?? fernProjectRoot ?? repositoryDir,
       snippetAliases
     );
+    if (platform === "fern" || platform === "mintlify" || platform === "docusaurus") {
+      raw = normalizeExplicitHeadingIds(raw);
+    }
     if (componentMigrator) {
       const warningsBeforeTransform = warnings.length;
       raw = componentMigrator.transform(raw, file.absolutePath);
@@ -5858,6 +6561,10 @@ function migrateRepository(options) {
       }
       raw = escapeFernLiteralBraces(protectedMath.body);
     }
+    const hasDocusaurusDocCardList = platform === "docusaurus" && /<DocCardList\b[^>]*\/>/.test(raw);
+    if (hasDocusaurusDocCardList) {
+      raw = raw.replace(/<DocCardList\b[^>]*\/>/g, '<div data-thally-doc-card-list="" />');
+    }
     let docusaurusDescriptor;
     const page = parseMarkdownPage({
       id,
@@ -5891,9 +6598,9 @@ function migrateRepository(options) {
       // hierarchy (never just its own segment) and wins over a docs.yml slug.
       ...platform === "fern" ? {
         resolveIdentity: (frontmatter, fallback) => {
-          const slug = typeof frontmatter.slug === "string" ? frontmatter.slug.trim() : "";
-          if (!slug) return fallback;
-          const overridden = pageIdFromReference(slug, true);
+          const slug2 = typeof frontmatter.slug === "string" ? frontmatter.slug.trim() : "";
+          if (!slug2) return fallback;
+          const overridden = pageIdFromReference(slug2, true);
           if (!overridden) return fallback;
           fernIdRenames.set(fallback.navigationId, overridden);
           return { ...fallback, id: overridden, navigationId: overridden };
@@ -5904,6 +6611,13 @@ function migrateRepository(options) {
       skipped++;
       continue;
     }
+    if (page.frontmatterError) {
+      warnings.push({
+        code: "unsupported-config",
+        message: `The page's frontmatter is not valid YAML (${page.frontmatterError}); the page was kept and as much of its metadata as could be read was used.`,
+        source: relative5(repositoryDir, file.absolutePath).replace(/\\/g, "/")
+      });
+    }
     if (platform === "fern" && !page.navTitle) {
       const navTitle = fernNavTitles.get(navigationId);
       if (navTitle && navTitle !== page.title) page.navTitle = navTitle;
@@ -5918,6 +6632,9 @@ function migrateRepository(options) {
       page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, fernProjectRoot, (assetPath) => {
         addAssetReference(assetPath, file.relativePath);
       });
+      page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, repositoryDir, (assetPath) => {
+        addAssetReference(assetPath, file.relativePath);
+      });
       page.body = stripFernBasePathFromLinks(page.body, fernBasePath);
       page.body = stripFernBasePathFromLinks(page.body, fernVersionPath);
     }
@@ -5972,11 +6689,21 @@ function migrateRepository(options) {
     }
     seenPageIds.add(page.id);
     pages.push(page);
+    if (hasDocusaurusDocCardList) {
+      docusaurusDocCardRoutes.add(page.navigationId);
+    }
     if (platform === "mintlify") {
       const sourcePath = exactReferenceKey(file.relativePath);
       if (sourcePath !== page.id && /^[A-Za-z0-9_./-]+$/.test(sourcePath)) {
         routeAliases.push({ source: `/${sourcePath}`, destination: `/${page.id}`, permanent: false });
       }
+      const versionPrefix = [...defaultVersionPrefixes].find((prefix) => sourcePath === prefix || sourcePath.startsWith(`${prefix}/`));
+      if (versionPrefix) {
+        const unversioned = sourcePath.slice(versionPrefix.length).replace(/^\/+/, "");
+        if (unversioned && unversioned !== sourcePath && unversioned !== page.id && /^[A-Za-z0-9_./-]+$/.test(unversioned) && !routeAliases.some((redirect) => redirect.source === `/${unversioned}`)) {
+          routeAliases.push({ source: `/${unversioned}`, destination: `/${page.id}`, permanent: false });
+        }
+      }
     }
     if (docusaurusDescriptor) {
       docusaurusDescriptors.push({ ...docusaurusDescriptor, title: page.title });
@@ -5989,6 +6716,43 @@ function migrateRepository(options) {
     }
   }
   const docusaurusAssetRoot = docusaurusProjectRoot ?? repositoryDir;
+  const fernBrandAssetPaths = /* @__PURE__ */ new Map();
+  const fernReferencedAssets = [];
+  if (platform === "fern" && fernProjectRoot) {
+    const seen = /* @__PURE__ */ new Set();
+    const addFernAsset = (candidate, source) => {
+      try {
+        const absolutePath = source ? resolveWithinRoot(fernProjectRoot, source.replace(/^\/+/, ""), repositoryDir) : resolveWithin(repositoryDir, candidate);
+        if (!existsSync5(absolutePath) || !lstatSync5(absolutePath).isFile()) return;
+        const realRoot = realpathSync2(repositoryDir);
+        const realPath = realpathSync2(absolutePath);
+        const confined = relative5(realRoot, realPath);
+        if (confined === ".." || confined.startsWith(`..${sep2}`) || isAbsolute2(confined)) return;
+        const withinFern = relative5(fernProjectRoot, absolutePath);
+        const assetRelative = withinFern !== ".." && !withinFern.startsWith(`..${sep2}`) && !isAbsolute2(withinFern) ? withinFern : relative5(repositoryDir, absolutePath);
+        const assetPath = normalizeAssetPath(assetRelative.replace(/\\/g, "/"));
+        if (!assetPath || !ASSET_EXTENSIONS.has(extname5(assetPath).toLowerCase())) return;
+        if (source) {
+          fernBrandAssetPaths.set(source, assetPath);
+          addAssetReference(assetPath, "fern/docs.yml");
+        }
+        if (seen.has(absolutePath)) return;
+        seen.add(absolutePath);
+        fernReferencedAssets.push({ absolutePath, relativePath: assetPath });
+      } catch {
+      }
+    };
+    for (const path of referencedAssetPaths.keys()) addFernAsset(path);
+    for (const value of [fernRawConfig?.logo, fernRawConfig?.favicon]) {
+      if (typeof value === "string") addFernAsset("", value);
+      else if (value && typeof value === "object" && !Array.isArray(value)) {
+        const variants = value;
+        for (const candidate of [variants.light, variants.dark, variants.src, variants.srcDark]) {
+          if (typeof candidate === "string") addFernAsset("", candidate);
+        }
+      }
+    }
+  }
   const repositoryAssets = platform === "docusaurus" && configuredDocsDir && !options.docusaurusSkipAssets ? ["static", "public"].flatMap((directory) => {
     const root = resolveWithin(docusaurusAssetRoot, directory);
     if (!existsSync5(root) || !lstatSync5(root).isDirectory()) return [];
@@ -5998,10 +6762,10 @@ function migrateRepository(options) {
     }));
   }) : [];
   const assetCandidates = [];
-  for (const file of [...files, ...repositoryAssets]) {
+  for (const file of [...files, ...repositoryAssets, ...fernReferencedAssets]) {
     const firstSegment = file.relativePath.split("/", 1)[0].toLowerCase();
     if (!ASSET_EXTENSIONS.has(extname5(file.relativePath).toLowerCase())) continue;
-    if (platform !== "mintlify" && !ASSET_DIRECTORIES.has(firstSegment)) continue;
+    if (platform !== "mintlify" && !ASSET_DIRECTORIES.has(firstSegment) && !(platform === "fern" && referencedAssetPaths.has(file.relativePath))) continue;
     const isDocusaurusStatic = platform === "docusaurus" && firstSegment === "static";
     const assetPath = normalizeAssetPath(firstSegment === "public" ? file.relativePath.slice("public/".length) : isDocusaurusStatic ? file.relativePath.slice("static/".length) : file.relativePath);
     if (!assetPath) continue;
@@ -6018,7 +6782,7 @@ function migrateRepository(options) {
       const referencingPages = referencedAssetPaths.get(assetPath);
       warnings.push({
         code: "limit-reached",
-        message: referencingPages ? `Asset was skipped because the migration asset budget was exhausted, but it is referenced by: ${[...referencingPages].join(", ")}.` : "An asset was skipped because the migration asset budget was exhausted.",
+        message: "This file was not copied because it is larger than 25 MB or the copied files would exceed 500 MB in total. Add it to public/ manually" + (referencingPages ? `; it is used by ${[...referencingPages].slice(0, 3).join(", ")}${referencingPages.size > 3 ? `, and ${referencingPages.size - 3} more` : ""}.` : "."),
         source: file.relativePath
       });
       continue;
@@ -6035,8 +6799,8 @@ function migrateRepository(options) {
     assets.push({ path: assetPath, content });
     totalAssetBytes += size;
   }
-  if (files.length >= MAX_SOURCE_FILES) {
-    warnings.push({ code: "limit-reached", message: `Repository discovery stopped at ${MAX_SOURCE_FILES} files.` });
+  if (!discoveryBudgetApplied && files.length >= MAX_SOURCE_FILES) {
+    warnings.push({ code: "limit-reached", message: `Stopped scanning after ${MAX_SOURCE_FILES} files, so the rest of the repository was not looked at. Run the migration on a smaller part of the repository with --docs-dir.` });
   }
   if (platform === "docusaurus") {
     const projected = projectDocusaurusNavigation({
@@ -6047,6 +6811,7 @@ function migrateRepository(options) {
       routePrefix: options.docusaurusRoutePrefix
     });
     docsConfig = projected.docsConfig;
+    expandDocusaurusDocCardLists(pages, docsConfig, docusaurusDocCardRoutes);
     warnings.push(...projected.warnings);
     for (const page of projected.generatedPages) {
       if (seenPageIds.has(page.id)) continue;
@@ -6062,7 +6827,8 @@ function migrateRepository(options) {
       const descriptor = descriptorByNavigationId.get(page.navigationId);
       if (descriptor) page.body = rewriteDocusaurusLinks(page.body, descriptor, docusaurusDescriptors, {
         sourceOrigin,
-        onExternalLink: (target) => externalizedLinks.add(target)
+        onExternalLink: (target) => externalizedLinks.add(target),
+        assetPaths: new Set(assets.map((asset) => asset.path))
       });
     }
     if (externalizedLinks.size > 0) warnings.push({
@@ -6120,10 +6886,11 @@ function migrateRepository(options) {
           filename = `${prefix}${filename}`;
         }
         specFilenameSources.set(filename, spec.absolutePath);
+        const specContent = readFileSync5(spec.absolutePath);
         if (!assets.some((asset) => asset.path === filename)) {
-          assets.push({ path: filename, content: readFileSync5(spec.absolutePath) });
+          assets.push({ path: filename, content: specContent });
         }
-        resolvedSpecs.push({ filename, tabLabel: section.tabLabel });
+        resolvedSpecs.push({ filename, tabLabel: section.tabLabel, content: specContent, routeSegments: section.routeSegments ?? [] });
         continue;
       }
       if (resolution.unsupported.length > 0) {
@@ -6151,16 +6918,28 @@ function migrateRepository(options) {
         message: checked.length ? `No OpenAPI/AsyncAPI spec could be found for the "${section.name}" API. Checked: ${checked.join(", ")}. Point generators.yml at a spec file that exists.` : `No OpenAPI/AsyncAPI spec could be found for the "${section.name}" API, because its api-name is not a valid folder name. Add the spec manually.`
       });
     }
-    if (resolvedSpecs.length > 0) docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs);
+    if (resolvedSpecs.length > 0) {
+      docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs, warnings);
+      const { operationLinks, prefixLandings } = apiOperationLinkMap(
+        resolvedSpecs.map((spec) => ({ filename: spec.filename, content: spec.content, prefix: spec.routeSegments.join("/") })),
+        docsConfig
+      );
+      rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings);
+    }
   } else if (platform === "mintlify") {
-    const resolvedSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings);
+    const resolvedSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs);
     for (const spec of resolvedSpecs) {
       if (!assets.some((asset) => asset.path === spec.filename)) {
         assets.push({ path: spec.filename, content: spec.content });
       }
     }
     if (resolvedSpecs.length > 0) {
-      docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs);
+      docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs, warnings);
+      const { operationLinks, prefixLandings } = apiOperationLinkMap(
+        resolvedSpecs.map((spec) => ({ filename: spec.filename, content: spec.content, prefix: spec.directory })),
+        docsConfig
+      );
+      rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings);
     } else {
       const fallback = findOpenApi(files);
       if (fallback) {
@@ -6193,7 +6972,7 @@ function migrateRepository(options) {
     ];
     for (const plugin of additionalRoots) {
       if (discovered >= MAX_SOURCE_FILES) {
-        warnings.push({ code: "limit-reached", message: `Docusaurus docs import stopped at the ${MAX_SOURCE_FILES}-file discovery budget.` });
+        warnings.push({ code: "limit-reached", message: `Stopped importing Docusaurus docs plugins after ${MAX_SOURCE_FILES} files; the remaining plugin docs were not migrated.` });
         break;
       }
       if (plugin.docsDir === configuredDocsDir) continue;
@@ -6234,6 +7013,15 @@ function migrateRepository(options) {
     }
   }
   if (platform === "docusaurus") {
+    const copiedAssets = new Set(assets.map((asset) => asset.path));
+    for (const page of pages) {
+      page.body = rewriteDocusaurusLinks(page.body, {
+        sourcePath: page.source ?? page.navigationId,
+        docId: page.navigationId,
+        navigationId: page.navigationId,
+        title: page.title
+      }, [], { assetPaths: copiedAssets });
+    }
     const importedRoutes = new Set(pages.map((page) => page.navigationId));
     docsConfig.tabs = docsConfig.tabs.map((tab) => {
       if (tab.href) return tab;
@@ -6293,6 +7081,27 @@ ${body}`;
     }
   }
   docsConfig = pruneMissingNavigationPages(docsConfig, new Set(pages.map((page) => page.navigationId)));
+  if (platform === "docusaurus") addDocusaurusTranslatedHeadingAliases(pages);
+  if (platform === "fern" && fernProjectRoot) {
+    const sourcePath = (page) => {
+      const fragment = page.source.split("#", 2)[1];
+      if (!fragment) return null;
+      try {
+        return relative5(fernProjectRoot, resolveWithin(repositoryDir, decodeURIComponent(fragment))).replace(/\\/g, "/");
+      } catch {
+        return null;
+      }
+    };
+    const routes = /* @__PURE__ */ new Map();
+    for (const page of pages) {
+      const source = sourcePath(page);
+      if (source) routes.set(source, page.id);
+    }
+    for (const page of pages) {
+      const source = sourcePath(page);
+      if (source) page.body = rewriteFernRelativePageLinks(page.body, source, routes);
+    }
+  }
   preserveLinkedAnchors(pages);
   if (platform === "fern" && fernRawConfig) {
     const sourceSiteUrl = fernSourceSiteUrl(fernRawConfig);
@@ -6410,7 +7219,7 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
   const assetPaths = new Set(assets.map((asset) => asset.path));
   const publicBrandPath = (value) => {
     if (typeof value !== "string" || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(value)) return void 0;
-    const normalized = normalizeAssetPath(value);
+    const normalized = fernBrandAssetPaths.get(value) ?? normalizeAssetPath(value);
     return normalized && assetPaths.has(normalized) ? `/${normalized}` : void 0;
   };
   const brandVariants = (value) => {
@@ -6445,6 +7254,34 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
       }
     }
   };
+  if (platform === "docusaurus" && docusaurusSettings?.navbarTitle && !logoLight) {
+    docsConfig = { ...docsConfig, navbar: { ...docsConfig.navbar, logo: null } };
+  }
+  if (mintlifyConfig) {
+    const appearance = mintlifyConfig.appearance && typeof mintlifyConfig.appearance === "object" ? mintlifyConfig.appearance : null;
+    const defaultMode = appearance?.default;
+    if (defaultMode === "light" || defaultMode === "dark" || defaultMode === "system") {
+      docsConfig = { ...docsConfig, appearance: { ...docsConfig.appearance, default: defaultMode } };
+    }
+    const background = mintlifyConfig.background && typeof mintlifyConfig.background === "object" ? mintlifyConfig.background : null;
+    if (background) {
+      const decoration = background.decoration;
+      const image = publicBrandPath(background.image);
+      const imageDark = publicBrandPath(background.imageDark);
+      docsConfig = {
+        ...docsConfig,
+        background: {
+          ...docsConfig.background,
+          ...decoration === "none" || decoration === "grid" || decoration === "gradient" ? { decoration } : {},
+          ...image ? { image } : {},
+          ...imageDark ? { imageDark } : {}
+        }
+      };
+    }
+  }
+  if (platform === "docusaurus") {
+    docsConfig = { ...docsConfig, appearance: { ...docsConfig.appearance, default: docusaurusSettings?.defaultColorMode ?? "light" } };
+  }
   if (faviconLight) docsConfig = {
     ...docsConfig,
     favicon: { light: faviconLight, ...faviconDark ? { dark: faviconDark } : {} }
@@ -6467,6 +7304,7 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     platform,
     pages,
     assets,
+    ...remoteApiSpecs.length > 0 ? { remoteApiSpecs } : {},
     ...componentMigrator ? { componentFiles: componentMigrator.files() } : {},
     docsConfig,
     ...mintlifyConfig ? {
@@ -6482,7 +7320,7 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
       }
     } : docusaurusSettings && (docusaurusSettings.name || docusaurusSettings.description || themeColors) ? {
       site: {
-        ...docusaurusSettings.name ? { name: docusaurusSettings.name } : {},
+        ...docusaurusSettings.navbarTitle || docusaurusSettings.name ? { name: docusaurusSettings.navbarTitle ?? docusaurusSettings.name } : {},
         ...docusaurusSettings.description ? { description: docusaurusSettings.description } : {},
         ...themeColors ? { colors: themeColors } : {}
       }
@@ -6754,10 +7592,10 @@ async function readResponseBody(response) {
   }
   return new TextDecoder().decode(body);
 }
-var defaultMigrationFetcher = async (url, request) => {
+var defaultMigrationFetcher = async (url, request2) => {
   const response = await fetch(url, {
     headers: {
-      Accept: request.accept,
+      Accept: request2.accept,
       "User-Agent": "Thally-Migrate/1.0 (+https://thally.io)"
     },
     redirect: "follow",
@@ -8172,6 +9010,202 @@ async function migrateUrl(options) {
     }
   };
 }
+
+// src/remote-api.ts
+import { createHash as createHash2 } from "crypto";
+import { lookup } from "dns/promises";
+import { request } from "https";
+import { isIP } from "net";
+import { parse as parseYaml6 } from "yaml";
+var MAX_SPEC_BYTES = 25e6;
+var MAX_REDIRECTS = 3;
+function isPublicAddress(address, family) {
+  if (family === 4) {
+    const parts = address.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false;
+    const [a, b] = parts;
+    return !(a === 0 || a === 10 || a === 127 || a >= 224 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && (b === 0 || b === 168) || a === 198 && (b === 18 || b === 19) || a === 203 && b === 0 || a === 198 && b === 51);
+  }
+  return family === 6 && /^[23][0-9a-f]{0,3}:/i.test(address) && !/^2001:db8:/i.test(address);
+}
+function validatedSpecUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.username || url.password || isIP(url.hostname)) {
+    throw new Error("Remote OpenAPI references must use an HTTPS domain without credentials or an IP literal.");
+  }
+  url.hash = "";
+  return url;
+}
+async function getPinnedAddress(url) {
+  const addresses = await lookup(url.hostname, { all: true });
+  if (addresses.length === 0 || addresses.some((candidate) => !isPublicAddress(candidate.address, candidate.family))) {
+    throw new Error("The OpenAPI host did not resolve exclusively to public addresses.");
+  }
+  return addresses[0];
+}
+async function requestPinnedSpec(url) {
+  const pinned = await getPinnedAddress(url);
+  return new Promise((resolve3, reject) => {
+    const req = request(url, {
+      headers: { Accept: "application/json, application/yaml, text/yaml, */*", "User-Agent": "Thally-Migrate/1.0 (+https://thally.io)" },
+      signal: AbortSignal.timeout(3e4),
+      // Node's dual-stack connector asks lookup for `all: true`; that
+      // callback must receive address records, not a single address string.
+      lookup: (_hostname, options, callback) => {
+        if (typeof options === "object" && options.all) callback(null, [pinned]);
+        else callback(null, pinned.address, pinned.family);
+      }
+    }, (response) => {
+      const status = response.statusCode ?? 0;
+      if (status >= 300 && status < 400) {
+        response.resume();
+        resolve3({ status, location: response.headers.location, body: Buffer.alloc(0) });
+        return;
+      }
+      if (status < 200 || status >= 300) {
+        response.resume();
+        reject(new Error(`OpenAPI server returned ${status}.`));
+        return;
+      }
+      const statedBytes = Number(response.headers["content-length"] ?? 0);
+      if (statedBytes > MAX_SPEC_BYTES) {
+        response.destroy();
+        reject(new Error("Remote OpenAPI spec exceeds the 25 MB import limit."));
+        return;
+      }
+      const chunks = [];
+      let bytes = 0;
+      response.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > MAX_SPEC_BYTES) {
+          response.destroy(new Error("Remote OpenAPI spec exceeds the 25 MB import limit."));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => resolve3({ status, body: Buffer.concat(chunks) }));
+      response.on("error", reject);
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+async function downloadSpec(value, fetcher) {
+  let url = validatedSpecUrl(value);
+  if (fetcher) {
+    const response = await fetcher(url, { accept: "application/json, application/yaml, text/yaml" });
+    validatedSpecUrl(response.finalUrl.toString());
+    const body = Buffer.from(response.body);
+    if (body.length > MAX_SPEC_BYTES) throw new Error("Remote OpenAPI spec exceeds the 25 MB import limit.");
+    return body;
+  }
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const response = await requestPinnedSpec(url);
+    if (response.status >= 300 && response.status < 400) {
+      if (!response.location || hop === MAX_REDIRECTS) throw new Error("Remote OpenAPI spec redirected too many times.");
+      url = validatedSpecUrl(new URL(response.location, url).toString());
+      continue;
+    }
+    return response.body;
+  }
+  throw new Error("Remote OpenAPI spec redirected too many times.");
+}
+function parseOpenApi(content, extension) {
+  const text = content.toString("utf8");
+  const parsed = extension === "yaml" || !text.trimStart().startsWith("{") ? parseYaml6(text) : JSON.parse(text);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("OpenAPI spec is not an object.");
+  const document = parsed;
+  if (typeof document.openapi !== "string" || !/^3\./.test(document.openapi)) {
+    throw new Error("Remote specification is not OpenAPI 3.x.");
+  }
+  if (!document.paths || typeof document.paths !== "object" || Array.isArray(document.paths)) {
+    throw new Error("Remote OpenAPI spec has no paths object.");
+  }
+  const paths = Object.entries(document.paths);
+  if (paths.length > 5e3) throw new Error("Remote OpenAPI spec has too many paths to import.");
+  const operations = [];
+  for (const [path, value] of paths) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    for (const [method, raw] of Object.entries(value)) {
+      if (!/^(get|post|put|patch|delete|head|options|trace)$/i.test(method) || !raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+      const operation = raw;
+      const tags = Array.isArray(operation.tags) ? operation.tags : [];
+      operations.push({
+        method: method.toLowerCase(),
+        path,
+        tag: typeof tags[0] === "string" ? tags[0] : "API Reference",
+        summary: typeof operation.summary === "string" ? operation.summary : String(operation.operationId ?? "")
+      });
+    }
+  }
+  return operations;
+}
+function slug(value) {
+  return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function operationTarget(operation) {
+  const path = operation.path.split("/").filter(Boolean).map((part) => part.replace(/[{}]/g, "").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").toLowerCase());
+  return `/api/default/${[...path, operation.method].join("/")}`;
+}
+async function hydrateRemoteApiSpecs(bundle, fetcher) {
+  if (!bundle.remoteApiSpecs?.length) return bundle;
+  const assets = [...bundle.assets];
+  const tabs = bundle.docsConfig.tabs.map((tab) => ({ ...tab }));
+  const redirects = [...bundle.docsConfig.redirects ?? []];
+  const warnings = [...bundle.warnings];
+  const authoredLinks = /* @__PURE__ */ new Set();
+  for (const page of bundle.pages) {
+    for (const match of page.body.matchAll(/\/[a-z0-9_/-]+/gi)) {
+      const segments = match[0].split("/").filter(Boolean);
+      if (segments.length < 3) continue;
+      const section = segments[0].toLowerCase();
+      if (section.includes("api") || section.includes("reference")) authoredLinks.add(match[0]);
+    }
+  }
+  for (const reference of bundle.remoteApiSpecs) {
+    for (let index = warnings.length - 1; index >= 0; index--) {
+      if (warnings[index].source === reference.url && warnings[index].message.includes("requires a network download")) warnings.splice(index, 1);
+    }
+    try {
+      const url = validatedSpecUrl(reference.url);
+      const extension = /\.ya?ml$/i.test(url.pathname) ? "yaml" : "json";
+      const body = await downloadSpec(reference.url, fetcher);
+      const operations = parseOpenApi(body, extension);
+      const filename = `openapi-${createHash2("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
+      assets.push({ path: filename, content: body });
+      const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
+      if (tab) tab.api = { source: `/${filename}` };
+      else tabs.push({ tab: reference.tabLabel ?? "API Reference", api: { source: `/${filename}` } });
+      const routes = /* @__PURE__ */ new Map();
+      for (const operation of operations) {
+        const key = `${slug(operation.tag)}/${slug(operation.summary)}`;
+        if (routes.has(key)) routes.set(key, null);
+        else routes.set(key, operationTarget(operation));
+      }
+      const existingSources = new Set(redirects.map((redirect) => redirect.source));
+      for (const source of authoredLinks) {
+        const parts = source.split("/").filter(Boolean);
+        const key = parts.slice(-2).join("/");
+        const destination = routes.get(key);
+        if (!destination || existingSources.has(source)) continue;
+        redirects.push({ source, destination, permanent: false });
+        existingSources.add(source);
+      }
+    } catch (error) {
+      warnings.push({
+        code: "fetch-failed",
+        source: reference.url,
+        message: `Remote OpenAPI spec could not be imported: ${error instanceof Error ? error.message : String(error)}`
+      });
+    }
+  }
+  return {
+    ...bundle,
+    assets,
+    docsConfig: { ...bundle.docsConfig, tabs, ...redirects.length > 0 ? { redirects } : {} },
+    warnings
+  };
+}
 export {
   addMintlifyDirectoryRedirects,
   buildNavigationFromPages,
@@ -8180,6 +9214,7 @@ export {
   detectRepositoryDocsDir,
   detectRepositoryPlatform,
   gitmodulePaths,
+  hydrateRemoteApiSpecs,
   mergeMigrationConfig,
   migrateRepository,
   migrateUrl,