@thallylabs/migrate 0.2.7 → 0.2.9

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, isAbsolute as isAbsolute2, 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";
@@ -50,6 +54,8 @@ function parseFrontmatter(raw) {
 
 // src/mdx.ts
 import { compileSync } from "@mdx-js/mdx";
+import { nameToEmoji } from "gemoji";
+import remarkGfm from "remark-gfm";
 import remarkMdx from "remark-mdx";
 import remarkParse from "remark-parse";
 import { unified } from "unified";
@@ -125,7 +131,7 @@ function titleFromId(id) {
   if (value === "introduction") return "Introduction";
   return value.split(/[-_]/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
-var descriptionParser = unified().use(remarkParse).use(remarkMdx);
+var descriptionParser = unified().use(remarkParse).use(remarkGfm).use(remarkMdx);
 function firstParagraph(content) {
   function plainText(node) {
     if (node.type === "text" || node.type === "inlineCode") return node.value ?? "";
@@ -159,19 +165,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 +191,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 +267,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;
@@ -221,6 +288,20 @@ var SAFE_BUILTIN_ROOTS = /* @__PURE__ */ new Set([
   "BigInt",
   "Reflect"
 ]);
+function leadingPageHeading(body) {
+  try {
+    const root = descriptionParser.parse(body);
+    const first = root.children?.find((node) => node.type !== "mdxjsEsm" && node.type !== "html");
+    if (first?.type !== "heading" || first.depth !== 1) return void 0;
+    const text = (node) => node.type === "mdxTextExpression" || node.type === "mdxFlowExpression" ? "" : node.value ?? (node.children ?? []).map(text).join("");
+    const title = text(first).replace(/\s+/g, " ").trim();
+    const start = first.position?.start.offset;
+    const end = first.position?.end.offset;
+    return title && start !== void 0 && end !== void 0 ? { title, start, end } : void 0;
+  } catch {
+    return void 0;
+  }
+}
 function collectPatternNames(pattern, names) {
   switch (pattern.type) {
     case "Identifier":
@@ -418,7 +499,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 +617,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 +628,7 @@ function maskCode(body) {
       continue;
     }
     if (fenceMatch) {
-      codeFence = fenceMatch[1][0];
+      codeFence = fenceMatch[1];
       fenceBuffer = [line];
       continue;
     }
@@ -565,14 +650,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 +854,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);
-      }
-    }
-    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>`;
-  });
+  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*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 +964,72 @@ 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 = replaceOutsideCode(rewritten, (segment) => segment.replace(
+      /:([+\w-]+):/g,
+      (shortcode, name) => nameToEmoji[name] ?? shortcode
+    ));
+    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 +1039,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 +1047,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);
@@ -819,9 +1065,13 @@ function parseMarkdownPage(input) {
     ...input.locale ? { locale: input.locale } : {}
   };
   const identity = input.resolveIdentity?.(parsed.data, fallbackIdentity) ?? fallbackIdentity;
-  const body = normalizeMdx(parsed.content, input.platform).trim();
+  let body = normalizeMdx(parsed.content, input.platform).trim();
   const keywords = Array.isArray(parsed.data.keywords) ? parsed.data.keywords.filter((value) => typeof value === "string") : [];
-  const title = typeof parsed.data.title === "string" && parsed.data.title.trim() ? parsed.data.title.trim() : titleFromId(identity.navigationId);
+  const heading = leadingPageHeading(body);
+  const title = typeof parsed.data.title === "string" && parsed.data.title.trim() ? parsed.data.title.trim() : heading?.title ?? titleFromId(identity.navigationId);
+  if (heading && heading.title === title) {
+    body = `${body.slice(0, heading.start)}${body.slice(heading.end)}`.trim();
+  }
   const navTitle = typeof parsed.data.sidebarTitle === "string" && parsed.data.sidebarTitle.trim() ? parsed.data.sidebarTitle.trim() : typeof parsed.data.navTitle === "string" && parsed.data.navTitle.trim() ? parsed.data.navTitle.trim() : void 0;
   const badge = typeof parsed.data.tag === "string" && parsed.data.tag.trim() ? parsed.data.tag.trim() : typeof parsed.data.badge === "string" && parsed.data.badge.trim() ? parsed.data.badge.trim() : void 0;
   const sourceMode = typeof parsed.data.mode === "string" ? parsed.data.mode : void 0;
@@ -834,6 +1084,7 @@ function parseMarkdownPage(input) {
     title,
     navTitle,
     description,
+    ...input.platform === "docusaurus" || input.platform === "fern" ? { descriptionPlacement: "body" } : {},
     badge,
     keywords,
     mode,
@@ -919,6 +1170,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 +1792,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 +1806,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 +1872,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 +1920,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 +1943,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 +2093,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 +2170,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;
@@ -2404,6 +2795,7 @@ function projectMintlifyNavigation(config, options = {}) {
   }) : [];
   let tabs = [];
   let i18n;
+  const localizedNavigation = {};
   const projectionTrace = {};
   if (languages.length > 0) {
     const defaultLanguage = languages.find((entry) => entry.default === true) ?? languages[0];
@@ -2439,8 +2831,11 @@ function projectMintlifyNavigation(config, options = {}) {
       if (language === defaultLanguage) {
         tabs = languageTabs;
         for (const reference of references) defaultPageIds.add(reference.navigationId);
+      } else if (languageTabs.length > 0) {
+        localizedNavigation[locale] = languageTabs;
       }
     }
+    if (Object.keys(localizedNavigation).length > 0) i18n.navigation = localizedNavigation;
   } else {
     const context = { references, seenReferences, warnings, warningKeys, pathPrefix: options.pathPrefix };
     tabs = convertContainerToTabs(navigation, context, "Documentation", projectionTrace);
@@ -2598,11 +2993,18 @@ function isDocumentationExtension(filename) {
   return [".md", ".mdx", ".rst", ".txt"].includes(extname2(filename).toLowerCase());
 }
 function pruneMissingNavigationPages(config, availableIds) {
-  const pruneNodes = (nodes) => nodes.flatMap((node) => {
-    if (typeof node === "string") return availableIds.has(node) ? [node] : [];
-    const pages = pruneNodes(node.pages);
-    return pages.length > 0 ? [{ ...node, pages }] : [];
-  });
+  const pruneNodes = (nodes) => {
+    const seenSiblings = /* @__PURE__ */ new Set();
+    return nodes.flatMap((node) => {
+      if (typeof node === "string") {
+        if (!availableIds.has(node) || seenSiblings.has(node)) return [];
+        seenSiblings.add(node);
+        return [node];
+      }
+      const pages = pruneNodes(node.pages);
+      return pages.length > 0 ? [{ ...node, pages }] : [];
+    });
+  };
   const tabs = config.tabs.flatMap((tab) => {
     const hadPages = (tab.pages?.length ?? 0) > 0 || (tab.groups?.length ?? 0) > 0;
     const pages = tab.pages ? pruneNodes(tab.pages) : void 0;
@@ -2695,7 +3097,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 +3113,52 @@ 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}`);
+    return line.replace(/(\]\()([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(target)}`).replace(/(\bhref=")([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(target)}${suffix}`).replace(/^(\s{0,3}\[[^\]]+\]:\s*)(<[^>]+>|\S+)/, (_match, prefix, destination) => {
+      const bracketed = destination.startsWith("<") && destination.endsWith(">");
+      const target = bracketed ? destination.slice(1, -1) : destination;
+      const rewritten = rewriteTarget(target);
+      return `${prefix}${bracketed ? `<${rewritten}>` : rewritten}`;
+    });
   }).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.");
@@ -2892,6 +3320,14 @@ function configuredSidebarPath(repositoryRoot) {
     const path = resolveWithin(repositoryRoot, filename);
     if (!existsSync3(path)) continue;
     const source = readBoundedText(path);
+    for (const docs of source.matchAll(/\bdocs\s*:\s*/g)) {
+      const object = matchingObjectLiteral(source, (docs.index ?? 0) + docs[0].length);
+      const candidate2 = object && staticStringField(object, "sidebarPath")?.replace(/^\.\//, "");
+      if (candidate2) {
+        const resolved2 = resolveWithin(repositoryRoot, candidate2);
+        if (existsSync3(resolved2) && lstatSync3(resolved2).isFile()) return candidate2;
+      }
+    }
     const match = source.match(/\bsidebarPath\s*:\s*(?:require\.resolve\(\s*)?(['"])([^'"]+)\1/);
     if (!match) continue;
     const candidate = match[2].replace(/^\.\//, "");
@@ -2900,9 +3336,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);
@@ -3070,15 +3509,156 @@ function readDocusaurusThemeColor(repositoryRoot) {
   if (lightMode) colors.dark = lightMode;
   return Object.keys(colors).length > 0 ? colors : void 0;
 }
-function readDocusaurusBrandAssetPaths(repositoryRoot) {
+function propertyStart(source, name) {
+  const pattern = new RegExp(`(?:^|[,{\\n])\\s*["']?${name}["']?\\s*:\\s*`, "m");
+  const match = pattern.exec(source);
+  return match ? match.index + match[0].length : -1;
+}
+function staticStringBindings(source) {
+  const bindings = /* @__PURE__ */ new Map();
+  for (const match of source.matchAll(/\bconst\s+([A-Z][A-Z0-9_]*)\s*=\s*((?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'))/g)) {
+    try {
+      const value = JSON5.parse(match[2]);
+      if (typeof value === "string") bindings.set(match[1], value);
+    } catch {
+    }
+  }
+  return bindings;
+}
+function staticArrayField(source, name) {
+  const start = propertyStart(source, name);
+  return start < 0 ? null : matchingArrayLiteral(source, start);
+}
+function staticObjectEntries(array) {
+  if (!array) return [];
+  const entries = [];
+  let afterDelimiter = 1;
+  let quote = "";
+  let lineComment = false;
+  let blockComment = false;
+  for (let index = 1; index < array.length - 1; index++) {
+    const char = array[index];
+    const next = array[index + 1];
+    if (lineComment) {
+      if (char === "\n") lineComment = false;
+      continue;
+    }
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        index++;
+      }
+      continue;
+    }
+    if (quote) {
+      if (char === "\\") {
+        index++;
+        continue;
+      }
+      if (char === quote) quote = "";
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      lineComment = true;
+      index++;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      index++;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === ",") {
+      afterDelimiter = index + 1;
+      continue;
+    }
+    if (char !== "{") continue;
+    const literal = matchingObjectLiteral(array, index);
+    if (!literal) continue;
+    const lead = array.slice(afterDelimiter, index).replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, "").trim();
+    if (!lead) entries.push(literal);
+    index += literal.length - 1;
+  }
+  return entries;
+}
+function staticStringField(source, name, bindings) {
+  const start = propertyStart(source, name);
+  if (start < 0) return void 0;
+  const quoted = source.slice(start).match(/^("(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*')/);
+  if (!quoted) {
+    const binding = source.slice(start).match(/^([A-Z][A-Z0-9_]*)\b/)?.[1];
+    return binding ? bindings?.get(binding) : void 0;
+  }
+  try {
+    const parsed = JSON5.parse(quoted[1]);
+    return typeof parsed === "string" ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readDocusaurusSiteSettings(repositoryRoot) {
+  const empty = { docsRouteBasePath: "docs", navbarLinks: [], footerLinks: [] };
   const configPath = findDocusaurusConfigPath(repositoryRoot);
-  if (!configPath) return [];
-  const configSource = readBoundedText(configPath);
-  const favicon = configSource.match(/\bfavicon\s*:\s*(['"])([^'"]+)\1/)?.[2];
-  const logoBlock = configSource.match(/\blogo\s*:\s*\{([^}]*)\}/)?.[1];
-  const logo = logoBlock?.match(/\bsrc\s*:\s*(['"])([^'"]+)\1/)?.[2];
-  const logoDark = logoBlock?.match(/\bsrcDark\s*:\s*(['"])([^'"]+)\1/)?.[2];
-  return [favicon, logo, logoDark].filter((path) => typeof path === "string");
+  if (!configPath) return empty;
+  const source = readBoundedText(configPath);
+  const bindings = staticStringBindings(source);
+  const presets = staticArrayField(source, "presets");
+  const classicDocs = presets && [...presets.matchAll(/["']?docs["']?\s*:\s*/g)].map((match) => matchingObjectLiteral(presets, (match.index ?? 0) + match[0].length)).find((object) => Boolean(object));
+  const docsRouteBasePath = classicDocs && staticStringField(classicDocs, "routeBasePath") || "docs";
+  const themeStart = propertyStart(source, "themeConfig");
+  const theme = themeStart < 0 ? null : matchingObjectLiteral(source, themeStart);
+  const navbarStart = theme ? propertyStart(theme, "navbar") : -1;
+  const navbar = navbarStart < 0 ? null : matchingObjectLiteral(theme, navbarStart);
+  const logoStart = navbar ? propertyStart(navbar, "logo") : -1;
+  const logo = logoStart < 0 ? null : matchingObjectLiteral(navbar, logoStart);
+  const footerStart = theme ? propertyStart(theme, "footer") : -1;
+  const footer = footerStart < 0 ? null : matchingObjectLiteral(theme, footerStart);
+  const navbarLinks = navbar ? staticObjectEntries(staticArrayField(navbar, "items")).flatMap((item) => {
+    if (propertyStart(item, "items") >= 0 || propertyStart(item, "dropdownItemsAfter") >= 0) return [];
+    const docsPluginId = staticStringField(item, "docsPluginId", bindings);
+    const href = staticStringField(item, "to", bindings) ?? staticStringField(item, "href", bindings);
+    const docId = staticStringField(item, "docId", bindings);
+    const sidebarId = staticStringField(item, "sidebarId", bindings);
+    const label = staticStringField(item, "label", bindings) ?? staticStringField(item, "aria-label", bindings);
+    return label && (href || docId || sidebarId || docsPluginId) ? [{
+      label,
+      ...href ? { href } : {},
+      ...docId ? { docId } : {},
+      ...sidebarId ? { sidebarId } : {},
+      ...docsPluginId ? { docsPluginId } : {}
+    }] : [];
+  }) : [];
+  const footerLinks = footer ? staticObjectEntries(staticArrayField(footer, "links")).flatMap((column) => {
+    const heading = staticStringField(column, "title", bindings);
+    if (!heading) return [];
+    const items = staticObjectEntries(staticArrayField(column, "items")).flatMap((item) => {
+      const href = staticStringField(item, "to", bindings) ?? staticStringField(item, "href", bindings);
+      const label = staticStringField(item, "label", bindings);
+      return label && href ? [{ label, href }] : [];
+    });
+    return items.length > 0 ? [{ heading, items }] : [];
+  }) : [];
+  const copyright = footer && propertyStart(footer, "copyright") >= 0 ? staticStringField(footer, "copyright") ?? footer.slice(propertyStart(footer, "copyright")).match(/^`([^`]+)`/)?.[1]?.replace(/\$\{new Date\(\)\.getFullYear\(\)\}/g, "{year}") : void 0;
+  return {
+    name: staticStringField(source, "title"),
+    description: staticStringField(source, "tagline"),
+    docsRouteBasePath,
+    ...logo && staticStringField(logo, "src") ? {
+      logo: {
+        light: staticStringField(logo, "src"),
+        ...staticStringField(logo, "srcDark") ? { dark: staticStringField(logo, "srcDark") } : {},
+        showTitle: Boolean(navbar && staticStringField(navbar, "title"))
+      }
+    } : {},
+    ...staticStringField(source, "favicon") ? { favicon: staticStringField(source, "favicon") } : {},
+    navbarLinks,
+    footerLinks,
+    ...copyright ? { copyright } : {}
+  };
 }
 function autogeneratedItems(dirName, context) {
   const normalizedDir = dirName === "." ? "" : normalizeDocId(dirName);
@@ -3165,19 +3745,19 @@ function projectDocusaurusNavigation(input) {
   ]]];
   const tabs = sidebarEntries.flatMap(([sidebarId, value]) => {
     const converted = convertItems(value, context);
-    const loosePages = converted.filter((entry) => typeof entry === "string");
-    const groups = converted.filter((entry) => typeof entry !== "string");
-    if (loosePages.length > 0) groups.unshift({ group: "Overview", pages: loosePages });
-    if (groups.length === 0) return [];
+    if (converted.length === 0) return [];
     return [{
       tab: sidebarEntries.length === 1 ? "Documentation" : titleCase2(sidebarId),
-      groups
+      // Docusaurus categories are disclosures, including at the sidebar
+      // root. Keeping them as Thally root nodes preserves their collapsed
+      // state and the authored interleaving of documents and categories.
+      pages: converted
     }];
   });
   const unreferenced = input.descriptors.filter((page) => !context.referencedNavigationIds.has(page.navigationId)).sort(descriptorSort).map((page) => page.navigationId);
   if (unreferenced.length > 0) {
-    if (tabs.length === 0) tabs.push({ tab: "Documentation", groups: [] });
-    tabs[0].groups?.push({ group: "Additional", pages: unreferenced });
+    if (tabs.length === 0) tabs.push({ tab: "Documentation", pages: [] });
+    tabs[0].pages?.push({ group: "Additional", pages: unreferenced });
   }
   return {
     docsConfig: { tabs },
@@ -3188,10 +3768,37 @@ 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 { load } from "cheerio";
 import { parse as parseYaml3 } from "yaml";
 var MAX_CONFIG_BYTES2 = 2e6;
+function announcementMarkdown(message) {
+  const document = load(message);
+  document("script, style, iframe, object, embed, svg, math").remove();
+  const escapeText = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/([\\`*_\[\]{}()!])/g, "\\$1");
+  const links = /* @__PURE__ */ new Map();
+  document("a").each((index, element) => {
+    const marker = `THALLYANNOUNCEMENTLINK${index}TOKEN`;
+    const label = document(element).text().trim();
+    const rawHref = document(element).attr("href")?.trim() ?? "";
+    let href;
+    if (/^https?:\/\//i.test(rawHref)) {
+      try {
+        href = new URL(rawHref).toString();
+      } catch {
+      }
+    } else if (rawHref.startsWith("/") && !rawHref.startsWith("//") && !/[\\<>\s]/.test(rawHref)) {
+      href = rawHref;
+    }
+    const destination = href?.replace(/\(/g, "%28").replace(/\)/g, "%29");
+    links.set(marker, destination && label ? `[${escapeText(label)}](${destination})` : escapeText(label));
+    document(element).replaceWith(marker);
+  });
+  let text = escapeText(document("body").text());
+  for (const [marker, link] of links) text = text.replaceAll(marker, link);
+  return text.trim();
+}
 function objectValue3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
@@ -3243,8 +3850,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);
@@ -3257,28 +3865,99 @@ function uniqueNavigationId(base, context) {
   while (context.seenNavigationIds.has(`${base}-${index}`)) index++;
   return `${base}-${index}`;
 }
-function registerPageAt(rawPath, base, context) {
-  const relativePath = rawPath.trim().replace(/^\.\//, "");
-  const sourcePath = context.pathPrefix ? `${context.pathPrefix}/${relativePath}` : relativePath;
+function registerPageAt(rawPath, base, context, navTitle, hidden = false) {
+  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 });
+  const isHidden = hidden || context.hiddenInherited === true;
+  context.descriptors.push({ sourcePath, navigationId, ...navTitle ? { navTitle } : {}, ...isHidden ? { hidden: true } : {} });
   const kept = context.sourcePathToNavigationId.get(sourcePath);
-  if (kept) return kept;
+  if (kept) {
+    if (!isHidden) {
+      const owner = context.descriptors.find((descriptor) => descriptor.navigationId === kept);
+      if (owner) owner.hidden = false;
+    }
+    return kept;
+  }
   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 source = lstatSync4(path).size <= MAX_CONFIG_BYTES2 ? readFileSync4(path, "utf8") : "";
+        const frontmatter = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] ?? "";
+        const hidden = /^hidden:\s*true\s*$/m.test(frontmatter);
+        const registered = registerPageAt(relative4(context.fernRoot, path), route, { ...context, pathPrefix: "" }, void 0, hidden);
+        if (registered && !hidden && !context.hiddenInherited) 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, label, object.hidden === true) || 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.page === "string") {
+    const page = registerPage(object, parentSegments, context);
+    return object.hidden === true || context.hiddenInherited ? null : page;
+  }
+  if (typeof object.folder === "string") {
+    const folder = registerFolder(object, parentSegments, object.hidden === true ? { ...context, hiddenInherited: true } : context);
+    return object.hidden === true || context.hiddenInherited ? null : folder;
+  }
   if (typeof object.section === "string") {
     const label = object.section;
     const segment = segmentFor(object, label, context);
@@ -3287,14 +3966,16 @@ 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, label, object.hidden === true);
+      if (registered) pages.push(registered);
     }
     for (const child of contents) {
-      const converted = convertNode(child, segments, context);
+      const converted = convertNode(child, segments, object.hidden === true ? { ...context, hiddenInherited: true } : context);
       if (converted) pages.push(converted);
     }
     if (pages.length === 0) return null;
     if (!hasOwnPath && segment) addBareRouteRedirect(segments, pages, context);
+    if (object.hidden === true || context.hiddenInherited) return null;
     return {
       group: label,
       ...typeof object.icon === "string" ? { icon: object.icon } : {},
@@ -3319,8 +4000,7 @@ function convertNode(node, parentSegments, context) {
     return null;
   }
   if (typeof object.changelog === "string") {
-    warnOnce2(context, "fern-changelog", "Fern changelog sections are not supported and were omitted.");
-    return null;
+    return registerFolder({ folder: object.changelog, title: "Changelog", "skip-slug": true }, parentSegments, context);
   }
   return null;
 }
@@ -3364,6 +4044,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(
@@ -3392,6 +4073,43 @@ function buildTabsFromConfig(rawConfig, configDir, fernRoot, routePrefix, fallba
       for (let index = sectionsBefore; index < context.apiSections.length; index += 1) {
         context.apiSections[index].tabLabel ??= label;
       }
+      if (groups.length === 0 && typeof meta.href === "string" && /^https?:\/\//i.test(meta.href)) {
+        return [{ tab: label, href: meta.href }];
+      }
+      if (groups.length === 0 && typeof meta.changelog === "string") {
+        const changelog = registerFolder({ folder: meta.changelog, title: label, "skip-slug": true }, segments, context);
+        if (changelog) {
+          const indexRoute = segments.join("/");
+          const descriptors = new Map(context.descriptors.map((descriptor) => [descriptor.navigationId, descriptor]));
+          const visiblePages = changelog.pages.filter((page) => typeof page === "string").filter((page) => !descriptors.get(page)?.hidden);
+          const index = visiblePages.find((page) => {
+            const descriptor = descriptors.get(page);
+            if (!descriptor) return false;
+            const stem = basename2(descriptor.sourcePath, extname4(descriptor.sourcePath));
+            return page === indexRoute || stem === "overview" || stem === "index";
+          });
+          const entries = visiblePages.filter((page) => page !== index).sort((left, right) => {
+            const date = (page) => descriptors.get(page)?.sourcePath.match(/\d{4}-\d{2}-\d{2}/)?.[0] ?? "";
+            return date(right).localeCompare(date(left)) || left.localeCompare(right);
+          });
+          for (const entryId of entries) {
+            const descriptor = descriptors.get(entryId);
+            if (descriptor) descriptor.hidden = true;
+          }
+          changelog.pages = [index ?? indexRoute];
+          context.changelogIndexes.push({ route: indexRoute, entries });
+          const latest = index ?? firstLeafId(changelog.pages);
+          const bareRouteIndex = context.bareRouteRedirects.findIndex((redirect) => redirect.source === `/${indexRoute}`);
+          const indexDescriptor = index ? descriptors.get(index) : void 0;
+          const indexSource = indexDescriptor && lstatSync4(resolveWithinRoot(context.fernRoot, indexDescriptor.sourcePath, context.repositoryRoot)).size <= MAX_CONFIG_BYTES2 ? readFileSync4(resolveWithinRoot(context.fernRoot, indexDescriptor.sourcePath, context.repositoryRoot), "utf8") : "";
+          const indexFrontmatter = indexSource.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] ?? "";
+          const indexSlug = indexFrontmatter.match(/^slug:\s*["']?([^\s"']+)["']?\s*$/m)?.[1]?.replace(/^\/+|\/+$/g, "");
+          const hasBarePage = index === indexRoute || indexSlug === indexRoute;
+          if (bareRouteIndex >= 0 && hasBarePage) context.bareRouteRedirects.splice(bareRouteIndex, 1);
+          else if (latest && bareRouteIndex >= 0) context.bareRouteRedirects[bareRouteIndex].destination = `/${latest}`;
+          return [{ tab: label, groups: [changelog] }];
+        }
+      }
       if (groups.length === 0) return [];
       if (segments.length > 0) addBareRouteRedirect(segments, groups, context);
       return [{
@@ -3463,9 +4181,12 @@ function projectFernProducts(rawProducts, fernRoot, context) {
 }
 function projectFernNavigation(input) {
   const context = {
+    fernRoot: input.fernRoot,
+    repositoryRoot: input.repositoryRoot ?? input.fernRoot,
     descriptors: [],
     seenNavigationIds: /* @__PURE__ */ new Set(),
     apiSections: [],
+    changelogIndexes: [],
     warnings: [],
     warningKeys: /* @__PURE__ */ new Set(),
     bareRouteRedirects: [],
@@ -3488,6 +4209,9 @@ function projectFernNavigation(input) {
     const label = typeof link?.text === "string" ? link.text : typeof link?.label === "string" ? link.label : link?.type === "github" ? "GitHub" : void 0;
     return href && label ? [{ label, href, ...link?.type === "github" ? { type: "github" } : {} }] : [];
   }) : [];
+  const announcement = objectValue3(config.announcement);
+  const announcementMessage = typeof announcement?.message === "string" ? announcement.message.trim() : "";
+  const bannerContent = announcementMarkdown(announcementMessage);
   const redirects = Array.isArray(config.redirects) ? config.redirects.flatMap((value) => {
     const redirect = objectValue3(value);
     if (!redirect || typeof redirect.source !== "string" || typeof redirect.destination !== "string") return [];
@@ -3509,13 +4233,6 @@ function projectFernNavigation(input) {
       ...typeof redirect.permanent === "boolean" ? { permanent: redirect.permanent } : {}
     }];
   }) : [];
-  if (config.logo || config.favicon) {
-    warnOnce2(
-      context,
-      "fern-branding",
-      "Fern logo and favicon were not migrated; add them to public/brand/ (default-logo-light.svg, default-logo-dark.svg, default-favicon-light.svg, default-favicon-dark.svg)."
-    );
-  }
   const authoredSources = new Set(redirects.map((redirect) => redirect.source));
   const knownIds = new Set(context.descriptors.map((descriptor) => descriptor.navigationId));
   const keptNavigationId = (descriptor) => context.sourcePathToNavigationId.get(descriptor.sourcePath) ?? descriptor.navigationId;
@@ -3559,12 +4276,14 @@ function projectFernNavigation(input) {
   return {
     docsConfig: {
       tabs,
+      ...bannerContent ? { banner: { content: bannerContent, dismissible: true } } : {},
       ...navbarLinks.length > 0 ? { navbar: { links: navbarLinks } } : {},
       ...allRedirects.length > 0 ? { redirects: allRedirects } : {}
     },
     descriptors: context.descriptors,
     warnings: context.warnings,
-    apiSections: disambiguatedApiSections
+    apiSections: disambiguatedApiSections,
+    changelogIndexes: context.changelogIndexes
   };
 }
 
@@ -3618,7 +4337,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 +4384,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 +4403,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 +4437,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 +4469,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 +4495,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 +4516,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 +4788,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 +4824,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;
     }
@@ -4138,12 +4904,6 @@ function fernThemeColors(value) {
   if (lightMode) colors.dark = lightMode;
   return Object.keys(colors).length > 0 ? colors : void 0;
 }
-function mintlifyBrandAssetPaths(value) {
-  if (typeof value === "string") return [value];
-  if (!value || typeof value !== "object") return [];
-  const source = value;
-  return ["light", "dark"].map((key) => source[key]).filter((entry) => typeof entry === "string");
-}
 function normalizedReferenceKey(value) {
   return value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/").replace(/\.(?:mdx?|rst|txt)$/i, "").replace(/\/(?:index|readme)$/i, "").replace(/^(?:index|readme)$/i, "") || "introduction";
 }
@@ -4151,7 +4911,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 +4978,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 +5045,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 +5088,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 +5103,276 @@ 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) || ASSET_EXTENSIONS.has(extname5(path).toLowerCase())) 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 preserveLinkedAnchors(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;
+    let fragment;
+    try {
+      fragment = decodeURIComponent(target.slice(hash2 + 1));
+    } catch {
+      return;
+    }
+    if (!/^[\p{L}\p{N}_.:$-]{1,120}$/u.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 closeOpenCodeFence(body) {
+  let open = null;
+  for (const line of body.split(/\r?\n/)) {
+    const match = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (!match) continue;
+    const marker = match[1][0];
+    if (!open) {
+      open = { marker, length: match[1].length };
+    } else if (marker === open.marker && match[1].length >= open.length && !match[2].trim()) {
+      open = null;
+    }
+  }
+  return open ? `${body}
+
+${open.marker.repeat(open.length)}` : body;
+}
+function addDatedHeadingAliases(body, date) {
+  let open = null;
+  const existingIds = new Set([...body.matchAll(/<a\s+id=["']([^"']+)["']/g)].map((match) => match[1]));
+  return body.split(/\r?\n/).flatMap((line) => {
+    const fence = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (fence) {
+      const marker = fence[1][0];
+      if (!open) open = { marker, length: fence[1].length };
+      else if (marker === open.marker && fence[1].length >= open.length && !fence[2].trim()) open = null;
+      return [line];
+    }
+    if (open) return [line];
+    const heading = line.match(/^#{2,6}\s+(.+?)\s*#*\s*$/);
+    if (!heading) return [line];
+    const slug = heading[1].replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[`*_]/g, "").normalize("NFKD").toLowerCase().replace(/[^\p{L}\p{N}\s-]/gu, "").trim().replace(/\s+/g, "-");
+    const id = `${date}-${slug}`;
+    if (!slug || existingIds.has(id)) return [line];
+    existingIds.add(id);
+    return [`<a id="${id}" />`, "", 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 +5383,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,9 +5416,13 @@ 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 candidate = decodedPath.startsWith("/") ? resolveWithin(siteRoot, decodedPath.replace(/^\/+/, "")) : resolveWithinRoot(dirname4(currentFile), decodedPath, siteRoot);
+    const realRoot = realpathSync2(siteRoot);
+    const realCandidate = realpathSync2(candidate);
+    const realRelative = relative5(realRoot, realCandidate);
+    if (realRelative === ".." || realRelative.startsWith(`..${sep2}`) || isAbsolute2(realRelative)) return null;
     const siteRelative = relative5(siteRoot, candidate).replace(/\\/g, "/");
     resolveWithin(siteRoot, siteRelative);
     if (!existsSync5(candidate) || !lstatSync5(candidate).isFile()) return null;
@@ -4381,15 +5436,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 +5444,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 +5475,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 +5494,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 +5508,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 +5554,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 +5589,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 +5645,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 +5654,14 @@ function migrateRepository(options) {
   let docusaurusSidebars = null;
   let mintlifyConfig = null;
   let fernRawConfig = null;
+  let fernBasePath = "";
+  let fernVersionPath = "";
   let fernApiSections = [];
+  let fernChangelogIndexes = [];
+  const fernReferencedPaths = /* @__PURE__ */ new Set();
+  const fernSourceLinkAliases = /* @__PURE__ */ new Map();
+  const fernNavTitles = /* @__PURE__ */ new Map();
+  const fernHiddenIds = /* @__PURE__ */ new Set();
   if (platform === "mintlify") {
     try {
       const config = readMintlifyConfig(mintlifyProjectRoot ?? repositoryDir);
@@ -4609,11 +5690,28 @@ 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;
+        fernChangelogIndexes = projected.changelogIndexes;
         for (const [index, descriptor] of projected.descriptors.entries()) {
+          fernReferencedPaths.add(descriptor.sourcePath);
+          if (descriptor.navTitle && !fernNavTitles.has(descriptor.navigationId)) {
+            fernNavTitles.set(descriptor.navigationId, descriptor.navTitle);
+          }
+          if (descriptor.hidden) fernHiddenIds.add(descriptor.navigationId);
+          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 +5728,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 +5742,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 +5784,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;
@@ -4793,6 +5904,11 @@ function migrateRepository(options) {
       skipped++;
       continue;
     }
+    if (platform === "fern" && !page.navTitle) {
+      const navTitle = fernNavTitles.get(navigationId);
+      if (navTitle && navTitle !== page.title) page.navTitle = navTitle;
+    }
+    if (platform === "fern" && fernHiddenIds.has(navigationId)) page.hidden = true;
     if (platform === "mintlify" && mintlifyProjectRoot) {
       page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, mintlifyProjectRoot, (assetPath) => {
         addAssetReference(assetPath, file.relativePath);
@@ -4802,6 +5918,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 +6000,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 +6056,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 +6099,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 +6113,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 +6164,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 +6177,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,22 +6203,27 @@ 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);
       }
-      const assetPaths = new Set(assets.map((asset) => asset.path));
+      const assetPaths2 = new Set(assets.map((asset) => asset.path));
       for (const asset of pluginBundle.assets) {
-        if (assetPaths.has(asset.path)) continue;
-        assetPaths.add(asset.path);
+        if (assetPaths2.has(asset.path)) continue;
+        assetPaths2.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}`
@@ -5080,21 +6233,234 @@ function migrateRepository(options) {
       skipped += pluginBundle.stats.skipped;
     }
   }
+  if (platform === "docusaurus") {
+    const importedRoutes = new Set(pages.map((page) => page.navigationId));
+    docsConfig.tabs = docsConfig.tabs.map((tab) => {
+      if (tab.href) return tab;
+      const root = tab.tab.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-");
+      if (!root || !importedRoutes.has(root)) return tab;
+      return {
+        ...tab,
+        href: `/${root}`,
+        ...tab.pages ? { pages: tab.pages.map((node) => {
+          if (typeof node === "string") return node;
+          const index = node.pages.indexOf(root);
+          return index > 0 ? { ...node, pages: [root, ...node.pages.filter((page) => page !== root)] } : node;
+        }) } : {},
+        ...tab.groups ? { groups: tab.groups.map((group) => {
+          const index = group.pages.indexOf(root);
+          return index > 0 ? { ...group, pages: [root, ...group.pages.filter((page) => page !== root)] } : group;
+        }) } : {}
+      };
+    });
+  }
+  if (platform === "fern") {
+    const byId = new Map(pages.map((page) => [page.navigationId, page]));
+    for (const changelog of fernChangelogIndexes) {
+      let index = byId.get(changelog.route);
+      const entries = changelog.entries.map((id) => byId.get(fernIdRenames.get(id) ?? id)).filter((page) => Boolean(page)).slice(0, 10);
+      if (entries.length === 0) continue;
+      if (!index) {
+        index = {
+          id: changelog.route,
+          navigationId: changelog.route,
+          title: "Release Notes",
+          description: "Latest release notes and product updates.",
+          descriptionPlacement: "body",
+          keywords: [],
+          body: "",
+          source: entries[0].source
+        };
+        pages.push(index);
+        byId.set(index.navigationId, index);
+        docsConfig.redirects = docsConfig.redirects?.filter((redirect) => redirect.source !== `/${changelog.route}`);
+      }
+      if (index.body.trim()) continue;
+      index.description ||= "Latest release notes and product updates.";
+      index.body = entries.map((entry) => {
+        const date = entry.source.match(/\d{4}-\d{2}-\d{2}/)?.[0];
+        const escapeText = (value) => value.replace(/([\\{}<>\[\]*_`])/g, "\\$1");
+        const body = /^(?:import|export)\s.+(?:from\s|\{)/m.test(entry.body) ? escapeText(entry.description) : closeOpenCodeFence(date ? addDatedHeadingAliases(entry.body.trim(), date) : entry.body.trim()) || escapeText(entry.description);
+        const dateAnchor = date ? `<a id="${date}T00:00:00.000Z" />
+
+` : "";
+        return `${dateAnchor}## ${escapeText(entry.title)}
+
+${date ? `**${date}** \xB7 ` : ""}[Read release note](/${entry.id})
+
+${body}`;
+      }).join("\n\n---\n\n");
+    }
+  }
   docsConfig = pruneMissingNavigationPages(docsConfig, new Set(pages.map((page) => page.navigationId)));
+  preserveLinkedAnchors(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:
 ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown or MDX pages were found in the repository.");
   }
   const isTopLevelDocusaurus = platform === "docusaurus" && docusaurusProjectRoot && !options.docusaurusSkipRedirects;
-  const themeColors = mintlifyConfig ? mintlifyThemeColors(mintlifyConfig.colors) : fernRawConfig ? fernThemeColors(fernRawConfig.colors) : isTopLevelDocusaurus ? readDocusaurusThemeColor(docusaurusProjectRoot) : void 0;
-  const brandAssetPaths = mintlifyConfig ? [...mintlifyBrandAssetPaths(mintlifyConfig.logo), ...mintlifyBrandAssetPaths(mintlifyConfig.favicon)] : isTopLevelDocusaurus ? readDocusaurusBrandAssetPaths(docusaurusProjectRoot) : [];
-  if (brandAssetPaths.length > 0) {
-    warnings.push({
+  const docusaurusSettings = isTopLevelDocusaurus ? readDocusaurusSiteSettings(docusaurusProjectRoot) : void 0;
+  if (docusaurusSettings) {
+    const importedRoutes = new Set(pages.map((page) => page.navigationId));
+    const sourceOrigin = readDocusaurusSiteOrigin(docusaurusProjectRoot);
+    const externalized = /* @__PURE__ */ new Set();
+    const projectLink = (raw, sourceLiteral = false) => {
+      if (/^https?:\/\//i.test(raw)) return raw;
+      if (/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(raw) || raw.includes("\\")) return void 0;
+      const suffixAt = raw.search(/[?#]/);
+      const path = suffixAt < 0 ? raw : raw.slice(0, suffixAt);
+      const suffix = suffixAt < 0 ? "" : raw.slice(suffixAt);
+      const route = path.replace(/^\.?\//, "").replace(/\/+$/, "");
+      if (route === ".." || route.startsWith("../") || route.includes("/../")) return void 0;
+      const docsBase = docusaurusSettings.docsRouteBasePath.replace(/^\/+|\/+$/g, "");
+      const isOutsideDocs = sourceLiteral && docsBase && route !== docsBase && !route.startsWith(`${docsBase}/`);
+      if (isOutsideDocs && sourceOrigin) {
+        externalized.add(raw);
+        return new URL(raw, `${sourceOrigin}/`).toString();
+      }
+      const strippedDocsRoute = docsBase && route.startsWith(`${docsBase}/`) ? route.slice(docsBase.length + 1) : route;
+      const candidates = [route, strippedDocsRoute, ...route === docsBase ? ["introduction"] : []];
+      const imported = candidates.find((candidate) => importedRoutes.has(candidate));
+      if (imported) return `/${imported}${suffix}`;
+      if (sourceOrigin) {
+        externalized.add(raw);
+        return new URL(raw, `${sourceOrigin}/`).toString();
+      }
+      return path.startsWith("/") ? `${path}${suffix}` : `/${route}${suffix}`;
+    };
+    const firstNavigationPage = (nodes) => {
+      for (const node of nodes) {
+        if (typeof node === "string") return node;
+        const nested = firstNavigationPage(node.pages);
+        if (nested) return nested;
+      }
+      return void 0;
+    };
+    const navbarLinks = docusaurusSettings.navbarLinks.flatMap((link) => {
+      const docRoute = link.docId && !link.docsPluginId && docusaurusDescriptors.find((page) => page.docId === link.docId)?.navigationId;
+      const sidebar = link.sidebarId && docsConfig.tabs.find((tab) => tab.tab.toLowerCase() === link.sidebarId.toLowerCase());
+      const sidebarRoute = sidebar && firstNavigationPage(sidebar.pages ?? sidebar.groups ?? []);
+      const pluginRoot = link.docsPluginId && importedRoutes.has(link.docsPluginId) ? link.docsPluginId : void 0;
+      const rawHref = link.href ?? (docRoute ? `/${docRoute}` : void 0) ?? (pluginRoot ? `/${pluginRoot}` : void 0) ?? (sidebarRoute ? `/${sidebarRoute}` : void 0) ?? (link.docsPluginId ? `/${link.docsPluginId}` : void 0);
+      const href = rawHref && projectLink(rawHref, Boolean(link.href));
+      return href ? [{ label: link.label, href }] : [];
+    });
+    const footerLinks = docusaurusSettings.footerLinks?.flatMap((column) => {
+      const items = column.items.flatMap((item) => {
+        const href = projectLink(item.href, true);
+        return href ? [{ label: item.label, href }] : [];
+      });
+      return items.length > 0 ? [{ heading: column.heading, items }] : [];
+    });
+    docsConfig = {
+      ...docsConfig,
+      ...navbarLinks.length > 0 ? { navbar: { ...docsConfig.navbar, links: navbarLinks } } : {},
+      ...footerLinks?.length || docusaurusSettings.copyright ? {
+        footer: {
+          ...docsConfig.footer,
+          ...footerLinks?.length ? { links: footerLinks } : {},
+          ...docusaurusSettings.copyright ? { copyright: docusaurusSettings.copyright } : {}
+        }
+      } : {}
+    };
+    if (externalized.size > 0) warnings.push({
       code: "unsupported-config",
-      message: `The site's logo/favicon (${brandAssetPaths.join(", ")}) were copied into public/ but are not wired into the migrated site's branding, which Thally manages from the admin dashboard rather than a static config field; set them there after the site is deployed.`
+      message: `${externalized.size} site navigation/footer link(s) point outside the imported docs and were kept on ${sourceOrigin}.`
     });
   }
+  if (!docsConfig.navigation?.display && docsConfig.tabs.filter((tab) => !tab.hidden).length > 6) {
+    docsConfig = { ...docsConfig, navigation: { display: "dropdown" } };
+  }
+  const themeColors = mintlifyConfig ? mintlifyThemeColors(mintlifyConfig.colors) : fernRawConfig ? fernThemeColors(fernRawConfig.colors) : isTopLevelDocusaurus ? readDocusaurusThemeColor(docusaurusProjectRoot) : void 0;
+  const assetPaths = new Set(assets.map((asset) => asset.path));
+  const publicBrandPath = (value) => {
+    if (typeof value !== "string" || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(value)) return void 0;
+    const normalized = normalizeAssetPath(value);
+    return normalized && assetPaths.has(normalized) ? `/${normalized}` : void 0;
+  };
+  const brandVariants = (value) => {
+    if (typeof value === "string") return { light: value };
+    if (!value || typeof value !== "object") return {};
+    const source = value;
+    const light = source.light ?? source.src;
+    const dark = source.dark ?? source.srcDark;
+    return {
+      ...typeof light === "string" ? { light } : {},
+      ...typeof dark === "string" ? { dark } : {},
+      ...typeof source.showTitle === "boolean" ? { showTitle: source.showTitle } : {}
+    };
+  };
+  const sourceLogo = mintlifyConfig?.logo ?? fernRawConfig?.logo ?? docusaurusSettings?.logo;
+  const sourceFavicon = mintlifyConfig?.favicon ?? fernRawConfig?.favicon ?? docusaurusSettings?.favicon;
+  const logo = brandVariants(sourceLogo);
+  const favicon = brandVariants(sourceFavicon);
+  const logoLight = publicBrandPath(logo.light);
+  const logoDark = publicBrandPath(logo.dark);
+  const faviconLight = publicBrandPath(favicon.light);
+  const faviconDark = publicBrandPath(favicon.dark);
+  if (logoLight) docsConfig = {
+    ...docsConfig,
+    navbar: {
+      ...docsConfig.navbar,
+      logo: {
+        light: logoLight,
+        ...logoDark ? { dark: logoDark } : {},
+        showTitle: mintlifyConfig || fernRawConfig ? false : logo.showTitle !== false,
+        ...typeof fernRawConfig?.logo?.["right-text"] === "string" ? { rightText: String(fernRawConfig.logo["right-text"]).trim().slice(0, 40) } : {}
+      }
+    }
+  };
+  if (faviconLight) docsConfig = {
+    ...docsConfig,
+    favicon: { light: faviconLight, ...faviconDark ? { dark: faviconDark } : {} }
+  };
+  const missingBrand = [
+    ...[logo.light, logo.dark].filter((value) => typeof value === "string" && !publicBrandPath(value)),
+    ...[favicon.light, favicon.dark].filter((value) => typeof value === "string" && !publicBrandPath(value))
+  ];
+  if (missingBrand.length > 0) warnings.push({
+    code: "unsupported-config",
+    message: `Brand asset(s) were referenced but not imported: ${[...new Set(missingBrand)].join(", ")}. Add these files under public/ or update docs.json.`
+  });
+  if (fernRawConfig?.logo && !logoLight && !logo.light) warnings.push({
+    code: "unsupported-config",
+    message: "Fern supplied a logo through its global theme without a local asset; add a logo path to docs.json after import."
+  });
   return {
     sourceUrl: options.sourceUrl,
     sourceKind: "repository",
@@ -5114,6 +6480,12 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
         ...typeof fernRawConfig.title === "string" ? { name: fernRawConfig.title } : {},
         ...themeColors ? { colors: themeColors } : {}
       }
+    } : docusaurusSettings && (docusaurusSettings.name || docusaurusSettings.description || themeColors) ? {
+      site: {
+        ...docusaurusSettings.name ? { name: docusaurusSettings.name } : {},
+        ...docusaurusSettings.description ? { description: docusaurusSettings.description } : {},
+        ...themeColors ? { colors: themeColors } : {}
+      }
     } : themeColors ? {
       site: { colors: themeColors }
     } : {},
@@ -5132,6 +6504,7 @@ function renderPage(bundle, page) {
     `title: ${yamlString(page.title)}`,
     page.navTitle ? `navTitle: ${yamlString(page.navTitle)}` : null,
     `description: ${yamlString(page.description)}`,
+    page.descriptionPlacement === "body" ? "descriptionPlacement: body" : null,
     page.badge ? `badge: ${yamlString(page.badge)}` : null,
     page.keywords.length > 0 ? `keywords: [${page.keywords.map(yamlString).join(", ")}]` : null,
     page.mode ? `mode: ${yamlString(page.mode)}` : null,
@@ -5233,7 +6606,7 @@ function renderMigrationFiles(bundle, options = {}) {
 }
 
 // src/url.ts
-import { load } from "cheerio";
+import { load as load2 } from "cheerio";
 import remarkMdx3 from "remark-mdx";
 import remarkParse3 from "remark-parse";
 import TurndownService from "turndown";
@@ -5410,7 +6783,7 @@ function machineIndexScopePath(source, documents) {
     if (!document) continue;
     const references = [...headerLinks(document)];
     if (/html/i.test(document.contentType)) {
-      const $ = load(document.body);
+      const $ = load2(document.body);
       references.push(...$("link[href], a[href]").map((_index, element) => $(element).attr("href") ?? "").get().filter((href) => /\/(?:llms(?:-full)?\.txt|sitemap\.xml)(?:[?#]|$)/i.test(href)));
     }
     for (const reference of references) {
@@ -5521,7 +6894,7 @@ function jsonObjectAfterKey(value, key) {
   return null;
 }
 function embeddedMintlifyConfig(body) {
-  const $ = load(body);
+  const $ = load2(body);
   const flightPayloads = [];
   $("script").each((_index, element) => {
     const script = $(element).text();
@@ -5619,7 +6992,7 @@ function isSafePortableUrl(value) {
   }
 }
 function decodeHtmlAttribute(value) {
-  const document = load(`<i data-thally-value="${value.replace(/"/g, "&quot;")}"></i>`);
+  const document = load2(`<i data-thally-value="${value.replace(/"/g, "&quot;")}"></i>`);
   return document("i").attr("data-thally-value") ?? "";
 }
 function escapeMarkdownText(value, escapeTableSeparator = false) {
@@ -5668,7 +7041,7 @@ function replacePortableHtmlImages(value) {
     if (start < cursor) continue;
     const end = htmlOpeningTagEnd(value, start + match[0].length);
     if (end === null) continue;
-    const fragment = load(value.slice(start, end));
+    const fragment = load2(value.slice(start, end));
     const image = fragment("img").first();
     const source = image.attr("src");
     const destination = source && isSafePortableUrl(source) ? markdownLinkDestination(source) : null;
@@ -5693,7 +7066,7 @@ function replacePortableHtmlAnchors(value) {
     const closing = closingMatch.exec(value);
     if (!closing) continue;
     const end = closing.index + closing[0].length;
-    const fragment = load(value.slice(start, end));
+    const fragment = load2(value.slice(start, end));
     const anchor = fragment("a").first();
     const href = anchor.attr("href");
     const label = escapeMarkdownText(anchor.text().replace(/\s+/g, " ").trim());
@@ -6074,7 +7447,7 @@ function mergeEmbeddedOpenApi(fragments) {
   return new TextEncoder().encode(stringifyYaml(combined));
 }
 function htmlPage(document, id) {
-  const $ = load(document.body);
+  const $ = load2(document.body);
   const links = $('nav a[href], main a[href], article a[href], [role="main"] a[href]').map((_index, element) => $(element).attr("href") ?? "").get().filter(Boolean);
   const title = $("main h1, article h1, h1").first().text().trim() || $('meta[property="og:title"]').attr("content")?.trim() || $("title").text().split("|")[0].trim();
   const description = $('meta[name="description"]').attr("content")?.trim() || $('meta[property="og:description"]').attr("content")?.trim();
@@ -6118,7 +7491,7 @@ function htmlPage(document, id) {
       const element = node;
       const className = element.className;
       const tag = /admonition-(?:danger)/.test(className) ? "Error" : /admonition-(?:caution|warning)/.test(className) ? "Warning" : /admonition-info/.test(className) ? "Info" : "Note";
-      const fragment = load(element.outerHTML);
+      const fragment = load2(element.outerHTML);
       const clone = fragment(".theme-admonition").first();
       const title2 = clone.find('[class*="admonitionHeading"],.admonition-heading').first();
       const titleText = title2.text().trim();
@@ -6139,7 +7512,7 @@ ${titleText ? `**${titleText}**
     filter: (node) => node.nodeName === "DIV" && node.classList.contains("tabs-container"),
     replacement: (_content, node) => {
       const element = node;
-      const fragment = load(element.outerHTML);
+      const fragment = load2(element.outerHTML);
       const container = fragment(".tabs-container").first();
       const labels = container.children("ul.tabs").children("li").toArray().map((item) => fragment(item).text().trim() || "Tab");
       const panels = container.children('div[role="tabpanel"]').toArray();
@@ -6162,7 +7535,7 @@ ${tabs.join("\n\n")}
   turndown.addRule("gfm-table", {
     filter: "table",
     replacement: (_content, node) => {
-      const fragment = load(node.outerHTML);
+      const fragment = load2(node.outerHTML);
       const rows = fragment("tr").toArray().map((row) => fragment(row).children("th,td").toArray().map((cell) => escapeMarkdownText(
         fragment(cell).text().replace(/\s+/g, " ").trim(),
         true
@@ -6183,7 +7556,7 @@ ${normalized.slice(1).map((row) => `| ${row.join(" | ")} |`).join("\n")}
     filter: (node) => node.nodeName === "PRE",
     replacement: (_content, node) => {
       const element = node;
-      const fragment = load(element.outerHTML);
+      const fragment = load2(element.outerHTML);
       const tokenLines = fragment(".token-line").toArray();
       const code = (tokenLines.length > 0 ? tokenLines.map((line) => fragment(line).text()).join("\n") : fragment("pre").text()).replace(/\n$/, "");
       const language = fragment("code").attr("class")?.match(/(?:language-|lang-)([A-Za-z0-9_+-]+)/)?.[1] ?? "";
@@ -6216,7 +7589,7 @@ ${fence}
   };
 }
 function htmlNavigationLinks(document) {
-  const $ = load(document.body);
+  const $ = load2(document.body);
   return $('.nav-tabs a[href], nav a[href], aside a[href], [role="navigation"] a[href]').map((_index, element) => $(element).attr("href") ?? "").get().filter(Boolean);
 }
 function normalizedLinkLabel(value) {
@@ -6224,7 +7597,7 @@ function normalizedLinkLabel(value) {
 }
 function readDocusaurusSidebar(document) {
   if (!/html/i.test(document.contentType)) return null;
-  const $ = load(document.body);
+  const $ = load2(document.body);
   const sidebar = $("ul.theme-doc-sidebar-menu").first();
   if (sidebar.length === 0) return null;
   function readList(list) {
@@ -6260,7 +7633,7 @@ function docusaurusSidebarHrefs(snapshot) {
   return hrefs;
 }
 function deriveDocusaurusScope(source, document, submittedScopePath) {
-  const $ = load(document.body);
+  const $ = load2(document.body);
   const sidebar = readDocusaurusSidebar(document);
   const internalPaths = docusaurusSidebarHrefs(sidebar).flatMap((href) => {
     try {
@@ -6390,7 +7763,7 @@ function docusaurusNavigationFromSnapshots(snapshots, pages, scopePath) {
   return { tabs };
 }
 function htmlTopLevelNavigation(document, source, scopePath) {
-  const $ = load(document.body);
+  const $ = load2(document.body);
   const collectCandidates = (selector) => {
     const candidates2 = [];
     $(selector).each((_containerIndex, container) => {
@@ -6451,7 +7824,7 @@ function markdownLinks(body) {
   return [...body.matchAll(/\[[^\]]+\]\(([^)\s]+)(?:\s+['"][^'"]*['"])?\)/g)].map((match) => match[1]);
 }
 function sitemapLinks(body) {
-  const $ = load(body, { xmlMode: true });
+  const $ = load2(body, { xmlMode: true });
   return $("url > loc, sitemap > loc").map((_index, element) => $(element).text().trim()).get().filter(Boolean);
 }
 function robotsSitemaps(body) {
@@ -6490,7 +7863,7 @@ async function migrateUrl(options) {
   const platform = options.platform ?? detectUrlPlatform(scopedHtmlProbe ?? initial);
   let docusaurusHtmlProbe = platform === "docusaurus" ? scopedHtmlProbe : null;
   if (docusaurusHtmlProbe && !readDocusaurusSidebar(docusaurusHtmlProbe)) {
-    const $ = load(docusaurusHtmlProbe.body);
+    const $ = load2(docusaurusHtmlProbe.body);
     const docsHref = $("nav a[href]").toArray().map((element) => ({
       href: $(element).attr("href"),
       label: normalizedLinkLabel($(element).text())