@thallylabs/migrate 0.2.7 → 0.2.8

package/dist/index.js

@@ -2,17 +2,21 @@
 import { compileSync as compileSync2 } from "@mdx-js/mdx";
 import { spawn } from "child_process";
 import {
+  closeSync,
   existsSync as existsSync5,
   lstatSync as lstatSync5,
+  openSync,
   readFileSync as readFileSync5,
-  readdirSync,
+  readSync,
+  readdirSync as readdirSync2,
   realpathSync as realpathSync2,
   rmSync,
   statSync
 } from "fs";
 import { createRequire } from "module";
-import { basename as basename2, dirname as dirname4, extname as extname4, relative as relative5, resolve as resolvePath, sep as sep2 } from "path";
+import { basename as basename3, dirname as dirname4, extname as extname5, relative as relative5, resolve as resolvePath, sep as sep2 } from "path";
 import { parse as parseYaml4 } from "yaml";
+import * as ts2 from "typescript";
 
 // src/components.ts
 import { createHash } from "crypto";
@@ -159,19 +163,21 @@ function docusaurusAdmonitionTag(kind) {
 function normalizeDocusaurusAdmonitions(body) {
   const lines = body.split("\n");
   const openAdmonitions = [];
+  const headingLines = [];
   let codeFence = null;
-  return lines.map((line) => {
-    const codeMatch = line.match(/^\s*(`{3,}|~{3,})/);
+  const output = lines.map((line, index) => {
+    const codeMatch = line.match(/^\s{0,3}(`{3,}|~{3,})/);
     if (codeMatch) {
-      if (!codeFence) codeFence = codeMatch[1][0];
-      else if (codeMatch[1][0] === codeFence) codeFence = null;
+      if (!codeFence) codeFence = codeMatch[1];
+      else if (codeMatch[1][0] === codeFence[0] && codeMatch[1].length >= codeFence.length && /^\s*$/.test(line.slice(codeMatch[0].length))) codeFence = null;
       return line;
     }
     if (codeFence) return line;
+    if (/^#{1,6}\s/.test(line)) headingLines.push(index);
     const opening = line.match(/^\s*(:{3,})(note|tip|info|warning|caution|danger)(?:\[([^\]]+)\]|\s+(.+))?\s*$/i);
     if (opening) {
       const tag = docusaurusAdmonitionTag(opening[2].toLowerCase());
-      openAdmonitions.push({ delimiter: opening[1], tag });
+      openAdmonitions.push({ delimiter: opening[1], tag, openedAt: index });
       const title = (opening[3] ?? opening[4])?.trim();
       return title ? `<${tag}>
 **${title}**` : `<${tag}>`;
@@ -183,7 +189,74 @@ function normalizeDocusaurusAdmonitions(body) {
       return `</${current.tag}>`;
     }
     return line;
-  }).join("\n");
+  });
+  const closingByLine = /* @__PURE__ */ new Map();
+  for (const open of openAdmonitions.reverse()) {
+    const at = headingLines.find((line) => line > open.openedAt) ?? output.length;
+    closingByLine.set(at, [...closingByLine.get(at) ?? [], `</${open.tag}>`]);
+  }
+  for (const [at, closing] of [...closingByLine].sort(([left], [right]) => right - left)) output.splice(at, 0, ...closing);
+  return output.join("\n");
+}
+function unwrapDocusaurusMdxCodeBlocks(body) {
+  const output = [];
+  let fence;
+  let isMdxCodeBlock = false;
+  for (const line of body.split("\n")) {
+    const opening = !fence && line.match(/^ {0,3}(`{3,}|~{3,})mdx-code-block\s*$/);
+    if (opening) {
+      fence = opening[1];
+      isMdxCodeBlock = true;
+      continue;
+    }
+    if (fence) {
+      const closing = line.match(/^ {0,3}(`{3,}|~{3,})\s*$/);
+      if (closing && closing[1][0] === fence[0] && closing[1].length >= fence.length) {
+        if (!isMdxCodeBlock) output.push(line);
+        fence = void 0;
+        isMdxCodeBlock = false;
+        continue;
+      }
+      if (isMdxCodeBlock && /^\s*(?:import|export)\b/.test(line)) return body;
+      output.push(line);
+      continue;
+    }
+    const ordinaryFence = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (ordinaryFence) {
+      fence = ordinaryFence[1];
+      isMdxCodeBlock = false;
+    }
+    output.push(line);
+  }
+  return isMdxCodeBlock ? body : output.join("\n");
+}
+function normalizeExplicitHeadingIds(body) {
+  return 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("}")) {
+      const marker = trimmed.lastIndexOf(" {#");
+      if (marker >= 0) {
+        const id = trimmed.slice(marker + 3, -1);
+        if (/^[A-Za-z][A-Za-z0-9_-]*$/.test(id)) {
+          return `<a id="${id}"></a>
+${trimmed.slice(0, marker).trimEnd()}`;
+        }
+      }
+    }
+    if (trimmed.endsWith("*/}")) {
+      const marker = trimmed.lastIndexOf(" {/*");
+      if (marker >= 0) {
+        const comment = trimmed.slice(marker + 4, -3).trim();
+        const id = comment.startsWith("#") ? comment.slice(1) : "";
+        if (/^[A-Za-z][A-Za-z0-9_.:-]*$/.test(id)) {
+          return `<a id="${id}"></a>
+${trimmed.slice(0, marker).trimEnd()}`;
+        }
+      }
+    }
+    return line;
+  }).join("\n"));
 }
 var GLOBAL_DOCUSARUS_COMPONENTS = /* @__PURE__ */ new Set([
   "Tabs",
@@ -192,19 +265,11 @@ var GLOBAL_DOCUSARUS_COMPONENTS = /* @__PURE__ */ new Set([
   "DocCardList",
   "TOCInline"
 ]);
-function isGlobalDocusaurusImport(line) {
-  const trimmed = line.trim().replace(/;$/, "").trimEnd();
-  if (!trimmed.startsWith("import ")) return false;
-  const separator = trimmed.indexOf(" from ", "import ".length);
-  if (separator < 0) return false;
-  const component = trimmed.slice("import ".length, separator).trim();
-  if (!GLOBAL_DOCUSARUS_COMPONENTS.has(component)) return false;
-  const source = trimmed.slice(separator + " from ".length);
-  if (source.length < 3) return false;
-  const quote = source[0];
-  if (quote !== "'" && quote !== '"' || source.at(-1) !== quote) return false;
-  const moduleName = source.slice(1, -1);
-  return moduleName.startsWith("@theme/") || moduleName.startsWith("@docusaurus/");
+function removeGlobalDocusaurusImports(body) {
+  return replaceOutsideCode(body, (segment) => segment.replace(
+    /\bimport\s+([A-Za-z_$][\w$]*)\s+from\s+(['"])(@(?:theme|docusaurus)\/[^'"]+)\2\s*;?/g,
+    (statement, component) => GLOBAL_DOCUSARUS_COMPONENTS.has(component) ? "" : statement
+  ));
 }
 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;
@@ -418,7 +483,11 @@ function escapeFernLiteralBraces(raw) {
       const end = node.position?.end.offset;
       const root2 = value.split(".")[0];
       const safeBuiltinPath = value.includes(".") && SAFE_BUILTIN_ROOTS.has(root2);
-      if (BARE_IDENTIFIER_PATH.test(value) && !JS_LITERAL_KEYWORDS.has(value) && !declared.has(root2) && !safeBuiltinPath && start !== void 0 && end !== void 0) {
+      const isTemplatePlaceholder = /^\{\s*[A-Za-z_$][\w$.-]*\s*\}$/.test(value);
+      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}\\}` });
       }
       return;
@@ -532,10 +601,10 @@ function maskCode(body) {
   let codeFence = null;
   let fenceBuffer = [];
   for (const line of source.split("\n")) {
-    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    const fenceMatch = line.match(/^\s{0,3}(`{3,}|~{3,})/);
     if (codeFence) {
       fenceBuffer.push(line);
-      if (fenceMatch && fenceMatch[1][0] === codeFence) {
+      if (fenceMatch && fenceMatch[1][0] === codeFence[0] && fenceMatch[1].length >= codeFence.length && /^\s*$/.test(line.slice(fenceMatch[0].length))) {
         lines.push(stash(fenceBuffer.join("\n")));
         codeFence = null;
         fenceBuffer = [];
@@ -543,7 +612,7 @@ function maskCode(body) {
       continue;
     }
     if (fenceMatch) {
-      codeFence = fenceMatch[1][0];
+      codeFence = fenceMatch[1];
       fenceBuffer = [line];
       continue;
     }
@@ -565,14 +634,104 @@ function normalizeHtmlComments(body) {
 function normalizeFernCallouts(body) {
   return replaceOutsideCode(body, (whole) => {
     const openTags = [];
-    return whole.replace(/<Callout\s+intent=(?:"([^"]*)"|'([^']*)')([^>]*?)(\/?)>/g, (_match, doubleQuoted, singleQuoted, rest, selfClose) => {
-      const intent = (doubleQuoted ?? singleQuoted ?? "").toLowerCase();
-      const tag = intent === "warning" ? "Warning" : intent === "success" || intent === "tip" ? "Tip" : intent === "error" || intent === "danger" ? "Error" : "Note";
-      if (!selfClose) openTags.push(tag);
-      return `<${tag}${rest}${selfClose}>`;
-    }).replace(/<\/Callout>/g, (match) => openTags.length ? `</${openTags.pop()}>` : match);
+    const output = [];
+    let cursor = 0;
+    while (cursor < whole.length) {
+      const opening = whole.indexOf("<Callout", cursor);
+      const closing = whole.indexOf("</Callout>", cursor);
+      const next = opening < 0 ? closing : closing < 0 ? opening : Math.min(opening, closing);
+      if (next < 0) break;
+      output.push(whole.slice(cursor, next));
+      if (next === closing) {
+        const tag = openTags.pop();
+        output.push(tag ? `</${tag}>` : "</Callout>");
+        cursor = next + "</Callout>".length;
+        continue;
+      }
+      const attributeStart = next + "<Callout".length;
+      if (!/[\s/>]/.test(whole[attributeStart] ?? "")) {
+        output.push("<Callout");
+        cursor = attributeStart;
+        continue;
+      }
+      let end = attributeStart;
+      let quote = null;
+      let expressionDepth = 0;
+      for (; end < whole.length; end++) {
+        const character = whole[end];
+        if (quote) {
+          if (character === quote && whole[end - 1] !== "\\") quote = null;
+        } else if (character === '"' || character === "'") {
+          quote = character;
+        } else if (character === "{") {
+          expressionDepth++;
+        } else if (character === "}" && expressionDepth > 0) {
+          expressionDepth--;
+        } else if (character === ">" && expressionDepth === 0) {
+          break;
+        }
+      }
+      if (end === whole.length) {
+        output.push(whole.slice(next));
+        cursor = whole.length;
+        break;
+      }
+      const attributes = whole.slice(attributeStart, end);
+      const intent = findStaticCalloutIntent(attributes);
+      const isSelfClosing = attributes.trimEnd().endsWith("/");
+      if (!intent) {
+        output.push(whole.slice(next, end + 1));
+        if (!isSelfClosing) openTags.push(null);
+      } else {
+        const value = intent.value.toLowerCase();
+        const tag = value === "warning" ? "Warning" : value === "success" || value === "tip" ? "Tip" : value === "error" || value === "danger" ? "Error" : "Note";
+        output.push(`<${tag}${attributes.slice(0, intent.start)}${attributes.slice(intent.end)}>`);
+        if (!isSelfClosing) openTags.push(tag);
+      }
+      cursor = end + 1;
+    }
+    output.push(whole.slice(cursor));
+    return output.join("");
   });
 }
+function findStaticCalloutIntent(attributes) {
+  let cursor = 0;
+  while (cursor < attributes.length) {
+    const start = cursor;
+    while (/\s/.test(attributes[cursor] ?? "")) cursor++;
+    if (cursor === start) {
+      cursor++;
+      continue;
+    }
+    const nameStart = cursor;
+    while (/[A-Za-z0-9_-]/.test(attributes[cursor] ?? "")) cursor++;
+    const name = attributes.slice(nameStart, cursor);
+    while (/\s/.test(attributes[cursor] ?? "")) cursor++;
+    if (attributes[cursor] !== "=") continue;
+    cursor++;
+    while (/\s/.test(attributes[cursor] ?? "")) cursor++;
+    const quote = attributes[cursor];
+    if (quote !== '"' && quote !== "'") {
+      if (quote === "{") {
+        let depth = 0;
+        do {
+          if (attributes[cursor] === "{") depth++;
+          if (attributes[cursor] === "}") depth--;
+          cursor++;
+        } while (cursor < attributes.length && depth > 0);
+      } else {
+        while (cursor < attributes.length && !/\s/.test(attributes[cursor])) cursor++;
+      }
+      continue;
+    }
+    const valueStart = ++cursor;
+    while (cursor < attributes.length && attributes[cursor] !== quote) cursor++;
+    const value = attributes.slice(valueStart, cursor);
+    if (cursor < attributes.length) cursor++;
+    if (name === "intent") return { start, end: cursor, value };
+  }
+  return null;
+}
 function unwrapFernCodeBlockTabs(body) {
   return replaceOutsideCode(body, (whole) => {
     let groupDepth = 0;
@@ -679,25 +838,31 @@ ${result}`;
   return result;
 }
 function normalizeDocusaurusTabs(body) {
-  return body.replace(/<Tabs\b([^>]*)>([\s\S]*?)<\/Tabs>/g, (_match, attributes, inner) => {
-    const labelByValue = /* @__PURE__ */ new Map();
-    const valuesSource = attributes.match(/\bvalues=\{(\[[\s\S]*?\])\s*\}/)?.[1];
-    if (valuesSource) {
-      for (const entry of valuesSource.matchAll(/\{([^{}]*)\}/g)) {
-        const label = entry[1].match(/\blabel:\s*(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean);
-        const value = entry[1].match(/\bvalue:\s*(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean);
-        if (value) labelByValue.set(value, label ?? value);
+  let result = body;
+  for (let depth = 0; depth < 20; depth += 1) {
+    const updated = result.replace(/<Tabs\b([^>]*)>((?:(?!<Tabs\b)[\s\S])*?)<\/Tabs>/g, (_match, attributes, inner) => {
+      const labelByValue = /* @__PURE__ */ new Map();
+      const valuesSource = attributes.match(/\bvalues=\{(\[[\s\S]*?\])\s*\}/)?.[1];
+      if (valuesSource) {
+        for (const entry of valuesSource.matchAll(/\{([^{}]*)\}/g)) {
+          const label = entry[1].match(/\blabel:\s*(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean);
+          const value = entry[1].match(/\bvalue:\s*(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean);
+          if (value) labelByValue.set(value, label ?? value);
+        }
       }
-    }
-    const cleanedAttributes = attributes.replace(/\s*defaultValue=(?:\{[^}]*\}|"[^"]*"|'[^']*')/g, "").replace(/\s*values=\{[\s\S]*?\]\s*\}/g, "").replace(/\s*groupId=(?:"[^"]*"|'[^']*')/g, "").replace(/\s*queryString(?:=(?:\{[^}]*\}|"[^"]*"|'[^']*'))?/g, "");
-    const rewrittenInner = inner.replace(/<TabItem\b([^>]*)>/g, (_itemMatch, itemAttributes) => {
-      const label = itemAttributes.match(/\blabel=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean);
-      const value = itemAttributes.match(/\bvalue=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean);
-      const title = label ?? (value && labelByValue.get(value)) ?? value ?? "Tab";
-      return `<Tab title="${title.replace(/"/g, "&quot;")}">`;
-    }).replace(/<\/TabItem>/g, "</Tab>");
-    return `<Tabs${cleanedAttributes}>${rewrittenInner}</Tabs>`;
-  });
+      const cleanedAttributes = attributes.replace(/\s*defaultValue=(?:\{[^}]*\}|"[^"]*"|'[^']*')/g, "").replace(/\s*values=\{[\s\S]*?\]\s*\}/g, "").replace(/\s*values=\{[^{}]*\}/g, "").replace(/\s*groupId=(?:"[^"]*"|'[^']*')/g, "").replace(/\s*queryString(?:=(?:\{[^}]*\}|"[^"]*"|'[^']*'))?/g, "");
+      const rewrittenInner = inner.replace(/<TabItem\b([^>]*)>/g, (_itemMatch, itemAttributes) => {
+        const label = itemAttributes.match(/\blabel=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean);
+        const value = itemAttributes.match(/\bvalue=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean);
+        const title = label ?? (value && labelByValue.get(value)) ?? value ?? "Tab";
+        return `<Tab title="${title.replace(/"/g, "&quot;")}">`;
+      }).replace(/<\/TabItem>/g, "</Tab>");
+      return `<ThallyTabs${cleanedAttributes}>${rewrittenInner}</ThallyTabs>`;
+    });
+    if (updated === result) break;
+    result = updated;
+  }
+  return result.replace(/<ThallyTabs\b/g, "<Tabs").replace(/<\/ThallyTabs>/g, "</Tabs>");
 }
 var TAB_FENCE_OPEN = /^(`{3,}|~{3,})(\S*)\s+tab\b(.*)$/;
 function normalizeDocusaurusTabBlocks(body) {
@@ -783,15 +948,68 @@ function convertHtmlStyleAttributes(body) {
     (_match, tag, before, _quote, styleText, after, selfClose) => `<${tag}${before} style={${cssTextToStyleObjectLiteral(styleText)}}${after}${selfClose ? " /" : ""}>`
   );
 }
-function normalizeMdx(body, platform) {
+function normalizeMintlifyUpdateLabels(body) {
+  return body.replace(/(<Update\b[^>]*\blabel=)\{(<\>[\s\S]*?<\/\>)\}/g, (match, prefix, fragment) => {
+    let root;
+    try {
+      root = descriptionParser.parse(fragment);
+    } catch {
+      return match;
+    }
+    const plainText = (node) => {
+      if (node.type === "text" || node.type === "inlineCode") return node.value ?? "";
+      if (node.type === "mdxTextExpression" || node.type === "mdxFlowExpression" || node.type === "mdxjsEsm") return null;
+      const parts = (node.children ?? []).map(plainText);
+      return parts.some((part) => part === null) ? null : parts.join("");
+    };
+    const label = plainText(root)?.replace(/\s+/g, " ").trim();
+    return label && !/[{}]/.test(label) ? `${prefix}{${JSON.stringify(label)}}` : match;
+  });
+}
+function normalizeMintlifyParameterAnchors(body) {
+  const seen = /* @__PURE__ */ new Set();
+  const anchorFor = (name) => {
+    const id = `param-${name.toLowerCase().replace(/[._]/g, "-")}`;
+    if (seen.has(id)) return "";
+    seen.add(id);
+    return `<a id="${id}"></a>
+`;
+  };
+  let fence;
+  const withHeadings = body.split("\n").map((line) => {
+    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 = void 0;
+      return line;
+    }
+    if (fence) return line;
+    const heading = line.match(/^ {0,3}#{1,6}\s+`([A-Za-z][A-Za-z0-9._-]*)`(?:\s|$)/);
+    return heading ? `${anchorFor(heading[1])}${line}` : line;
+  }).join("\n");
+  return replaceOutsideCode(withHeadings, (segment) => segment.replace(
+    /<(ResponseField|ParamField)\b([^>]*?)\bname=(?:"([A-Za-z][A-Za-z0-9._-]*)"|'([A-Za-z][A-Za-z0-9._-]*)')([^>]*)>/g,
+    (match, _tag, _before, doubleQuoted, singleQuoted) => `${anchorFor(doubleQuoted ?? singleQuoted)}${match}`
+  ));
+}
+function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   const runFern = platform === "fern";
   const runMintlify = platform === "mintlify";
   const runDocusaurus = platform === "docusaurus";
-  let rewritten = normalizeDocusaurusAdmonitions(runFern ? normalizeFernCallouts(body) : body);
+  const sourceBody = runDocusaurus && unwrapMdxCodeBlocks ? unwrapDocusaurusMdxCodeBlocks(body) : body;
+  let rewritten = normalizeDocusaurusAdmonitions(normalizeExplicitHeadingIds(runFern ? normalizeFernCallouts(sourceBody) : sourceBody));
   if (runDocusaurus) {
-    const withoutGlobalImports = rewritten.split("\n").filter((line) => !isGlobalDocusaurusImport(line)).join("\n");
-    rewritten = normalizeDocusaurusTabBlocks(normalizeDocusaurusTabs(withoutGlobalImports));
+    rewritten = normalizeDocusaurusTabBlocks(normalizeDocusaurusTabs(removeGlobalDocusaurusImports(rewritten)));
+    rewritten = replaceOutsideCode(rewritten, (segment) => segment.replace(
+      /\bimport\s+([A-Za-z_$][\w$]*)\s+from\s+(['"])(@site\/[^'"]+)\2\s*;?/g,
+      (statement, binding, _quote, _source, offset) => {
+        const withoutStatement = segment.slice(0, offset) + segment.slice(offset + statement.length);
+        return new RegExp(`\\b${binding}\\s*(?:\\.|\\[|\\})`).test(withoutStatement) ? statement : "";
+      }
+    ));
+    rewritten = rewritten.replace(/^\n{2,}/, "\n");
   }
+  if (runMintlify) rewritten = normalizeMintlifyParameterAnchors(rewritten);
   rewritten = replaceOutsideCode(rewritten, (segment) => {
     let result = convertHtmlStyleAttributes(segment).replace(/<!--([\s\S]*?)-->/g, (_match, content) => `{/*${content}*/}`).replace(/<Danger(\s[^>]*)?>/g, "<Error$1>").replace(/<\/Danger>/g, "</Error>").replace(/<Warn(\s[^>]*)?>/g, "<Warning$1>").replace(/<\/Warn>/g, "</Warning>").replace(/<Check(\s[^>]*)?>/g, "<Note$1>").replace(/<\/Check>/g, "</Note>").replace(/<Tree\.Folder/g, "<Folder").replace(/<\/Tree\.Folder>/g, "</Folder>").replace(/<Tree\.File/g, "<File").replace(/<\/Tree\.File>/g, "</File>");
     if (runDocusaurus) {
@@ -801,7 +1019,7 @@ function normalizeMdx(body, platform) {
       }).replace(/<\/TabItem>/g, "</Tab>").replace(/<Link\b([^>]*)\bto=(?:"([^"]*)"|'([^']*)')([^>]*)>/g, (_match, before, doubleQuoted, singleQuoted, after) => `<a${before}href="${doubleQuoted ?? singleQuoted}"${after}>`).replace(/<\/Link>/g, "</a>").replace(/<(?:DocCardList|TOCInline)\b[^>]*\/>/g, "");
     }
     if (runMintlify) {
-      result = result.replace(/<FileTree(\s[^>]*)?>/g, "<Tree$1>").replace(/<\/FileTree>/g, "</Tree>").replace(/<GitHub\.Repo/g, "<GitHub").replace(/<\/GitHub\.Repo>/g, "</GitHub>").replace(/<Column(\s[^>]*)?>/g, "<div$1>").replace(/<\/Column>/g, "</div>");
+      result = normalizeMintlifyUpdateLabels(result).replace(/<FileTree(\s[^>]*)?>/g, "<Tree$1>").replace(/<\/FileTree>/g, "</Tree>").replace(/<GitHub\.Repo/g, "<GitHub").replace(/<\/GitHub\.Repo>/g, "</GitHub>").replace(/<Column(\s[^>]*)?>/g, "<div$1>").replace(/<\/Column>/g, "</div>");
     }
     if (runFern) {
       result = result.replace(/<CodeBlocks(\s[^>]*)?>/g, "<CodeGroup$1>").replace(/<\/CodeBlocks>/g, "</CodeGroup>").replace(/<ParameterField\b/g, "<ParamField").replace(/<\/ParameterField>/g, "</ParamField>").replace(/<Cards(\s[^>]*)?>/g, "<CardGroup$1>").replace(/<\/Cards>/g, "</CardGroup>").replace(/<Success(\s[^>]*)?>/g, "<Tip$1>").replace(/<\/Success>/g, "</Tip>").replace(/<Launch(\s[^>]*)?>/g, "<Note$1>").replace(/<\/Launch>/g, "</Note>").replace(/<Files(\s[^>]*)?>\n?/g, "").replace(/<\/Files>/g, "");
@@ -809,7 +1027,15 @@ function normalizeMdx(body, platform) {
     return result;
   });
   if (runFern) rewritten = unwrapFernCodeBlockTabs(rewritten);
-  return provideScopedGlobalReferences(rewritten);
+  const normalized = provideScopedGlobalReferences(rewritten);
+  if (runDocusaurus && sourceBody !== body) {
+    try {
+      compileSync(normalized, { outputFormat: "program" });
+    } catch {
+      return normalizeMdx(body, platform, false);
+    }
+  }
+  return normalized;
 }
 function parseMarkdownPage(input) {
   const parsed = parseFrontmatter(input.raw);
@@ -919,6 +1145,73 @@ function normalizeAssetPath(value) {
 }
 
 // src/components.ts
+function normalizeIndentedFences(content) {
+  const lines = content.split("\n");
+  let active;
+  let ordinaryFence;
+  let indentedJsx;
+  let listIndent;
+  return lines.map((line) => {
+    const trimmed = line.trimStart();
+    if (indentedJsx) {
+      const normalized2 = line.startsWith(indentedJsx.indent) ? line.slice(indentedJsx.indent.length) : line;
+      if (normalized2.trimStart().startsWith(`</${indentedJsx.tag}>`)) indentedJsx = void 0;
+      return normalized2;
+    }
+    if (ordinaryFence) {
+      const closing2 = trimmed.match(/^(`{3,}|~{3,})\s*$/)?.[1];
+      if (closing2 && closing2[0] === ordinaryFence[0] && closing2.length >= ordinaryFence.length) ordinaryFence = void 0;
+      return line;
+    }
+    if (!active) {
+      const listItem = line.match(/^([ \t]*)(?:[-*+]|\d+[.)])\s/);
+      const indentation = line.length - trimmed.length;
+      if (listItem) listIndent = listItem[1].length;
+      else if (trimmed && listIndent !== void 0 && indentation <= listIndent) listIndent = void 0;
+      const jsx = line.match(/^([ \t]{2,})<([A-Z][\w.]*)\b[^>]*>\s*$/);
+      if (jsx && listIndent !== void 0 && jsx[1].length > listIndent && !trimmed.endsWith("/>")) {
+        indentedJsx = { tag: jsx[2], indent: jsx[1] };
+        return line.slice(jsx[1].length);
+      }
+      const match = line.match(/^([ \t]{4,})(`{3,}|~{3,})/);
+      if (match) {
+        active = { indent: match[1], marker: match[2] };
+        return line.slice(match[1].length);
+      }
+      const ordinary = line.match(/^[ \t]{0,3}(`{3,}|~{3,})/);
+      if (ordinary) ordinaryFence = ordinary[1];
+      return line;
+    }
+    const normalized = line.startsWith(active.indent) ? line.slice(active.indent.length) : line;
+    const closing = normalized.trimStart().match(/^(`{3,}|~{3,})\s*$/)?.[1];
+    if (closing && closing[0] === active.marker[0] && closing.length >= active.marker.length) active = void 0;
+    return normalized;
+  }).join("\n");
+}
+function staticServerHelper(path, imported, local) {
+  if (imported === "default") return null;
+  const parsed = ts.createSourceFile(path, readFileSync(path, "utf8"), ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const isLiteral = (node) => {
+    if (ts.isParenthesizedExpression(node)) return isLiteral(node.expression);
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isNumericLiteral(node)) return true;
+    if ([ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.NullKeyword].includes(node.kind)) return true;
+    if (ts.isPrefixUnaryExpression(node)) return [ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken].includes(node.operator) && ts.isNumericLiteral(node.operand);
+    if (ts.isArrayLiteralExpression(node)) return node.elements.every((element) => ts.isExpression(element) && isLiteral(element));
+    if (ts.isObjectLiteralExpression(node)) return node.properties.every((property) => ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name) || ts.isNumericLiteral(property.name)) && isLiteral(property.initializer));
+    return false;
+  };
+  for (const statement of parsed.statements) {
+    if (!ts.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== imported || !declaration.initializer || !ts.isArrowFunction(declaration.initializer)) continue;
+      const arrow = declaration.initializer;
+      if (arrow.parameters.length > 0) continue;
+      const result = ts.isBlock(arrow.body) ? arrow.body.statements.length === 1 && ts.isReturnStatement(arrow.body.statements[0]) ? arrow.body.statements[0].expression : void 0 : arrow.body;
+      if (result && isLiteral(result)) return `export const ${local} = () => (${result.getText(parsed)});`;
+    }
+  }
+  return null;
+}
 var YOUTUBE_VIDEO_ID = /^[\w-]{1,64}$/;
 var YOUTUBE_ID_PACKAGES = /* @__PURE__ */ new Set(["react-lite-youtube-embed", "react-youtube", "@justinribeiro/lite-youtube"]);
 var YOUTUBE_URL = /(?:youtube\.com\/(?:watch\?v=|embed\/|shorts\/)|youtu\.be\/)([\w-]{1,64})/i;
@@ -1474,7 +1767,7 @@ 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 = normalizeHtmlComments(parsedFrontmatter);
+    const content = normalizeIndentedFences(normalizeHtmlComments(parsedFrontmatter));
     let tree;
     try {
       tree = parser.parse(content);
@@ -1488,6 +1781,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
     const declarations = [];
     const moduleImports = [];
     const realPageImports = [];
+    const serverPageDeclarations = [];
     const sharedImportEdits = [];
     let hasUnsupportedImports = false;
     function hasExpressionReference(names, options = {}) {
@@ -1553,13 +1847,19 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
         const rawSpecifier = ts.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : "";
         const specifier = rawSpecifier.startsWith("@site/") ? `/${rawSpecifier.slice("@site/".length)}` : rawSpecifier;
         if (isScaffoldProvidedImport(specifier)) {
+          if (specifier === "react" && bindings.length > 0 && bindings.every((binding) => REACT_GLOBALS.has(binding.imported)) && !hasExpressionReference(new Set(bindings.map((binding) => binding.local)))) {
+            edits.push({ start: node.position.start.offset + statement.getStart(ast), end: node.position.start.offset + statement.end, value: "" });
+            continue;
+          }
           moduleImports.push(statement.getText(ast));
           continue;
         }
         if (!specifier.startsWith(".") && !specifier.startsWith("/")) {
           if (SHARED_IMPORTS.has(specifier)) {
-            moduleImports.push(statement.getText(ast));
-            sharedImportEdits.push({ start: node.position.start.offset + statement.getStart(ast), end: node.position.start.offset + statement.end, value: "" });
+            const isUnusedReactHookImport = specifier === "react" && bindings.length > 0 && bindings.every((binding) => REACT_GLOBALS.has(binding.imported)) && !hasExpressionReference(new Set(bindings.map((binding) => binding.local)));
+            if (!isUnusedReactHookImport) moduleImports.push(statement.getText(ast));
+            if (isUnusedReactHookImport) edits.push({ start: node.position.start.offset + statement.getStart(ast), end: node.position.start.offset + statement.end, value: "" });
+            else sharedImportEdits.push({ start: node.position.start.offset + statement.getStart(ast), end: node.position.start.offset + statement.end, value: "" });
           } else if (specifier.startsWith("@theme/") || specifier.startsWith("@docusaurus/")) {
             edits.push({ start: node.position.start.offset + statement.getStart(ast), end: node.position.start.offset + statement.end, value: "" });
           } else if (hasExpressionReference(new Set(bindings.map((binding) => binding.local)))) {
@@ -1595,18 +1895,19 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
           hasUnsupportedImports = true;
           continue;
         }
-        if (bindings.some((binding) => !/^[A-Z]/.test(binding.local))) {
-          warn("MDX imports containing non-component values require manual migration; the import was preserved.", currentFile);
-          hasUnsupportedImports = true;
-          continue;
-        }
         try {
-          const path = copyGraph(resolveDependency(specifier, currentFile));
+          const sourcePath = resolveDependency(specifier, currentFile);
+          const path = copyGraph(sourcePath);
           const isSvgUsedAsTag = extname(path).toLowerCase() === ".svg" && bindings.some((binding) => usedAsJsxTagName(binding.local));
           for (const binding of bindings) {
             const registerPath = isSvgUsedAsTag ? wrapSvgAsComponent(path) : path;
             const registerImported = isSvgUsedAsTag ? "default" : binding.imported;
             if (!isSvgUsedAsTag && hasExpressionReference(/* @__PURE__ */ new Set([binding.local]))) {
+              const helper = staticServerHelper(sourcePath, binding.imported, binding.local);
+              if (helper) {
+                serverPageDeclarations.push(helper);
+                continue;
+              }
               const aliasSpecifier = portableSpecifier(`@/${registerPath.replace(/^src\//, "").replace(/\\/g, "/")}`);
               realPageImports.push(`import { ${registerImported} as ${binding.local} } from ${JSON.stringify(aliasSpecifier)};`);
               continue;
@@ -1617,6 +1918,15 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
           }
           edits.push({ start: node.position.start.offset + statement.getStart(ast), end: node.position.start.offset + statement.end, value: "" });
         } catch (error) {
+          if (hasExpressionReference(new Set(bindings.map((binding) => binding.local)))) {
+            warnings.push({
+              code: "skipped-file",
+              message: `This page was excluded because local import ${JSON.stringify(rawSpecifier)} could not be copied and is used in an expression: ${error instanceof Error ? error.message : "unsupported dependency"}.`,
+              source: relative2(root, currentFile).replace(/\\/g, "/")
+            });
+            hasUnsupportedImports = true;
+            continue;
+          }
           const failedPackage = error instanceof Error ? error.message.match(/^external package (\S+) requires manual installation and review$/)?.[1] : void 0;
           if (failedPackage && YOUTUBE_ID_PACKAGES.has(failedPackage)) {
             for (const binding of bindings) unsupportedImports.set(binding.local, failedPackage);
@@ -1758,9 +2068,64 @@ ${inlineSource}` });
       }
       edits.push(...declarations.map(({ start, end }) => ({ start, end, value: "" })), ...sharedImportEdits);
     }
+    const pageFunctions = functionDeclaredNames(content);
+    const passiveRoots = [];
+    const wrappedRoots = /* @__PURE__ */ new Set();
+    walk(tree, (node) => {
+      if (!node.name || !aliases.has(node.name) || !functionValuedAttribute(node, pageFunctions) || node.position?.start.offset === void 0 || node.position.end.offset === void 0) return;
+      if (passiveRoots.some((root2) => node.position.start.offset >= root2.position.start.offset && node.position.end.offset <= root2.position.end.offset)) return;
+      const functionAttributes = (node.attributes ?? []).filter((attribute) => {
+        const value = attribute.value && typeof attribute.value === "object" ? attribute.value.value?.trim() : void 0;
+        return !!value && pageFunctions.has(value);
+      });
+      if (functionAttributes.length === 1 && functionAttributes[0].name && functionAttributes[0].position?.start.offset !== void 0 && functionAttributes[0].position.end.offset !== void 0) {
+        const functionName = functionAttributes[0].value.value.trim();
+        const declaration = declarations.find((entry) => new RegExp(`^export const ${functionName}\\s*=`).test(entry.source));
+        const safeDeclaration = declaration?.source.match(/^export const \w+\s*=\s*\(\s*\{\s*children(?:\s*,\s*\.\.\.props)?\s*\}\s*\)\s*=>\s*\([\s\S]*\)\s*;?$/) && !/\b(?:window|document|process|fetch|use[A-Z]\w*)\b/.test(declaration.source) && [...declaration.source.matchAll(/<([A-Z]\w*)\b/g)].every((match) => match[1] === "CodeBlock") && [...declaration.source.matchAll(/\{([^{}]*)\}/g)].every((match) => ["children", "...props", "children, ...props"].includes(match[1].trim()));
+        const binding = registrations.get(aliases.get(node.name));
+        if (safeDeclaration && binding) {
+          const fallbackDeclaration = declaration.source.replace(/<CodeBlock\b[^>]*>/g, "<pre><code>").replace(/<\/CodeBlock>/g, "</code></pre>");
+          const wrapperPath = `${destinationRoot}/callback-${hash(`${currentFile}:${node.position.start.offset}`)}.jsx`;
+          const imported = binding.imported === "default" ? "default" : binding.imported;
+          const importClause = imported === "default" ? "import Original" : `import { ${imported} as Original }`;
+          const specifier = portableSpecifier(`./${relative2(destinationRoot, binding.path).replace(/\\/g, "/")}`);
+          const wrapperName = register(wrapperPath, "CallbackWrapper");
+          copied.set(wrapperPath, { path: wrapperPath, content: [
+            "'use client';",
+            `${importClause} from ${JSON.stringify(specifier)};`,
+            fallbackDeclaration,
+            `export function CallbackWrapper({ children, ...props }) { return <Original {...props} ${functionAttributes[0].name}={${functionName}}>{children}</Original>; }`
+          ].join("\n") });
+          const start = node.position.start.offset;
+          const end = node.position.end.offset;
+          const source2 = content.slice(start, end);
+          const opening = source2.indexOf(`<${node.name}`);
+          const closing = source2.lastIndexOf(`</${node.name}`);
+          if (opening >= 0) edits.push({ start: start + opening + 1, end: start + opening + 1 + node.name.length, value: wrapperName });
+          if (closing >= 0) edits.push({ start: start + closing + 2, end: start + closing + 2 + node.name.length, value: wrapperName });
+          edits.push({ start: functionAttributes[0].position.start.offset, end: functionAttributes[0].position.end.offset, value: "" });
+          wrappedRoots.add(node);
+          if (declaration.source.includes("<CodeBlock")) warn(`Interactive <${node.name}> was retained with a basic code block in place of Mintlify's CodeBlock.`, currentFile);
+          return;
+        }
+      }
+      const source = content.slice(node.position.start.offset, node.position.end.offset);
+      const openingEnd = source.indexOf(">");
+      const closingStart = source.lastIndexOf(`</${node.name}`);
+      const children = openingEnd >= 0 && closingStart > openingEnd ? source.slice(openingEnd + 1, closingStart) : "";
+      edits.push({
+        start: node.position.start.offset,
+        end: node.position.end.offset,
+        value: `<div data-migration-interactive-fallback="${node.name}">${children}</div>`
+      });
+      passiveRoots.push(node);
+      warn(`Interactive <${node.name}> passes a page-local function into a client component; its child content was retained without the interactive control. Move the callback into a client component to restore it.`, currentFile);
+    });
     walk(tree, (node) => {
       const replacement = node.name ? aliases.get(node.name) : void 0;
       if (!replacement || node.position?.start.offset === void 0 || node.position.end.offset === void 0) return;
+      if (wrappedRoots.has(node)) return;
+      if (passiveRoots.some((root2) => node.position.start.offset >= root2.position.start.offset && node.position.end.offset <= root2.position.end.offset)) return;
       const start = node.position.start.offset;
       const end = node.position.end.offset;
       if (extracted.some((item) => start >= item.node.position.start.offset && end <= item.node.position.end.offset)) return;
@@ -1780,7 +2145,8 @@ ${inlineSource}` });
       edits.push({ start, end, value });
     });
     const rendered = applyReplacements(content, edits);
-    const realImportsBlock = realPageImports.length ? `${[...new Set(realPageImports)].join("\n")}
+    const pageStatements = [.../* @__PURE__ */ new Set([...realPageImports, ...serverPageDeclarations])];
+    const realImportsBlock = pageStatements.length ? `${pageStatements.join("\n")}
 
 ` : "";
     return frontmatter + realImportsBlock + rendered;
@@ -2695,7 +3061,7 @@ function resolveDocusaurusPageIdentity(sourcePath, frontmatter, fallback) {
 function sourceReferenceKey(value) {
   return value.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\.(?:mdx?)$/i, "").replace(/\/$/, "");
 }
-function rewriteDocusaurusLinks(body, current, descriptors) {
+function rewriteDocusaurusLinks(body, current, descriptors, options = {}) {
   const routes = /* @__PURE__ */ new Map();
   for (const descriptor of descriptors) {
     const sourceKey = sourceReferenceKey(descriptor.sourcePath);
@@ -2711,26 +3077,47 @@ function rewriteDocusaurusLinks(body, current, descriptors) {
     const suffixIndex = target.search(/[?#]/);
     const path = suffixIndex >= 0 ? target.slice(0, suffixIndex) : target;
     const suffix = suffixIndex >= 0 ? target.slice(suffixIndex) : "";
-    const candidates = path.startsWith("/") ? [sourceReferenceKey(path), sourceReferenceKey(path).replace(/^docs\//, "")] : [
+    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(path)
     ];
     const route = candidates.map((candidate) => routes.get(candidate)).find(Boolean);
-    if (!route) return target;
+    if (!route) {
+      if (path.startsWith("/") && path !== "/" && options.sourceOrigin) {
+        options.onExternalLink?.(target);
+        return new URL(target, options.sourceOrigin).toString();
+      }
+      return target;
+    }
     return `${route === "introduction" ? "/" : `/${route}`}${suffix}`;
   }
   let codeFence = null;
   return body.split("\n").map((line) => {
-    const fence = line.match(/^\s*(`{3,}|~{3,})/);
+    const fence = line.match(/^\s{0,3}(`{3,}|~{3,})/);
     if (fence) {
-      if (!codeFence) codeFence = fence[1][0];
-      else if (fence[1][0] === codeFence) codeFence = null;
+      if (!codeFence) codeFence = fence[1];
+      else if (fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length && /^\s*$/.test(line.slice(fence[0].length))) codeFence = null;
       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}`);
   }).join("\n");
 }
+function readDocusaurusSiteOrigin(repositoryRoot) {
+  const configPath = findDocusaurusConfigPath(repositoryRoot);
+  if (!configPath) return void 0;
+  const address = readBoundedText(configPath).match(/\burl['"]?\s*:\s*(['"])(https?:\/\/[^'"]+)\1/)?.[2];
+  if (!address) return void 0;
+  try {
+    return new URL(address).origin;
+  } catch {
+    return void 0;
+  }
+}
 function readBoundedText(path) {
   if (lstatSync3(path).size > MAX_CONFIG_BYTES) {
     throw new Error("Docusaurus sidebar config exceeded the 1 MB static-parser limit.");
@@ -2900,9 +3287,12 @@ function configuredSidebarPath(repositoryRoot) {
   }
   return null;
 }
-function readDocusaurusSidebars(repositoryRoot) {
-  const configured = configuredSidebarPath(repositoryRoot);
-  const sourcePath = [configured, ...SIDEBAR_FILENAMES].filter((value) => Boolean(value)).find((candidate) => existsSync3(resolveWithin(repositoryRoot, candidate)));
+function readDocusaurusSidebars(repositoryRoot, versionedSidebarPath) {
+  const configured = versionedSidebarPath ?? configuredSidebarPath(repositoryRoot);
+  const sourcePath = [configured, ...versionedSidebarPath ? [] : SIDEBAR_FILENAMES].filter((value) => Boolean(value)).find((candidate) => {
+    const path = resolveWithin(repositoryRoot, candidate);
+    return existsSync3(path) && lstatSync3(path).isFile();
+  });
   if (!sourcePath) return null;
   const absolutePath = resolveWithin(repositoryRoot, sourcePath);
   const source = readBoundedText(absolutePath);
@@ -3188,8 +3578,8 @@ function projectDocusaurusNavigation(input) {
 }
 
 // src/fern.ts
-import { existsSync as existsSync4, lstatSync as lstatSync4, readFileSync as readFileSync4 } from "fs";
-import { dirname as dirname3, relative as relative4 } from "path";
+import { existsSync as existsSync4, lstatSync as lstatSync4, readFileSync as readFileSync4, readdirSync } from "fs";
+import { basename as basename2, dirname as dirname3, extname as extname4, relative as relative4 } from "path";
 import { parse as parseYaml3 } from "yaml";
 var MAX_CONFIG_BYTES2 = 2e6;
 function objectValue3(value) {
@@ -3243,8 +3633,9 @@ function fernLabelSlug(label) {
 }
 function segmentFor(value, label, context) {
   if (value["skip-slug"] === true) return null;
-  const explicit = typeof value.slug === "string" ? value.slug.trim() : "";
-  if (!explicit) return fernLabelSlug(label) || null;
+  if (typeof value.slug !== "string") return fernLabelSlug(label) || null;
+  const explicit = value.slug.trim();
+  if (!explicit) return null;
   const slugified = fernBasicSlug(explicit);
   if (context && explicit !== slugified && FERN_SEGMENT_ALIAS.test(explicit)) {
     context.segmentAliases.set(slugified, explicit);
@@ -3258,8 +3649,18 @@ function uniqueNavigationId(base, context) {
   return `${base}-${index}`;
 }
 function registerPageAt(rawPath, base, context) {
-  const relativePath = rawPath.trim().replace(/^\.\//, "");
-  const sourcePath = context.pathPrefix ? `${context.pathPrefix}/${relativePath}` : relativePath;
+  let sourcePath;
+  try {
+    const absolute = resolveWithinRoot(
+      context.pathPrefix ? resolveWithin(context.fernRoot, context.pathPrefix) : context.fernRoot,
+      rawPath.trim(),
+      context.repositoryRoot
+    );
+    sourcePath = relative4(context.fernRoot, absolute).replace(/\\/g, "/");
+  } catch {
+    warnOnce2(context, `fern-unsafe-page-${rawPath}`, `Fern page path "${rawPath}" escapes the repository and was skipped.`);
+    return "";
+  }
   const navigationId = uniqueNavigationId(base || "introduction", context);
   context.seenNavigationIds.add(navigationId);
   context.descriptors.push({ sourcePath, navigationId });
@@ -3268,17 +3669,62 @@ function registerPageAt(rawPath, base, context) {
   context.sourcePathToNavigationId.set(sourcePath, navigationId);
   return navigationId;
 }
+function registerFolder(object, parentSegments, context) {
+  const rawPath = String(object.folder).trim();
+  let folder;
+  try {
+    folder = resolveWithinRoot(
+      context.pathPrefix ? resolveWithin(context.fernRoot, context.pathPrefix) : context.fernRoot,
+      rawPath,
+      context.repositoryRoot
+    );
+  } catch {
+    warnOnce2(context, `fern-unsafe-folder-${rawPath}`, `Fern folder "${rawPath}" escapes the repository and was skipped.`);
+    return null;
+  }
+  if (!existsSync4(folder) || !lstatSync4(folder).isDirectory()) {
+    warnOnce2(context, `fern-missing-folder-${rawPath}`, `Fern folder "${rawPath}" does not exist and was skipped.`);
+    return null;
+  }
+  const label = typeof object.title === "string" && object.title.trim() ? object.title.trim() : titleCase3(basename2(folder));
+  const segment = typeof object.slug === "string" || object["skip-slug"] === true ? segmentFor(object, label, context) : fernBasicSlug(basename2(folder));
+  const segments = segment ? [...parentSegments, segment] : parentSegments;
+  const visit = (directory, routeSegments, depth) => {
+    if (depth > 12 || context.descriptors.length >= 5e3) return [];
+    const pages2 = [];
+    const entries = readdirSync(directory, { withFileTypes: true }).filter((entry) => !entry.name.startsWith(".") && !entry.isSymbolicLink()).sort((left, right) => Number(left.name !== "index.mdx" && left.name !== "index.md") - Number(right.name !== "index.mdx" && right.name !== "index.md") || left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const path = resolveWithin(directory, entry.name);
+      if (entry.isDirectory()) {
+        const nested = visit(path, [...routeSegments, fernBasicSlug(entry.name)], depth + 1);
+        if (nested.length) pages2.push({ group: titleCase3(entry.name), pages: nested });
+      } else if (entry.isFile() && [".md", ".mdx"].includes(extname4(entry.name).toLowerCase())) {
+        const stem = basename2(entry.name, extname4(entry.name));
+        const pageSegment = stem.toLowerCase() === "index" ? null : fernBasicSlug(stem);
+        const route = [...routeSegments, ...pageSegment ? [pageSegment] : []].join("/");
+        const registered = registerPageAt(relative4(context.fernRoot, path), route, { ...context, pathPrefix: "" });
+        if (registered) pages2.push(registered);
+      }
+    }
+    return pages2;
+  };
+  const pages = visit(folder, segments, 0);
+  if (!pages.length) return null;
+  addBareRouteRedirect(segments, pages, context);
+  return { group: label, pages };
+}
 function registerPage(object, parentSegments, context) {
   if (typeof object.path !== "string" || !object.path.trim()) return null;
   const label = typeof object.page === "string" && object.page.trim() ? object.page.trim() : "Untitled";
   const segment = segmentFor(object, label, context);
   const base = [...parentSegments, segment].filter(Boolean).join("/");
-  return registerPageAt(object.path, base, context);
+  return registerPageAt(object.path, base, context) || null;
 }
 function convertNode(node, parentSegments, context) {
   const object = objectValue3(node);
   if (!object) return null;
   if (typeof object.page === "string") return registerPage(object, parentSegments, context);
+  if (typeof object.folder === "string") return registerFolder(object, parentSegments, context);
   if (typeof object.section === "string") {
     const label = object.section;
     const segment = segmentFor(object, label, context);
@@ -3287,7 +3733,8 @@ function convertNode(node, parentSegments, context) {
     const pages = [];
     const hasOwnPath = typeof object.path === "string" && object.path.trim().length > 0;
     if (hasOwnPath) {
-      pages.push(registerPageAt(object.path, segments.join("/"), context));
+      const registered = registerPageAt(object.path, segments.join("/"), context);
+      if (registered) pages.push(registered);
     }
     for (const child of contents) {
       const converted = convertNode(child, segments, context);
@@ -3364,6 +3811,7 @@ function resolveVersionedNavigation(config, configDir, fernRoot, context) {
     }
     const versionConfig = objectValue3(readBoundedYaml(versionPath));
     if (!versionConfig) return config;
+    context.pathPrefix = relative4(fernRoot, dirname3(versionPath)).replace(/\\/g, "/");
     return { ...config, navigation: versionConfig.navigation, tabs: versionConfig.tabs ?? config.tabs };
   } catch (error) {
     warnOnce2(
@@ -3463,6 +3911,8 @@ function projectFernProducts(rawProducts, fernRoot, context) {
 }
 function projectFernNavigation(input) {
   const context = {
+    fernRoot: input.fernRoot,
+    repositoryRoot: input.repositoryRoot ?? input.fernRoot,
     descriptors: [],
     seenNavigationIds: /* @__PURE__ */ new Set(),
     apiSections: [],
@@ -3618,7 +4068,8 @@ var REPOSITORY_ONLY_DOCUMENTS = /* @__PURE__ */ new Set([
   "security.md"
 ]);
 var SNIPPET_DIRECTORIES = /* @__PURE__ */ new Set(["snippets", "_snippets", "partials", "_partials"]);
-var SNIPPET_IMPORT_PATTERN = /^import\s+(?:\{\s*(?:default\s+as\s+)?([A-Z][A-Za-z0-9_]*)\s*\}|([A-Z][A-Za-z0-9_]*))\s+from\s+['"]([^'"]+\.mdx?)['"]\s*;?(?:\s*\/\/.*)?$/gm;
+var SNIPPET_IMPORT_PATTERN = /\bimport\s+(?:\{\s*(?:default\s+as\s+)?([A-Z][A-Za-z0-9_]*)\s*\}|([A-Z][A-Za-z0-9_]*))\s+from\s+['"]([^'"]+\.mdx?)['"]\s*;?/g;
+var SNIPPET_VALUE_IMPORT_PATTERN = /\bimport\s*\{([^{}]+)\}\s*from\s+['"]([^'"]+\.mdx?)['"]\s*;?/g;
 var SNIPPET_TAG_PATTERN = /<Snippet\s+file=(?:"([^"]+)"|'([^']+)')\s*(?:\/>|>[\s\S]*?<\/Snippet>)/g;
 var MINTIGNORE_FILENAME = ".mintignore";
 var createIgnoreMatcher = createRequire(import.meta.url)("ignore");
@@ -3664,7 +4115,7 @@ function countMarkdownPages(directory, limit = 2e4) {
     const current = stack.pop();
     let entries;
     try {
-      entries = readdirSync(current, { withFileTypes: true });
+      entries = readdirSync2(current, { withFileTypes: true });
     } catch {
       continue;
     }
@@ -3683,7 +4134,7 @@ function pickPreferredDocsRoot(candidates, repositoryDir, platformLabel, warning
   const ranked = [...candidates].sort((left, right) => {
     const byRank = (rank?.(right) ?? 0) - (rank?.(left) ?? 0);
     if (byRank !== 0) return byRank;
-    const byName = (basename2(right) === "docs" ? 1 : 0) - (basename2(left) === "docs" ? 1 : 0);
+    const byName = (basename3(right) === "docs" ? 1 : 0) - (basename3(left) === "docs" ? 1 : 0);
     if (byName !== 0) return byName;
     return countMarkdownPages(right) - countMarkdownPages(left);
   });
@@ -3717,7 +4168,7 @@ function findMintlifyProjectRoot(repositoryDir, docsDir, warnings) {
     visited++;
     if (hasMintlifyConfig(current.directory)) candidates.push(current.directory);
     if (current.depth >= 4) continue;
-    for (const entry of readdirSync(current.directory, { withFileTypes: true })) {
+    for (const entry of readdirSync2(current.directory, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.isSymbolicLink() || isIgnoredDirectory(entry.name)) continue;
       queue.push({ directory: resolveWithin(current.directory, entry.name), depth: current.depth + 1 });
     }
@@ -3749,7 +4200,7 @@ function findFernProjectRoot(repositoryDir, docsDir) {
     visited++;
     if (hasFernConfig(current.directory)) return current.directory;
     if (current.depth >= 4) continue;
-    for (const entry of readdirSync(current.directory, { withFileTypes: true })) {
+    for (const entry of readdirSync2(current.directory, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.isSymbolicLink() || isIgnoredDirectory(entry.name)) continue;
       queue.push({ directory: resolveWithin(current.directory, entry.name), depth: current.depth + 1 });
     }
@@ -3775,7 +4226,7 @@ function findDocusaurusProjectRoot(repositoryDir, docsDir, warnings) {
     visited++;
     if (hasDocusaurusConfig(current.directory)) candidates.push(current.directory);
     if (current.depth >= 4) continue;
-    for (const entry of readdirSync(current.directory, { withFileTypes: true })) {
+    for (const entry of readdirSync2(current.directory, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.isSymbolicLink() || isIgnoredDirectory(entry.name)) continue;
       queue.push({
         directory: resolveWithin(current.directory, entry.name),
@@ -3796,6 +4247,52 @@ function primaryDocusaurusDocsDirectory(projectRoot) {
   const configured = source.match(/\bdocs\s*:\s*\{[\s\S]{0,4000}?\bpath\s*:\s*(['"])([^'"]+)\1/)?.[2];
   return trimTrailingSlashes(configured?.replace(/^\.\//, "") ?? "") || "docs";
 }
+function docusaurusArchiveRoots(projectRoot, repositoryDir, warnings) {
+  const archives = [];
+  const relativeRoot = relative5(repositoryDir, projectRoot).replace(/\\/g, "/");
+  const directoryNames = (directory) => {
+    const path = resolveWithin(projectRoot, directory);
+    if (!existsSync5(path) || !lstatSync5(path).isDirectory()) return [];
+    return readdirSync2(path, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.isSymbolicLink()).map((entry) => entry.name).sort();
+  };
+  let versions = directoryNames("versioned_docs").filter((name) => /^version-[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name));
+  const versionsPath = resolveWithin(projectRoot, "versions.json");
+  if (existsSync5(versionsPath) && lstatSync5(versionsPath).isFile()) {
+    try {
+      if (lstatSync5(versionsPath).size > 1e5) throw new Error("file exceeds the 100 KB limit");
+      const declared = JSON.parse(readFileSync5(versionsPath, "utf8"));
+      if (!Array.isArray(declared) || !declared.every((value) => typeof value === "string")) throw new Error("expected an array of version names");
+      const declaredOrder = declared.map((value) => `version-${value}`);
+      versions = [...declaredOrder.filter((name) => versions.includes(name)), ...versions.filter((name) => !declaredOrder.includes(name))];
+    } catch (error) {
+      warnings.push({ code: "unsupported-config", message: `Docusaurus versions.json could not be read safely: ${error instanceof Error ? error.message : String(error)}` });
+    }
+  }
+  const sidebarPath = (version) => {
+    const candidates = ["json", "js", "cjs", "mjs", "ts"].map((extension) => `versioned_sidebars/${version}-sidebars.${extension}`);
+    return candidates.find((candidate) => {
+      const path = resolveWithin(projectRoot, candidate);
+      return existsSync5(path) && lstatSync5(path).isFile();
+    });
+  };
+  const add = (directory, routePrefix, label, sidebar) => {
+    const docsDir = [relativeRoot, directory].filter(Boolean).join("/");
+    archives.push({ docsDir, routePrefix, label, ...sidebar ? { sidebarPath: sidebar } : {} });
+  };
+  for (const version of versions) add(`versioned_docs/${version}`, version.slice("version-".length), `Version ${version.slice("version-".length)}`, sidebarPath(version));
+  for (const locale of directoryNames("i18n").filter((name) => /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{2,8})*$/.test(name))) {
+    const localizedRoot = `i18n/${locale}/docusaurus-plugin-content-docs`;
+    const current = resolveWithin(projectRoot, `${localizedRoot}/current`);
+    if (existsSync5(current) && lstatSync5(current).isDirectory()) add(`${localizedRoot}/current`, locale, `${locale} Documentation`);
+    const localizedVersions = directoryNames(localizedRoot).filter((name) => /^version-[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name));
+    for (const version of localizedVersions) {
+      const path = resolveWithin(projectRoot, `${localizedRoot}/${version}`);
+      if (existsSync5(path) && lstatSync5(path).isDirectory()) add(`${localizedRoot}/${version}`, `${locale}/${version.slice("version-".length)}`, `${locale} Version ${version.slice("version-".length)}`);
+    }
+  }
+  if (archives.length > 48) warnings.push({ code: "limit-reached", message: `Only the first 48 Docusaurus archived or localized docs roots were imported (${archives.length} found).` });
+  return archives.slice(0, 48);
+}
 function additionalDocusaurusPluginRoots(repositoryDir, projectRoot, warnings) {
   const source = readDocusaurusConfigSource(projectRoot);
   const plugins = [];
@@ -4022,10 +4519,10 @@ function detectRepositoryPlatform(repositoryDir, docsDir) {
 }
 function containsMarkdown(directory, depth = 0) {
   if (depth > 4) return false;
-  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+  for (const entry of readdirSync2(directory, { withFileTypes: true })) {
     if (isIgnoredDirectory(entry.name) || entry.isSymbolicLink()) continue;
     const path = resolveWithin(directory, entry.name);
-    if (entry.isFile() && [".md", ".mdx"].includes(extname4(entry.name).toLowerCase())) return true;
+    if (entry.isFile() && [".md", ".mdx"].includes(extname5(entry.name).toLowerCase())) return true;
     if (entry.isDirectory() && containsMarkdown(path, depth + 1)) return true;
   }
   return false;
@@ -4058,7 +4555,7 @@ function scanFiles(root, confinementRoot = root, warnings) {
     visitedRealPaths.add(directoryReal);
     let entries;
     try {
-      entries = readdirSync(directory, { withFileTypes: true });
+      entries = readdirSync2(directory, { withFileTypes: true });
     } catch {
       return;
     }
@@ -4151,7 +4648,25 @@ function exactReferenceKey(value) {
   return value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/").replace(/\.(?:mdx?|rst|txt)$/i, "");
 }
 function findOpenApi(files) {
-  return files.find((file) => OPENAPI_FILENAMES.has(basename2(file.relativePath).toLowerCase())) ?? null;
+  return files.find((file) => OPENAPI_FILENAMES.has(basename3(file.relativePath).toLowerCase()) && classifyApiSpec(file.absolutePath) === "openapi") ?? null;
+}
+function classifyApiSpec(path) {
+  const buffer = Buffer.alloc(64e3);
+  let bytesRead = 0;
+  try {
+    const descriptor = openSync(path, "r");
+    try {
+      bytesRead = readSync(descriptor, buffer, 0, buffer.length, 0);
+    } finally {
+      closeSync(descriptor);
+    }
+  } catch {
+    return "unknown";
+  }
+  const text = buffer.toString("utf8", 0, bytesRead);
+  const topLevel = text.match(/^(?:openapi|swagger|asyncapi)\s*:/m)?.[0] ?? text.match(/^\s*\{\s*"(?:openapi|swagger|asyncapi)"\s*:/m)?.[0];
+  if (!topLevel) return "unknown";
+  return /asyncapi/i.test(topLevel) ? "asyncapi" : "openapi";
 }
 function mintlifyTopLevelApiReferences(config) {
   const api = config?.api && typeof config.api === "object" && !Array.isArray(config.api) ? config.api : null;
@@ -4200,7 +4715,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings) {
       });
       continue;
     }
-    specs.push({ filename: basename2(match.relativePath), content: readFileSync5(match.absolutePath), tabLabel: reference.tabLabel });
+    specs.push({ filename: basename3(match.relativePath), content: readFileSync5(match.absolutePath), tabLabel: reference.tabLabel });
   }
   return specs;
 }
@@ -4267,6 +4782,12 @@ function findFernConfiguredOpenApi(fernRoot, repositoryDir, apiName, apiNameExpl
       try {
         const absolute = resolveWithinRoot(dir, specPath, repositoryDir);
         if (!existsSync5(absolute) || !lstatSync5(absolute).isFile()) continue;
+        const kind = classifyApiSpec(absolute);
+        if (kind === "asyncapi") {
+          unsupported.push({ kind: "asyncapi", path: specPath });
+          continue;
+        }
+        if (kind !== "openapi") continue;
         return { spec: { absolutePath: absolute, relativePath: relative5(repositoryDir, absolute).replace(/\\/g, "/") }, unsupported };
       } catch {
         warnings.push({
@@ -4304,9 +4825,11 @@ function staticSnippetProperties(attributes) {
   }
   return properties;
 }
-function interpolateSnippet(snippet, attributes) {
+function interpolateSnippet(snippet, attributes, children) {
   const properties = staticSnippetProperties(attributes);
+  if (children !== void 0) properties.set("children", children.trim());
   if (properties.size === 0) return snippet;
+  const isJsxSnippet = /<[A-Za-z][A-Za-z0-9]*/.test(snippet);
   let fence = "";
   return snippet.split("\n").map((line) => {
     const marker = line.match(/^\s*(`{3,}|~{3,})/)?.[1];
@@ -4317,11 +4840,234 @@ function interpolateSnippet(snippet, attributes) {
     }
     if (fence) return line;
     return line.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (original, name) => {
-      return properties.get(name) ?? original;
+      const value = properties.get(name);
+      if (value === void 0) return original;
+      if (name === "children") return value;
+      return isJsxSnippet ? `{${JSON.stringify(value)}}` : value;
     });
   }).join("\n");
 }
+function snippetComponentBody(source, componentName) {
+  const parsed = ts2.createSourceFile("snippet.tsx", source, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
+  for (const statement of parsed.statements) {
+    if (!ts2.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts2.isIdentifier(declaration.name) || declaration.name.text !== componentName) continue;
+      const initializer = declaration.initializer;
+      if (!initializer || !ts2.isArrowFunction(initializer)) continue;
+      const returned = ts2.isBlock(initializer.body) ? initializer.body.statements.find(ts2.isReturnStatement)?.expression : initializer.body;
+      if (!returned) continue;
+      let expression = returned;
+      while (ts2.isParenthesizedExpression(expression)) expression = expression.expression;
+      if (ts2.isJsxElement(expression) || ts2.isJsxSelfClosingElement(expression) || ts2.isJsxFragment(expression)) {
+        return expression.getText(parsed);
+      }
+    }
+  }
+  return source;
+}
+function statefulSnippetDeclaration(source, componentName) {
+  const parsed = ts2.createSourceFile("snippet.tsx", source, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
+  if (parsed.statements.length !== 1) return null;
+  const statement = parsed.statements[0];
+  if (!ts2.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword) || statement.declarationList.declarations.length !== 1) return null;
+  const declaration = statement.declarationList.declarations[0];
+  if (!ts2.isIdentifier(declaration.name) || declaration.name.text !== componentName || !declaration.initializer || !ts2.isArrowFunction(declaration.initializer) || !ts2.isBlock(declaration.initializer.body)) return null;
+  const body = declaration.initializer.body.statements;
+  if (body.length < 2 || !body.some(ts2.isReturnStatement)) return null;
+  return source.trim();
+}
+function staticNamedSnippetValues(source) {
+  const values = /* @__PURE__ */ new Map();
+  const parsed = ts2.createSourceFile("snippet.tsx", source, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
+  for (const statement of parsed.statements) {
+    if (!ts2.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts2.isIdentifier(declaration.name) || !declaration.initializer) continue;
+      const expression = declaration.initializer;
+      if (ts2.isStringLiteral(expression) || ts2.isNoSubstitutionTemplateLiteral(expression)) {
+        values.set(declaration.name.text, JSON.stringify(expression.text));
+      } else if (ts2.isNumericLiteral(expression)) {
+        values.set(declaration.name.text, expression.text);
+      } else if (expression.kind === ts2.SyntaxKind.TrueKeyword || expression.kind === ts2.SyntaxKind.FalseKeyword) {
+        values.set(declaration.name.text, expression.kind === ts2.SyntaxKind.TrueKeyword ? "true" : "false");
+      }
+    }
+  }
+  return values;
+}
+function hoistMdxImports(source) {
+  const imports2 = /* @__PURE__ */ new Set();
+  const withoutImports = replaceOutsideCode(source, (body) => body.replace(
+    /^[ \t]*import\s+(?:\{[^}\n]+\}|[A-Za-z_$][\w$]*)\s+from\s+(['"])[^'"\n]+\1[ \t]*;?/gm,
+    (statement) => {
+      imports2.add(statement.trim().replace(/;?$/, ";"));
+      return "";
+    }
+  ));
+  if (imports2.size === 0) return source;
+  const frontmatter = withoutImports.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+  const prefix = frontmatter?.[0] ?? "";
+  return `${prefix}${[...imports2].join("\n")}
+
+${withoutImports.slice(prefix.length).replace(/^(?:\r?\n)*/, "")}`;
+}
+function fernSourceBasePath(config) {
+  const instance = Array.isArray(config.instances) ? config.instances[0] : null;
+  if (!instance || typeof instance !== "object" || Array.isArray(instance)) return "";
+  const value = instance;
+  const address = typeof value["custom-domain"] === "string" ? value["custom-domain"] : value.url;
+  if (typeof address !== "string") return "";
+  try {
+    const path = new URL(/^https?:\/\//i.test(address) ? address : `https://${address}`).pathname.replace(/\/+$/, "");
+    return path === "/" ? "" : path;
+  } catch {
+    return "";
+  }
+}
+function fernDefaultVersionPath(config) {
+  if (!Array.isArray(config.versions)) return "";
+  const versions = config.versions.filter((entry) => !!entry && typeof entry === "object" && !Array.isArray(entry));
+  const chosen = versions.find((version) => version.default === true) ?? versions[0];
+  return typeof chosen?.slug === "string" && /^[A-Za-z0-9_-]+$/.test(chosen.slug) ? `/${chosen.slug}` : "";
+}
+function fernSourceSiteUrl(config) {
+  const instance = Array.isArray(config.instances) ? config.instances[0] : null;
+  if (!instance || typeof instance !== "object" || Array.isArray(instance)) return void 0;
+  const value = instance;
+  const address = typeof value["custom-domain"] === "string" ? value["custom-domain"] : value.url;
+  if (typeof address !== "string") return void 0;
+  try {
+    const url = new URL(/^https?:\/\//i.test(address) ? address : `https://${address}`);
+    return `${url.origin}${fernSourceBasePath(config)}${fernDefaultVersionPath(config)}`;
+  } catch {
+    return void 0;
+  }
+}
+function externalizeMissingFernLinks(body, pageIds, sourceSiteUrl, externalized) {
+  const rewrite = (target) => {
+    const path = target.split(/[?#]/, 1)[0].replace(/^\//, "").replace(/\/$/, "");
+    if (!path || pageIds.has(path)) return target;
+    try {
+      const base = new URL(`${sourceSiteUrl}/`);
+      const sourceLinkUrl = new URL(target.slice(1), base);
+      if (sourceLinkUrl.origin !== base.origin) return target;
+      const sourceLink = sourceLinkUrl.toString();
+      externalized.add(target);
+      return sourceLink;
+    } catch {
+      return target;
+    }
+  };
+  return replaceOutsideCode(body, (text) => text.replace(/(\]\()\/(?!\/)([^\s)]+)(\))/g, (_match, before, target, after) => `${before}${rewrite(`/${target}`)}${after}`).replace(/(\b(?:href|to)=(['"]))\/(?!\/)([^'"\n]+)\2/g, (_match, before, quote, target) => `${before}${rewrite(`/${target}`)}${quote}`));
+}
+function stripFernBasePathFromLinks(body, basePath) {
+  if (!basePath) return body;
+  const escaped = basePath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return replaceOutsideCode(body, (text) => text.replace(new RegExp(`(\\]\\()${escaped}(?=\\/|[)#?])`, "g"), (match, prefix, offset, source) => prefix + (source[offset + match.length] === "/" ? "" : "/")).replace(new RegExp(`(\\b(?:href|to)=["'])${escaped}(?=\\/|["'#?])`, "g"), (match, prefix, offset, source) => prefix + (source[offset + match.length] === "/" ? "" : "/")));
+}
+function rewriteMintlifyMountedLinks(body, pageIds) {
+  const rewrite = (target) => {
+    const suffixAt = target.search(/[?#]/);
+    const pathname = suffixAt < 0 ? target : target.slice(0, suffixAt);
+    const suffix = suffixAt < 0 ? "" : target.slice(suffixAt);
+    if (!pathname.startsWith("/") || pathname.startsWith("//") || pathname.includes("\\")) return target;
+    const segments = pathname.slice(1).split("/");
+    if (segments.some((segment) => !segment || segment === "." || segment === "..")) return target;
+    if (pageIds.has(segments.join("/"))) return target;
+    for (let count = 1; count < segments.length && count <= 3; count++) {
+      const candidate = segments.slice(count).join("/");
+      if (pageIds.has(candidate)) return `/${candidate}${suffix}`;
+    }
+    return target;
+  };
+  return replaceOutsideCode(body, (text) => text.replace(/(\]\()(\/[^\s)]+)(\))/g, (_match, before, target, after) => `${before}${rewrite(target)}${after}`).replace(/(\b(?:href|to)=(['"]))(\/[^'"\n]+)\2/g, (_match, before, quote, target) => `${before}${rewrite(target)}${quote}`));
+}
+function preserveDocusaurusLinkedAnchors(pages) {
+  const pageById = new Map(pages.map((page) => [page.id, page]));
+  const requested = /* @__PURE__ */ new Map();
+  const crossPageRequests = /* @__PURE__ */ new Set();
+  const addTarget = (target, currentId) => {
+    const hash2 = target.indexOf("#");
+    if (hash2 < 0) return;
+    const fragment = target.slice(hash2 + 1);
+    if (!/^[A-Za-z0-9_.:-]{1,120}$/.test(fragment)) return;
+    const path = target.slice(0, hash2).split("?")[0];
+    const id = target.startsWith("#") ? currentId : path.startsWith("/") && !path.startsWith("//") ? path.replace(/^\//, "").replace(/\/$/, "") || "introduction" : "";
+    if (!pageById.has(id)) return;
+    if (!requested.has(id)) requested.set(id, /* @__PURE__ */ new Set());
+    requested.get(id).add(fragment);
+    if (id !== currentId) crossPageRequests.add(`${id}#${fragment}`);
+  };
+  for (const page of pages) {
+    replaceOutsideCode(page.body, (text) => {
+      for (const match of text.matchAll(/\]\(([^)\s]+)\)/g)) addTarget(match[1], page.id);
+      for (const match of text.matchAll(/\b(?:href|to)=(['"])([^'"\n]+)\1/g)) addTarget(match[2], page.id);
+      return text;
+    });
+  }
+  const comparable = (value) => value.replace(/&(?:lt|gt|amp|quot);/g, " ").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
+  for (const page of pages) {
+    const fragments = requested.get(page.id);
+    if (!fragments?.size) continue;
+    const lines = page.body.split("\n");
+    let fence;
+    const tableCells = [];
+    const headings = lines.map((line, 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 = void 0;
+        return null;
+      }
+      if (fence) return null;
+      const tableCell = line.match(/^ {0,3}\|\s*([^|]+?)\s*\|/);
+      if (tableCell && !/^[:\s-]+$/.test(tableCell[1])) tableCells.push({ index, text: tableCell[1] });
+      const match = line.match(/^ {0,3}#{1,6}\s+(.+?)\s*#*\s*$/);
+      return match ? { index, text: match[1] } : null;
+    }).filter((entry) => entry !== null);
+    const existing = /* @__PURE__ */ new Set();
+    replaceOutsideCode(page.body, (text) => {
+      for (const match of text.matchAll(/\bid=(?:"([^"]+)"|'([^']+)')/g)) existing.add(match[1] ?? match[2]);
+      return text;
+    });
+    const candidateIndexes = /* @__PURE__ */ new Map();
+    for (const heading of headings) {
+      const key = comparable(heading.text);
+      candidateIndexes.set(key, [...candidateIndexes.get(key) ?? [], { index: heading.index, kind: "heading" }]);
+    }
+    for (const cell of tableCells) {
+      const key = comparable(cell.text);
+      candidateIndexes.set(key, [...candidateIndexes.get(key) ?? [], { index: cell.index, kind: "table" }]);
+    }
+    for (const heading of headings) existing.add(heading.text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, ""));
+    const headingAliases = /* @__PURE__ */ new Map();
+    const tableAliases = /* @__PURE__ */ new Map();
+    for (const fragment of fragments) {
+      if (existing.has(fragment)) continue;
+      const matches = candidateIndexes.get(comparable(fragment)) ?? [];
+      let match = matches.length === 1 ? matches[0] : void 0;
+      if (!match && matches.length > 1 && !crossPageRequests.has(`${page.id}#${fragment}`)) {
+        const escaped = fragment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const linkPattern = new RegExp(`\\]\\(#${escaped}\\)|\\b(?:href|to)=["']#${escaped}["']`);
+        const linkIndexes = lines.flatMap((line, index2) => linkPattern.test(line) ? [index2] : []);
+        const selections = linkIndexes.map((index2) => matches.filter((candidate) => candidate.index < index2).at(-1));
+        if (selections.length && selections.every((candidate) => candidate?.index === selections[0]?.index)) match = selections[0];
+      }
+      if (!match) continue;
+      const { index, kind } = match;
+      const aliases = kind === "heading" ? headingAliases : tableAliases;
+      aliases.set(index, [...aliases.get(index) ?? [], fragment]);
+      existing.add(fragment);
+    }
+    if (headingAliases.size || tableAliases.size) page.body = lines.flatMap((line, index) => [
+      ...(headingAliases.get(index) ?? []).map((fragment) => `<a id="${fragment}"></a>`),
+      tableAliases.has(index) ? line.replace(/^( {0,3}\|\s*)/, (prefix) => `${prefix}${tableAliases.get(index).map((fragment) => `<a id="${fragment}"></a>`).join("")}`) : line
+    ]).join("\n");
+  }
+}
 function resolveSnippetPath(sourcePath, currentFile, repositoryRoot, siteRoot) {
+  sourcePath = sourcePath.replace(/\\(?=_)/g, "");
   const repositoryRelative = sourcePath.startsWith("@site/") ? relative5(repositoryRoot, resolveWithin(siteRoot, sourcePath.slice("@site/".length))).replace(/\\/g, "/") : sourcePath.startsWith("/") ? relative5(repositoryRoot, resolveWithin(siteRoot, sourcePath.replace(/^\/+/, ""))).replace(/\\/g, "/") : relative5(repositoryRoot, resolvePath(dirname4(currentFile), sourcePath)).replace(/\\/g, "/");
   const candidate = resolveWithin(repositoryRoot, repositoryRelative);
   resolveWithin(repositoryRoot, relative5(repositoryRoot, candidate));
@@ -4332,12 +5078,12 @@ function globalSnippetAliases(files, repositoryRoot, siteRoot) {
   for (const file of files) {
     const segments = file.relativePath.split("/");
     if (!segments.some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase()))) continue;
-    const basenameWithoutExtension = basename2(file.relativePath).replace(/\.mdx?$/i, "");
+    const basenameWithoutExtension = basename3(file.relativePath).replace(/\.mdx?$/i, "");
     const conventionalAlias = basenameWithoutExtension.split(/[^A-Za-z0-9]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
     if (conventionalAlias) aliases.set(conventionalAlias, file.absolutePath);
   }
   for (const file of files) {
-    if (![".md", ".mdx"].includes(extname4(file.relativePath).toLowerCase())) continue;
+    if (![".md", ".mdx"].includes(extname5(file.relativePath).toLowerCase())) continue;
     const raw = readFileSync5(file.absolutePath, "utf8");
     for (const match of raw.matchAll(SNIPPET_IMPORT_PATTERN)) {
       try {
@@ -4365,7 +5111,7 @@ function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
   } catch {
     return null;
   }
-  if (!ASSET_EXTENSIONS.has(extname4(decodedPath).toLowerCase())) return null;
+  if (!ASSET_EXTENSIONS.has(extname5(decodedPath).toLowerCase())) return null;
   try {
     const candidate = decodedPath.startsWith("/") ? resolveWithin(siteRoot, decodedPath.replace(/^\/+/, "")) : resolveWithin(dirname4(currentFile), decodedPath);
     const siteRelative = relative5(siteRoot, candidate).replace(/\\/g, "/");
@@ -4381,15 +5127,7 @@ function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
   }
 }
 function rewriteFernIdRenameLinks(body, renames) {
-  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;
+  return replaceOutsideCode(body, (text) => {
     const rewriteTarget = (target) => {
       const suffixIndex = target.search(/[?#]/);
       const path = (suffixIndex >= 0 ? target.slice(0, suffixIndex) : target).replace(/^\/+/, "");
@@ -4397,8 +5135,8 @@ function rewriteFernIdRenameLinks(body, renames) {
       const renamed = renames.get(path);
       return renamed ? `/${renamed}${suffix}` : 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");
+    return text.replace(/(\]\()\/([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(`/${target}`)}`).replace(/(\bhref=")\/([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(`/${target}`)}${suffix}`);
+  });
 }
 function rewriteRepositoryAssetLinks(body, currentFile, siteRoot, onReferenced) {
   return body.replace(/(!?\[[^\]]*\]\()(<[^>]+>|[^)\s]+)([^)]*\))/g, (original, opening, destination, closing) => {
@@ -4428,8 +5166,10 @@ function locallyDeclaredNames(raw) {
 }
 function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0, siteRoot = repositoryRoot, globalAliases = /* @__PURE__ */ new Map()) {
   if (depth >= 8) return raw;
+  raw = normalizeIndentedFences(raw);
   const snippets = /* @__PURE__ */ new Map();
-  const withoutImports = raw.replace(
+  const preservedDeclarations = /* @__PURE__ */ new Map();
+  let withoutImports = replaceOutsideCode(raw, (source) => source.replace(
     SNIPPET_IMPORT_PATTERN,
     (_statement, namedComponent, defaultComponent, sourcePath) => {
       const componentName = namedComponent ?? defaultComponent;
@@ -4445,7 +5185,9 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
           siteRoot,
           globalAliases
         );
-        snippets.set(componentName, nested);
+        const declaration = statefulSnippetDeclaration(nested, componentName);
+        if (declaration) preservedDeclarations.set(componentName, declaration);
+        else snippets.set(componentName, snippetComponentBody(nested, componentName));
         return "";
       } catch {
         warnings.push({
@@ -4457,7 +5199,40 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
         return "";
       }
     }
-  );
+  ));
+  withoutImports = replaceOutsideCode(withoutImports, (source) => source.replace(
+    SNIPPET_VALUE_IMPORT_PATTERN,
+    (statement, names, sourcePath) => {
+      const bindings = names.split(",").map((name) => name.trim()).filter(Boolean).map((name) => {
+        const parsed = name.match(/^([A-Za-z_$][\w$]*)(?:\s+as\s+([A-Za-z_$][\w$]*))?$/);
+        return parsed ? { exported: parsed[1], local: parsed[2] ?? parsed[1] } : null;
+      });
+      if (bindings.length === 0 || bindings.some((binding) => !binding)) return statement;
+      try {
+        const candidate = resolveSnippetPath(sourcePath, currentFile, repositoryRoot, siteRoot);
+        if (!existsSync5(candidate) || !lstatSync5(candidate).isFile()) return statement;
+        const snippetSource = readFileSync5(candidate, "utf8");
+        const values = staticNamedSnippetValues(snippetSource);
+        const declarations = [];
+        const components = [];
+        for (const binding of bindings) {
+          const value = values.get(binding.exported);
+          if (value !== void 0) {
+            declarations.push(`export const ${binding.local} = ${value};`);
+            continue;
+          }
+          if (!/^[A-Z]/.test(binding.exported)) return statement;
+          const body = snippetComponentBody(snippetSource, binding.exported);
+          if (body === snippetSource) return statement;
+          components.push([binding.local, body]);
+        }
+        for (const [name, body] of components) snippets.set(name, body);
+        return declarations.join("\n");
+      } catch {
+        return statement;
+      }
+    }
+  ));
   const localNames = locallyDeclaredNames(withoutImports);
   for (const [componentName, candidate] of globalAliases) {
     if (snippets.has(componentName) || localNames.has(componentName) || !new RegExp(`<${componentName}(?:\\s|/?>)`).test(withoutImports)) continue;
@@ -4470,14 +5245,16 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
       siteRoot,
       globalAliases
     );
-    snippets.set(componentName, nested);
+    const declaration = statefulSnippetDeclaration(nested, componentName);
+    if (declaration) preservedDeclarations.set(componentName, declaration);
+    else snippets.set(componentName, snippetComponentBody(nested, componentName));
   }
   let result = withoutImports;
   for (const [componentName, snippet] of snippets) {
     result = result.replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)\\s*/>`, "g"), (_tag, attributes) => {
       return interpolateSnippet(snippet, attributes);
-    }).replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)>(?:[\\s\\S]*?)<\\/${componentName}>`, "g"), (_tag, attributes) => {
-      return interpolateSnippet(snippet, attributes);
+    }).replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)>([\\s\\S]*?)<\\/${componentName}>`, "g"), (_tag, attributes, children) => {
+      return interpolateSnippet(snippet, attributes, children);
     });
   }
   result = result.replace(SNIPPET_TAG_PATTERN, (_tag, doubleQuoted, singleQuoted) => {
@@ -4503,13 +5280,25 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
       return `{/* Missing snippet: ${filePath} */}`;
     }
   });
-  return result;
+  if (preservedDeclarations.size > 0) {
+    const frontmatter = result.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+    const prefix = frontmatter?.[0] ?? "";
+    result = `${prefix}${[...preservedDeclarations.values()].join("\n\n")}
+
+${result.slice(prefix.length)}`;
+  }
+  return depth === 0 ? hoistMdxImports(result) : result;
 }
 function injectOpenApiSpecs(config, specs) {
   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}`, navigation: false };
+    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}` } }];
   }
   return { ...config, tabs };
@@ -4547,30 +5336,6 @@ function migrateRepository(options) {
     }
     return platform === "mintlify" ? "" : detectRepositoryDocsDir(repositoryDir);
   })();
-  if (platform === "docusaurus" && docusaurusProjectRoot) {
-    for (const [directory, label] of [
-      ["versioned_docs", "versioned docs"],
-      ["versioned_sidebars", "versioned sidebars"]
-    ]) {
-      const path = resolveWithin(docusaurusProjectRoot, directory);
-      if (!existsSync5(path) || !lstatSync5(path).isDirectory()) continue;
-      const versions = readdirSync(path, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-      if (versions.length) warnings.push({
-        code: "unsupported-config",
-        message: `Docusaurus ${label} were skipped; only current docs were imported. Skipped: ${versions.join(", ")}.`,
-        source: directory
-      });
-    }
-    const i18nPath = resolveWithin(docusaurusProjectRoot, "i18n");
-    if (existsSync5(i18nPath) && lstatSync5(i18nPath).isDirectory()) {
-      const locales = readdirSync(i18nPath, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-      if (locales.length) warnings.push({
-        code: "unsupported-config",
-        message: `Docusaurus localized content was skipped; only the default locale was imported. Skipped locales: ${locales.join(", ")}.`,
-        source: "i18n"
-      });
-    }
-  }
   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: [] };
@@ -4580,7 +5345,11 @@ function migrateRepository(options) {
   let docusaurusSidebars = null;
   let mintlifyConfig = null;
   let fernRawConfig = null;
+  let fernBasePath = "";
+  let fernVersionPath = "";
   let fernApiSections = [];
+  const fernReferencedPaths = /* @__PURE__ */ new Set();
+  const fernSourceLinkAliases = /* @__PURE__ */ new Map();
   if (platform === "mintlify") {
     try {
       const config = readMintlifyConfig(mintlifyProjectRoot ?? repositoryDir);
@@ -4609,11 +5378,23 @@ function migrateRepository(options) {
       const fernConfig = readFernConfig(fernProjectRoot);
       if (fernConfig) {
         fernRawConfig = fernConfig.config;
-        const projected = projectFernNavigation({ config: fernConfig.config, fernRoot: fernProjectRoot });
+        fernBasePath = fernSourceBasePath(fernConfig.config);
+        fernVersionPath = fernDefaultVersionPath(fernConfig.config);
+        const projected = projectFernNavigation({ config: fernConfig.config, fernRoot: fernProjectRoot, repositoryRoot: repositoryDir });
         docsConfig = projected.docsConfig;
         warnings.push(...projected.warnings);
         fernApiSections = projected.apiSections;
         for (const [index, descriptor] of projected.descriptors.entries()) {
+          fernReferencedPaths.add(descriptor.sourcePath);
+          const sourceTail = descriptor.sourcePath.match(/(?:^|\/)pages\/(.+)\.mdx?$/i)?.[1]?.replace(/\/index$/i, "");
+          if (sourceTail) {
+            const routeSegments = descriptor.navigationId.split("/");
+            const sourceSegments = sourceTail.split("/");
+            if (routeSegments.length === sourceSegments.length + 1) {
+              const alias = `${routeSegments[0]}/${sourceTail}`;
+              if (alias !== descriptor.navigationId && !fernSourceLinkAliases.has(alias)) fernSourceLinkAliases.set(alias, descriptor.navigationId);
+            }
+          }
           const key = normalizedReferenceKey(descriptor.sourcePath);
           if (!referenceMap.has(key)) referenceMap.set(key, { navigationId: descriptor.navigationId });
           const exactKey = exactReferenceKey(descriptor.sourcePath);
@@ -4630,7 +5411,7 @@ function migrateRepository(options) {
   }
   if (platform === "docusaurus") {
     try {
-      docusaurusSidebars = options.docusaurusSkipSidebar || !docusaurusProjectRoot ? null : readDocusaurusSidebars(docusaurusProjectRoot);
+      docusaurusSidebars = options.docusaurusSkipSidebar || !docusaurusProjectRoot ? null : readDocusaurusSidebars(docusaurusProjectRoot, options.docusaurusSidebarPath);
     } catch (error) {
       warnings.push({
         code: "unsupported-config",
@@ -4644,6 +5425,19 @@ function migrateRepository(options) {
   }
   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);
+  if (platform === "fern" && fernProjectRoot) {
+    const scanned = new Set(files.map((file) => file.absolutePath));
+    for (const sourcePath of fernReferencedPaths) {
+      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);
+      } catch {
+        warnings.push({ code: "missing-page", message: "A Fern navigation path could not be read within this repository.", source: sourcePath });
+      }
+    }
+  }
   const pages = [];
   const assets = [];
   const referencedAssetPaths = /* @__PURE__ */ new Map();
@@ -4673,16 +5467,16 @@ function migrateRepository(options) {
       continue;
     }
     const sourceSegments = file.relativePath.split("/");
-    if (sourceSegments.some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase())) || platform === "docusaurus" && basename2(file.relativePath).startsWith("_")) {
+    if (sourceSegments.some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase())) || platform === "docusaurus" && basename3(file.relativePath).startsWith("_")) {
       skipped++;
       continue;
     }
-    const rootFilename = !file.relativePath.includes("/") ? basename2(file.relativePath).toLowerCase() : "";
+    const rootFilename = !file.relativePath.includes("/") ? basename3(file.relativePath).toLowerCase() : "";
     if (REPOSITORY_ONLY_DOCUMENTS.has(rootFilename) && !exactReferenceMap.has(exactReferenceKey(file.relativePath))) {
       skipped++;
       continue;
     }
-    if (![".md", ".mdx"].includes(extname4(file.relativePath).toLowerCase())) {
+    if (![".md", ".mdx"].includes(extname5(file.relativePath).toLowerCase())) {
       skipped++;
       warnings.push({ code: "skipped-file", message: "Only Markdown and MDX are imported without an explicit converter.", source: file.relativePath });
       continue;
@@ -4802,6 +5596,8 @@ function migrateRepository(options) {
       page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, fernProjectRoot, (assetPath) => {
         addAssetReference(assetPath, file.relativePath);
       });
+      page.body = stripFernBasePathFromLinks(page.body, fernBasePath);
+      page.body = stripFernBasePathFromLinks(page.body, fernVersionPath);
     }
     if (platform === "mintlify" || platform === "docusaurus" || platform === "fern") {
       page.body = replaceLinkWithAnchor(page.body);
@@ -4882,7 +5678,7 @@ function migrateRepository(options) {
   const assetCandidates = [];
   for (const file of [...files, ...repositoryAssets]) {
     const firstSegment = file.relativePath.split("/", 1)[0].toLowerCase();
-    if (!ASSET_EXTENSIONS.has(extname4(file.relativePath).toLowerCase())) continue;
+    if (!ASSET_EXTENSIONS.has(extname5(file.relativePath).toLowerCase())) continue;
     if (platform !== "mintlify" && !ASSET_DIRECTORIES.has(firstSegment)) 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);
@@ -4938,10 +5734,19 @@ function migrateRepository(options) {
     const descriptorByNavigationId = new Map(
       docusaurusDescriptors.map((descriptor) => [descriptor.navigationId, descriptor])
     );
+    const sourceOrigin = docusaurusProjectRoot ? readDocusaurusSiteOrigin(docusaurusProjectRoot) : void 0;
+    const externalizedLinks = /* @__PURE__ */ new Set();
     for (const page of pages) {
       const descriptor = descriptorByNavigationId.get(page.navigationId);
-      if (descriptor) page.body = rewriteDocusaurusLinks(page.body, descriptor, docusaurusDescriptors);
+      if (descriptor) page.body = rewriteDocusaurusLinks(page.body, descriptor, docusaurusDescriptors, {
+        sourceOrigin,
+        onExternalLink: (target) => externalizedLinks.add(target)
+      });
     }
+    if (externalizedLinks.size > 0) warnings.push({
+      code: "unsupported-config",
+      message: `${externalizedLinks.size} link(s) outside the imported Docusaurus docs still point to ${sourceOrigin}; migrate those sections separately if this site must be fully independent.`
+    });
     if (docusaurusProjectRoot && !options.docusaurusSkipRedirects) {
       const redirects = readDocusaurusRedirects(docusaurusProjectRoot, warnings);
       if (redirects.length > 0) docsConfig = { ...docsConfig, redirects: [...docsConfig.redirects ?? [], ...redirects] };
@@ -4972,6 +5777,11 @@ function migrateRepository(options) {
       } : {}
     };
   }
+  if (platform === "fern" && fernSourceLinkAliases.size > 0) {
+    const imported = new Set(pages.map((page) => page.id));
+    const aliases = new Map([...fernSourceLinkAliases].map(([source, target]) => [source, fernIdRenames.get(target) ?? target]).filter(([, target]) => imported.has(target)));
+    for (const page of pages) page.body = rewriteFernIdRenameLinks(page.body, aliases);
+  }
   if (docsConfig.tabs.length === 0) docsConfig = buildNavigationFromPages(pages);
   if (platform === "fern" && fernProjectRoot) {
     const sections = fernApiSections.length > 0 ? fernApiSections : [{ nameExplicit: false }];
@@ -4981,7 +5791,7 @@ function migrateRepository(options) {
       const resolution = findFernConfiguredOpenApi(fernProjectRoot, repositoryDir, section.name, section.nameExplicit, warnings);
       const spec = resolution.spec ?? (!section.nameExplicit ? findOpenApi(files) : null);
       if (spec) {
-        let filename = basename2(spec.relativePath);
+        let filename = basename3(spec.relativePath);
         const existingSource = specFilenameSources.get(filename);
         if (existingSource && existingSource !== spec.absolutePath) {
           const prefix = section.name ? `${section.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "")}-` : `${specFilenameSources.size + 1}-`;
@@ -5032,7 +5842,7 @@ function migrateRepository(options) {
     } else {
       const fallback = findOpenApi(files);
       if (fallback) {
-        const filename = basename2(fallback.relativePath);
+        const filename = basename3(fallback.relativePath);
         if (!assets.some((asset) => asset.path === filename)) {
           assets.push({ path: filename, content: readFileSync5(fallback.absolutePath) });
         }
@@ -5045,9 +5855,25 @@ function migrateRepository(options) {
     const aliases = routeAliases.filter((redirect) => !sources.has(redirect.source));
     if (aliases.length > 0) docsConfig = { ...docsConfig, redirects: [...docsConfig.redirects ?? [], ...aliases] };
     docsConfig = addMintlifyHomepageRedirects(addMintlifyDirectoryRedirects(docsConfig, pages), pages);
+    const reachablePaths = /* @__PURE__ */ new Set([
+      ...pages.map((page) => page.id),
+      ...(docsConfig.redirects ?? []).map((redirect) => redirect.source.replace(/^\//, ""))
+    ]);
+    for (const page of pages) page.body = rewriteMintlifyMountedLinks(page.body, reachablePaths);
   }
   if (platform === "docusaurus" && docusaurusProjectRoot && !options.docusaurusSkipPlugins) {
-    for (const plugin of additionalDocusaurusPluginRoots(repositoryDir, docusaurusProjectRoot, warnings)) {
+    const additionalRoots = [
+      ...additionalDocusaurusPluginRoots(repositoryDir, docusaurusProjectRoot, warnings).map((plugin) => ({
+        ...plugin,
+        label: plugin.routePrefix.split(/[-_/]/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ")
+      })),
+      ...docusaurusArchiveRoots(docusaurusProjectRoot, repositoryDir, warnings)
+    ];
+    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.` });
+        break;
+      }
       if (plugin.docsDir === configuredDocsDir) continue;
       const pluginBundle = migrateRepository({
         ...options,
@@ -5055,12 +5881,17 @@ function migrateRepository(options) {
         platform: "docusaurus",
         docusaurusRoutePrefix: plugin.routePrefix,
         docusaurusSkipPlugins: true,
-        docusaurusSkipSidebar: true,
+        docusaurusSkipSidebar: !plugin.sidebarPath,
+        docusaurusSidebarPath: plugin.sidebarPath,
         docusaurusSkipAssets: true,
         docusaurusSkipRedirects: true
       });
       for (const page of pluginBundle.pages) {
-        if (seenPageIds.has(page.id)) continue;
+        if (seenPageIds.has(page.id)) {
+          skipped++;
+          warnings.push({ code: "collision", message: `Docusaurus docs roots both map to ${page.id}; the first page was kept.`, source: page.source });
+          continue;
+        }
         seenPageIds.add(page.id);
         pages.push(page);
       }
@@ -5070,7 +5901,7 @@ function migrateRepository(options) {
         assetPaths.add(asset.path);
         assets.push(asset);
       }
-      const pluginLabel = plugin.routePrefix.split(/[-_/]/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+      const pluginLabel = plugin.label;
       docsConfig.tabs.push(...pluginBundle.docsConfig.tabs.map((tab, index) => ({
         ...tab,
         tab: index === 0 ? pluginLabel : `${pluginLabel}: ${tab.tab}`
@@ -5081,6 +5912,41 @@ function migrateRepository(options) {
     }
   }
   docsConfig = pruneMissingNavigationPages(docsConfig, new Set(pages.map((page) => page.navigationId)));
+  if (platform === "docusaurus") preserveDocusaurusLinkedAnchors(pages);
+  if (platform === "fern" && fernRawConfig) {
+    const sourceSiteUrl = fernSourceSiteUrl(fernRawConfig);
+    if (sourceSiteUrl) {
+      const externalized = /* @__PURE__ */ new Set();
+      const pageIds = new Set(pages.map((page) => page.id));
+      for (const page of pages) page.body = externalizeMissingFernLinks(page.body, pageIds, sourceSiteUrl, externalized);
+      if (externalized.size > 0) warnings.push({
+        code: "unsupported-config",
+        message: `${externalized.size} unresolved Fern link(s) still point to ${sourceSiteUrl}; import those sections separately for a fully independent site.`
+      });
+    }
+  }
+  if (docsConfig.redirects) {
+    docsConfig = {
+      ...docsConfig,
+      redirects: docsConfig.redirects.filter((redirect) => {
+        const literalRoute = (route) => route.startsWith("/") && !/[?:*#()[\]{}]/.test(route) ? route.replace(/\/+$/, "") || "/" : null;
+        const sourceRoute = literalRoute(redirect.source);
+        if (sourceRoute && sourceRoute === literalRoute(redirect.destination)) {
+          warnings.push({
+            code: "unsupported-config",
+            message: `Self-redirect from ${redirect.source} to ${redirect.destination} was omitted.`
+          });
+          return false;
+        }
+        if (!/[+?()[\]{}]/.test(redirect.source)) return true;
+        warnings.push({
+          code: "unsupported-config",
+          message: `Redirect from ${redirect.source} contains route-pattern syntax Next.js cannot express literally and was omitted.`
+        });
+        return false;
+      })
+    };
+  }
   if (pages.length === 0) {
     const reasons = warnings.map((warning) => warning.message);
     throw new Error(reasons.length ? `No importable Markdown or MDX pages were found in the repository. Warnings encountered during migration: