@thallylabs/migrate 0.2.8 → 0.2.10

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   statSync
 } from "fs";
 import { createRequire } from "module";
-import { basename as basename3, dirname as dirname4, extname as extname5, 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";
 
@@ -53,7 +53,10 @@ function parseFrontmatter(raw) {
 }
 
 // src/mdx.ts
+import { posix } from "path";
 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";
@@ -129,7 +132,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 ?? "";
@@ -286,6 +289,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":
@@ -628,6 +645,66 @@ function replaceOutsideCode(body, transform) {
   const { masked, unmask } = maskCode(body);
   return unmask(transform(masked));
 }
+function rewriteFernRelativePageLinks(body, currentSourcePath, routesBySourcePath) {
+  const rewrite = (target) => {
+    if (!target || target.startsWith("/") || target.startsWith("#") || target.startsWith("?") || target.includes("\\") || /[\u0000-\u001f\u007f]/.test(target) || /^[A-Za-z][A-Za-z\d+.-]*:/.test(target)) return target;
+    const suffixAt = target.search(/[?#]/);
+    const pathname = suffixAt < 0 ? target : target.slice(0, suffixAt);
+    const suffix = suffixAt < 0 ? "" : target.slice(suffixAt);
+    if (!pathname || pathname.startsWith("//") || pathname.split("/").some((part) => /%2f|%5c/i.test(part))) return target;
+    const source = posix.normalize(posix.join(posix.dirname(currentSourcePath.replace(/\\/g, "/")), pathname));
+    const candidates = /\.mdx?$/i.test(source) ? [source] : [source, `${source}.mdx`, `${source}.md`, `${source}/index.mdx`, `${source}/index.md`];
+    const route = candidates.map((candidate) => routesBySourcePath.get(candidate)).find(Boolean);
+    return route ? `/${route.replace(/^\/+/, "")}${suffix}` : target;
+  };
+  return replaceOutsideCode(body, (text) => text.replace(
+    /(\]\()(<[^>\n]+>|[^\s)]+)(?=\s|\))/g,
+    (_match, opening, target) => `${opening}${target.startsWith("<") && target.endsWith(">") ? `<${rewrite(target.slice(1, -1))}>` : rewrite(target)}`
+  ).replace(
+    /(\b(?:href|to)\s*=\s*)(["'])([^"'\n]+)\2/g,
+    (_match, opening, quote, target) => `${opening}${quote}${rewrite(target)}${quote}`
+  ).replace(
+    /(\b(?:href|to)\s*=\s*\{\s*)(["'])([^"'\n]+)\2(?=\s*\})/g,
+    (_match, opening, quote, target) => `${opening}${quote}${rewrite(target)}${quote}`
+  ));
+}
+function normalizeFernFileTrees(body) {
+  return replaceOutsideCode(body, (whole) => whole.replace(
+    /<FileTree\s*>\s*\n([\s\S]*?)\n\s*<\/FileTree>/g,
+    (original, contents) => {
+      const lines = contents.split(/\r?\n/).filter((line) => line.trim());
+      if (!lines.length) return original;
+      const nodes = [];
+      for (const line of lines) {
+        const match = /^( *)(?:-|\*|\+)\s+(.+?)\s*$/.exec(line);
+        if (!match || match[1].length % 2 !== 0 || match[2].includes("\0")) return original;
+        nodes.push({ indent: match[1].length / 2, name: match[2], isFolder: match[2].endsWith("/") });
+      }
+      const output = ["<Tree>"];
+      const folders = [];
+      for (const node of nodes) {
+        while (folders.length > node.indent) {
+          output.push("</Folder>");
+          folders.pop();
+        }
+        if (node.indent > folders.length || node.indent > 0 && folders.length === 0) return original;
+        const name = `{${JSON.stringify(node.name)}}`;
+        if (node.isFolder) {
+          output.push(`<Folder name=${name} defaultOpen>`);
+          folders.push(node.indent);
+        } else {
+          output.push(`<File name=${name} />`);
+        }
+      }
+      while (folders.length) {
+        output.push("</Folder>");
+        folders.pop();
+      }
+      output.push("</Tree>");
+      return output.join("\n");
+    }
+  ));
+}
 function normalizeHtmlComments(body) {
   return replaceOutsideCode(body, (whole) => whole.replace(/<!--([\s\S]*?)-->/g, (_match, comment) => `{/*${comment}*/}`));
 }
@@ -997,8 +1074,12 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   const runMintlify = platform === "mintlify";
   const runDocusaurus = platform === "docusaurus";
   const sourceBody = runDocusaurus && unwrapMdxCodeBlocks ? unwrapDocusaurusMdxCodeBlocks(body) : body;
-  let rewritten = normalizeDocusaurusAdmonitions(normalizeExplicitHeadingIds(runFern ? normalizeFernCallouts(sourceBody) : sourceBody));
+  let rewritten = normalizeDocusaurusAdmonitions(normalizeExplicitHeadingIds(runFern ? normalizeFernFileTrees(normalizeFernCallouts(sourceBody)) : sourceBody));
   if (runDocusaurus) {
+    rewritten = replaceOutsideCode(rewritten, (segment) => segment.replace(
+      /:([+\w-]+):/g,
+      (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,
@@ -1045,9 +1126,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;
@@ -1060,6 +1145,7 @@ function parseMarkdownPage(input) {
     title,
     navTitle,
     description,
+    ...input.platform === "docusaurus" || input.platform === "fern" ? { descriptionPlacement: "body" } : {},
     badge,
     keywords,
     mode,
@@ -1468,9 +1554,14 @@ function implicitReactImports(source) {
   visit(source);
   const hooks = [...REACT_GLOBALS].filter((name) => references.has(name) && !bindings.has(name)).sort();
   const usesMintlifyComponents = references.has("MintlifyComponents") && !bindings.has("MintlifyComponents");
+  const implicitComponents = MINTLIFY_COMPONENT_MODULES.map(({ module, names }) => {
+    const needed = names.filter((name) => references.has(name) && !bindings.has(name));
+    return needed.length ? `import { ${needed.join(", ")} } from '${module}';` : "";
+  }).filter(Boolean);
   return [
     references.has("React") && !bindings.has("React") ? "import * as React from 'react';" : "",
     hooks.length ? `import { ${hooks.join(", ")} } from 'react';` : "",
+    ...implicitComponents,
     usesMintlifyComponents ? mintlifyComponentsShim() : ""
   ].filter(Boolean).join("\n");
 }
@@ -2217,7 +2308,7 @@ import { customComponents as ${name} } from ${JSON.stringify(registryPath)}
 
 // src/docusaurus.ts
 import { existsSync as existsSync3, lstatSync as lstatSync3, readFileSync as readFileSync3 } from "fs";
-import { extname as extname3, posix } from "path";
+import { extname as extname3, posix as posix2 } from "path";
 import JSON5 from "json5";
 import { parse as parseYaml2 } from "yaml";
 
@@ -2770,6 +2861,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];
@@ -2805,8 +2897,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);
@@ -2964,11 +3059,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;
@@ -3027,19 +3129,19 @@ function storageIdForRoute(routeId) {
 function titleCase2(value) {
   return stripNumberPrefix(value).replace(/sidebar$/i, "").split(/[-_]/).filter(Boolean).map((word) => ["api", "cli", "sdk", "ui"].includes(word.toLowerCase()) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
-function routeFromSlug(slug, fallback, sourceDirectory) {
-  if (slug === "/") return "introduction";
-  if (slug.startsWith("/")) return docusaurusRouteId(slug);
-  const fallbackDirectory = sourceDirectory ?? (fallback === "introduction" ? "" : posix.dirname(fallback));
-  const resolved = posix.normalize(posix.join(fallbackDirectory, slug));
+function routeFromSlug(slug2, fallback, sourceDirectory) {
+  if (slug2 === "/") return "introduction";
+  if (slug2.startsWith("/")) return docusaurusRouteId(slug2);
+  const fallbackDirectory = sourceDirectory ?? (fallback === "introduction" ? "" : posix2.dirname(fallback));
+  const resolved = posix2.normalize(posix2.join(fallbackDirectory, slug2));
   if (resolved === ".." || resolved.startsWith("../")) return null;
   return docusaurusRouteId(resolved);
 }
 function resolveDocusaurusPageIdentity(sourcePath, frontmatter, fallback) {
   const sourceDocId = normalizeDocId(sourcePath);
-  const sourceDirectory = posix.dirname(sourceDocId);
+  const sourceDirectory = posix2.dirname(sourceDocId);
   const configuredId = typeof frontmatter.id === "string" && frontmatter.id.trim() ? stripNumberPrefix(frontmatter.id.trim()) : null;
-  const docId = configuredId ? normalizeDocId(sourceDirectory === "." ? configuredId : posix.join(sourceDirectory, configuredId)) : sourceDocId;
+  const docId = configuredId ? normalizeDocId(sourceDirectory === "." ? configuredId : posix2.join(sourceDirectory, configuredId)) : sourceDocId;
   const defaultNavigationId = defaultDocusaurusRouteId(docId) ?? fallback.navigationId;
   const configuredSlug = typeof frontmatter.slug === "string" ? frontmatter.slug.trim() : "";
   const navigationId = configuredSlug ? routeFromSlug(
@@ -3061,6 +3163,105 @@ function resolveDocusaurusPageIdentity(sourcePath, frontmatter, fallback) {
 function sourceReferenceKey(value) {
   return value.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\.(?:mdx?)$/i, "").replace(/\/$/, "");
 }
+function sourceHeadings(body) {
+  const headings = [];
+  const lines = body.split("\n");
+  let fence = null;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (marker) {
+      if (!fence) fence = marker[1];
+      else if (marker[1][0] === fence[0] && marker[1].length >= fence.length && /^\s*$/.test(line.slice(marker[0].length))) fence = null;
+      continue;
+    }
+    if (fence) continue;
+    const heading = line.match(/^ {0,3}(#{2,6})\s+(.+?)\s*#*\s*$/);
+    if (!heading) continue;
+    const preceding = lines[index - 1]?.match(/^<a id="([\p{L}\p{N}_.:$-]{1,120})"><\/a>$/u);
+    const plainText = !/[<>{}\[\]`*_]/.test(heading[2]);
+    const generatedId = plainText ? heading[2].normalize("NFC").toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/(^-|-$)/g, "") : null;
+    headings.push({ index, level: heading[1].length, id: preceding?.[1] ?? generatedId });
+  }
+  return headings;
+}
+function addDocusaurusTranslatedHeadingAliases(pages) {
+  const byRoute = new Map(pages.map((page) => [page.navigationId, page]));
+  for (const page of pages) {
+    const locale = page.source.match(/(?:^|[/#])i18n\/([A-Za-z]{2,8}(?:-[A-Za-z0-9]{2,8})*)\/docusaurus-plugin-content-docs\//)?.[1];
+    if (!locale) continue;
+    const originalRoute = page.navigationId === locale ? "introduction" : page.navigationId.startsWith(`${locale}/`) ? page.navigationId.slice(locale.length + 1) : null;
+    if (!originalRoute) continue;
+    const original = byRoute.get(originalRoute);
+    if (!original) continue;
+    const originalHeadings = sourceHeadings(original.body);
+    const translatedHeadings = sourceHeadings(page.body);
+    if (!originalHeadings.length || originalHeadings.length !== translatedHeadings.length || originalHeadings.some((heading, index) => heading.level !== translatedHeadings[index].level)) continue;
+    const occupied = new Set(translatedHeadings.map((heading) => heading.id).filter((id) => !!id));
+    for (const match of page.body.matchAll(/<a\s+id="([^"]+)"/g)) occupied.add(match[1]);
+    const originalIdCounts = /* @__PURE__ */ new Map();
+    for (const heading of originalHeadings) {
+      if (heading.id) originalIdCounts.set(heading.id, (originalIdCounts.get(heading.id) ?? 0) + 1);
+    }
+    const aliases = /* @__PURE__ */ new Map();
+    for (let index = 0; index < originalHeadings.length; index++) {
+      const id = originalHeadings[index].id;
+      if (!id || occupied.has(id) || originalIdCounts.get(id) !== 1) continue;
+      aliases.set(translatedHeadings[index].index, id);
+      occupied.add(id);
+    }
+    if (aliases.size) page.body = page.body.split("\n").flatMap((line, index) => {
+      const alias = aliases.get(index);
+      return alias ? [`<a id="${alias}"></a>`, line] : [line];
+    }).join("\n");
+  }
+}
+function expandDocusaurusDocCardLists(pages, config, sourceRoutes) {
+  const pageByRoute = new Map(pages.map((page) => [page.navigationId, page]));
+  const containsRoute = (items, route) => items.some((item) => typeof item === "string" ? item === route : containsRoute(item.pages, route));
+  const findGroup = (items, route) => {
+    for (const item of items) {
+      if (typeof item === "string" || !containsRoute(item.pages, route)) continue;
+      return findGroup(item.pages, route) ?? item;
+    }
+    return void 0;
+  };
+  const firstRoute = (items) => {
+    for (const item of items) {
+      if (typeof item === "string") return item;
+      const candidate = firstRoute(item.pages);
+      if (candidate) return candidate;
+    }
+    return void 0;
+  };
+  for (const page of pages) {
+    if (!sourceRoutes.has(page.navigationId)) continue;
+    const group = config.tabs.map((tab) => findGroup([
+      ...tab.pages ?? [],
+      ...tab.groups ?? []
+    ], page.navigationId)).find(Boolean);
+    if (!group) {
+      page.body = page.body.replace(/<div data-thally-doc-card-list=""\s*\/>/g, "");
+      continue;
+    }
+    const cards = group.pages.flatMap((item) => {
+      if (typeof item === "string") {
+        if (item === page.navigationId) return [];
+        const target = pageByRoute.get(item);
+        return [{ title: target?.title ?? item.split("/").at(-1) ?? item, route: item }];
+      }
+      const slug2 = slugifySegment(item.group);
+      const routes = [...item.pages].flatMap((child) => typeof child === "string" ? [child] : []);
+      const route = routes.find((candidate) => candidate === slug2 || candidate.endsWith(`/${slug2}`)) ?? firstRoute(item.pages);
+      return route ? [{ title: item.group, route }] : [];
+    });
+    const markup = cards.length ? `<CardGroup>
+${cards.map(({ title, route }) => `  <Card title={${JSON.stringify(title)}} href={${JSON.stringify(`/${route === "introduction" ? "" : route}`)}} />`).join("\n")}
+</CardGroup>` : "";
+    page.body = page.body.replace(/<div data-thally-doc-card-list=""\s*\/>/g, markup);
+    if (markup && !page.body.includes(markup)) page.body = [page.body.trim(), markup].filter(Boolean).join("\n\n");
+  }
+}
 function rewriteDocusaurusLinks(body, current, descriptors, options = {}) {
   const routes = /* @__PURE__ */ new Map();
   for (const descriptor of descriptors) {
@@ -3071,18 +3272,30 @@ function rewriteDocusaurusLinks(body, current, descriptors, options = {}) {
     const sourceRoute = pageIdFromReference(sourceKey);
     if (sourceRoute) routes.set(sourceRoute, descriptor.navigationId);
   }
-  const currentDirectory = posix.dirname(sourceReferenceKey(current.sourcePath));
+  const currentDirectory = posix2.dirname(sourceReferenceKey(current.sourcePath));
+  function copiedAssetTarget(target) {
+    if (!target.startsWith("/") || target.startsWith("//") || target.includes("\\")) return null;
+    const suffixIndex = target.search(/[?#]/);
+    const path = suffixIndex >= 0 ? target.slice(0, suffixIndex) : target;
+    const suffix = suffixIndex >= 0 ? target.slice(suffixIndex) : "";
+    if (path.startsWith("/docs/") && options.assetPaths?.has(path.slice("/docs/".length))) {
+      return `/${path.slice("/docs/".length)}${suffix}`;
+    }
+    return options.assetPaths?.has(path.slice(1)) ? target : null;
+  }
   function rewriteTarget(target) {
     if (!target || target.startsWith("#") || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(target)) return target;
     const suffixIndex = target.search(/[?#]/);
     const path = suffixIndex >= 0 ? target.slice(0, suffixIndex) : target;
     const suffix = suffixIndex >= 0 ? target.slice(suffixIndex) : "";
+    const copiedAsset = copiedAssetTarget(target);
+    if (copiedAsset) return copiedAsset;
     const candidates = path.startsWith("/") ? [
       sourceReferenceKey(path),
       sourceReferenceKey(path).replace(/^docs\//, ""),
       sourceReferenceKey(path).replace(/^docs\/(?:next|current|latest)\//, "")
     ] : [
-      sourceReferenceKey(posix.normalize(posix.join(currentDirectory, path))),
+      sourceReferenceKey(posix2.normalize(posix2.join(currentDirectory, path))),
       sourceReferenceKey(path)
     ];
     const route = candidates.map((candidate) => routes.get(candidate)).find(Boolean);
@@ -3104,7 +3317,12 @@ function rewriteDocusaurusLinks(body, current, descriptors, options = {}) {
       return line;
     }
     if (codeFence) return line;
-    return line.replace(/(\]\()([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(target)}`).replace(/(\bhref=")([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(target)}${suffix}`);
+    return line.replace(/(\]\()([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(target)}`).replace(/(\bhref=")([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(target)}${suffix}`).replace(/(\bsrc=")([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${copiedAssetTarget(target) ?? target}${suffix}`).replace(/^(\s{0,3}\[[^\]]+\]:\s*)(<[^>]+>|\S+)/, (_match, prefix, destination) => {
+      const bracketed = destination.startsWith("<") && destination.endsWith(">");
+      const target = bracketed ? destination.slice(1, -1) : destination;
+      const rewritten = rewriteTarget(target);
+      return `${prefix}${bracketed ? `<${rewritten}>` : rewritten}`;
+    });
   }).join("\n");
 }
 function readDocusaurusSiteOrigin(repositoryRoot) {
@@ -3279,6 +3497,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(/^\.\//, "");
@@ -3369,7 +3595,7 @@ function readDocusaurusRedirects(repositoryRoot, warnings) {
 }
 function readCategoryMetadata(contentRoot, directory) {
   for (const filename of CATEGORY_FILENAMES) {
-    const path = resolveWithin(contentRoot, posix.join(directory, filename));
+    const path = resolveWithin(contentRoot, posix2.join(directory, filename));
     if (!existsSync3(path) || !lstatSync3(path).isFile()) continue;
     try {
       const raw = readBoundedText(path);
@@ -3414,7 +3640,7 @@ function generatedIndexPage(label, linkValue, context) {
   if (link.type !== "generated-index") return null;
   const fallback = `category/${slugifySegment(label)}`;
   const unprefixedNavigationId = typeof link.slug === "string" ? routeFromSlug(link.slug, fallback) ?? fallback : fallback;
-  const navigationId = context.routePrefix && unprefixedNavigationId !== context.routePrefix && !unprefixedNavigationId.startsWith(`${context.routePrefix}/`) ? posix.join(context.routePrefix, unprefixedNavigationId) : unprefixedNavigationId;
+  const navigationId = context.routePrefix && unprefixedNavigationId !== context.routePrefix && !unprefixedNavigationId.startsWith(`${context.routePrefix}/`) ? posix2.join(context.routePrefix, unprefixedNavigationId) : unprefixedNavigationId;
   if (!context.generatedIds.has(navigationId) && !context.descriptors.some((page) => page.navigationId === navigationId)) {
     const description = typeof link.description === "string" ? link.description : `Browse the ${label} documentation.`;
     context.generatedPages.push({
@@ -3460,15 +3686,162 @@ 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", defaultColorMode: "light", 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 colorModeStart = theme ? propertyStart(theme, "colorMode") : -1;
+  const colorMode = colorModeStart < 0 ? null : matchingObjectLiteral(theme, colorModeStart);
+  const configuredColorMode = colorMode ? staticStringField(colorMode, "defaultMode") : void 0;
+  const defaultColorMode = configuredColorMode === "dark" ? "dark" : "light";
+  const navbarStart = theme ? propertyStart(theme, "navbar") : -1;
+  const navbar = navbarStart < 0 ? null : matchingObjectLiteral(theme, navbarStart);
+  const logoStart = navbar ? propertyStart(navbar, "logo") : -1;
+  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"),
+    ...navbar && staticStringField(navbar, "title") ? { navbarTitle: staticStringField(navbar, "title") } : {},
+    defaultColorMode,
+    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);
@@ -3480,32 +3853,47 @@ function autogeneratedItems(dirName, context) {
   const childDirectories = /* @__PURE__ */ new Set();
   for (const descriptor of inDirectory) {
     const source = descriptor.sourcePath.replace(/\.(?:mdx?)$/i, "");
-    const relativePath = normalizedDir ? posix.relative(normalizedDir, source) : source;
+    const relativePath = normalizedDir ? posix2.relative(normalizedDir, source) : source;
     const segments = relativePath.split("/").filter(Boolean);
     if (segments.length <= 1) directPages.push(descriptor);
     else childDirectories.add(segments[0]);
   }
-  const items = directPages.sort(descriptorSort).map((descriptor) => {
-    context.referencedNavigationIds.add(descriptor.navigationId);
-    return descriptor.navigationId;
-  });
+  const pages = directPages.map((descriptor) => ({
+    // An index document is the category landing page in Docusaurus. Thally
+    // renders it as a child link, so put it before the category's other docs.
+    position: descriptor.sidebarPosition ?? (/(?:^|\/)(?:index|readme)\.mdx?$/i.test(descriptor.sourcePath) ? -1 : Number.MAX_SAFE_INTEGER),
+    sortKey: descriptor.sourcePath,
+    item: descriptor.navigationId
+  }));
   const groups = [...childDirectories].map((segment) => {
-    const directory = normalizedDir ? posix.join(normalizedDir, segment) : segment;
+    const directory = normalizedDir ? posix2.join(normalizedDir, segment) : segment;
     const metadata = readCategoryMetadata(context.contentRoot, directory);
-    const pages = autogeneratedItems(directory, context);
+    const pages2 = autogeneratedItems(directory, context);
+    if (pages2.length === 1 && typeof pages2[0] === "string" && !metadata.label && metadata.position === void 0 && !metadata.link) {
+      const onlyPage = context.descriptors.find((descriptor) => descriptor.navigationId === pages2[0]);
+      if (onlyPage && /(?:^|\/)(?:index|readme)\.mdx?$/i.test(onlyPage.sourcePath)) {
+        return {
+          position: onlyPage.sidebarPosition ?? Number.MAX_SAFE_INTEGER,
+          sortKey: segment,
+          item: pages2[0]
+        };
+      }
+    }
     const landing = generatedIndexPage(metadata.label ?? titleCase2(segment), metadata.link, context);
-    if (landing && !pages.includes(landing)) pages.unshift(landing);
+    if (landing && !pages2.includes(landing)) pages2.unshift(landing);
     return {
       position: metadata.position ?? Number.MAX_SAFE_INTEGER,
-      segment,
-      group: {
+      sortKey: segment,
+      item: {
         group: metadata.label ?? titleCase2(segment),
-        pages
+        pages: pages2
       }
     };
-  }).sort((left, right) => left.position - right.position || left.segment.localeCompare(right.segment, void 0, { numeric: true }));
-  items.push(...groups.map((entry) => entry.group));
-  return items;
+  });
+  return [...pages, ...groups].sort((left, right) => left.position - right.position || left.sortKey.localeCompare(right.sortKey, void 0, { numeric: true })).map(({ item }) => {
+    if (typeof item === "string") context.referencedNavigationIds.add(item);
+    return item;
+  });
 }
 function convertItems(value, context) {
   if (typeof value === "string") {
@@ -3555,19 +3943,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 },
@@ -3580,8 +3968,35 @@ function projectDocusaurusNavigation(input) {
 // src/fern.ts
 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;
 }
@@ -3648,7 +4063,7 @@ function uniqueNavigationId(base, context) {
   while (context.seenNavigationIds.has(`${base}-${index}`)) index++;
   return `${base}-${index}`;
 }
-function registerPageAt(rawPath, base, context) {
+function registerPageAt(rawPath, base, context, navTitle, hidden = false) {
   let sourcePath;
   try {
     const absolute = resolveWithinRoot(
@@ -3663,9 +4078,16 @@ function registerPageAt(rawPath, base, context) {
   }
   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;
 }
@@ -3702,8 +4124,11 @@ function registerFolder(object, parentSegments, context) {
         const stem = basename2(entry.name, extname4(entry.name));
         const pageSegment = stem.toLowerCase() === "index" ? null : fernBasicSlug(stem);
         const route = [...routeSegments, ...pageSegment ? [pageSegment] : []].join("/");
-        const registered = registerPageAt(relative4(context.fernRoot, path), route, { ...context, pathPrefix: "" });
-        if (registered) pages2.push(registered);
+        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;
@@ -3718,13 +4143,19 @@ function registerPage(object, parentSegments, context) {
   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) || null;
+  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.folder === "string") return registerFolder(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);
@@ -3733,15 +4164,16 @@ function convertNode(node, parentSegments, context) {
     const pages = [];
     const hasOwnPath = typeof object.path === "string" && object.path.trim().length > 0;
     if (hasOwnPath) {
-      const registered = 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 } : {},
@@ -3750,11 +4182,23 @@ function convertNode(node, parentSegments, context) {
     };
   }
   if (typeof object.link === "string") {
-    warnOnce2(
-      context,
-      "fern-link",
-      'Fern navigation "link" entries are external and cannot be nested inside a Thally group; add them to the navbar manually.'
-    );
+    const label = object.link.trim();
+    const rawHref = typeof object.href === "string" ? object.href.trim() : "";
+    let href;
+    if (/^https?:\/\//i.test(rawHref) && !/[\\\u0000-\u0020\u007f]/.test(rawHref)) {
+      try {
+        const url = new URL(rawHref);
+        if (["http:", "https:"].includes(url.protocol) && !url.username && !url.password) href = url.toString();
+      } catch {
+      }
+    }
+    if (label && href && object.hidden !== true && !context.hiddenInherited) {
+      if (!context.externalLinks.some((link) => link.label === label && link.href === href)) {
+        context.externalLinks.push({ label, href });
+      }
+    } else if (!href && object.hidden !== true && !context.hiddenInherited) {
+      warnOnce2(context, `fern-link-${rawHref}`, `Fern navigation link "${label}" has an unsafe or invalid external URL and was skipped.`);
+    }
     return null;
   }
   if (typeof object.api === "string") {
@@ -3766,8 +4210,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;
 }
@@ -3840,6 +4283,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 [{
@@ -3916,8 +4396,10 @@ function projectFernNavigation(input) {
     descriptors: [],
     seenNavigationIds: /* @__PURE__ */ new Set(),
     apiSections: [],
+    changelogIndexes: [],
     warnings: [],
     warningKeys: /* @__PURE__ */ new Set(),
+    externalLinks: [],
     bareRouteRedirects: [],
     segmentAliases: /* @__PURE__ */ new Map(),
     pathPrefix: "",
@@ -3938,6 +4420,14 @@ function projectFernNavigation(input) {
     const label = typeof link?.text === "string" ? link.text : typeof link?.label === "string" ? link.label : link?.type === "github" ? "GitHub" : void 0;
     return href && label ? [{ label, href, ...link?.type === "github" ? { type: "github" } : {} }] : [];
   }) : [];
+  for (const link of context.externalLinks) {
+    if (!navbarLinks.some((existing) => existing.label === link.label && existing.href === link.href)) {
+      navbarLinks.push(link);
+    }
+  }
+  const announcement = objectValue3(config.announcement);
+  const announcementMessage = typeof announcement?.message === "string" ? announcement.message.trim() : "";
+  const bannerContent = announcementMarkdown(announcementMessage);
   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 [];
@@ -3959,13 +4449,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;
@@ -4009,12 +4492,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
   };
 }
 
@@ -4635,12 +5120,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";
 }
@@ -4679,7 +5158,7 @@ function mintlifyTopLevelApiReferences(config) {
   }
   return references;
 }
-function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings) {
+function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
   if (!mintlifyConfig) return [];
   const references = [
     ...mintlifyTopLevelApiReferences(mintlifyConfig),
@@ -4699,13 +5178,19 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings) {
       });
       continue;
     }
-    if (/^https?:\/\//i.test(reference.value)) {
+    if (/^https:\/\//i.test(reference.value)) {
+      remoteSpecs.push({ url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {} });
       warnings.push({
         code: "unsupported-config",
-        message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} was not downloaded. Download it manually, add it to public/, and set its API source in docs.json to the local path.`
+        message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} requires a network download before this import is complete.`,
+        source: reference.value
       });
       continue;
     }
+    if (/^http:\/\//i.test(reference.value)) {
+      warnings.push({ code: "unsupported-config", message: `The OpenAPI spec "${reference.value}"${tabSuffix} uses insecure HTTP and was not imported.`, source: reference.value });
+      continue;
+    }
     const key = reference.value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/");
     const match = files.find((file) => file.relativePath === key);
     if (!match) {
@@ -4947,7 +5432,7 @@ function fernSourceSiteUrl(config) {
 function externalizeMissingFernLinks(body, pageIds, sourceSiteUrl, externalized) {
   const rewrite = (target) => {
     const path = target.split(/[?#]/, 1)[0].replace(/^\//, "").replace(/\/$/, "");
-    if (!path || pageIds.has(path)) return target;
+    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);
@@ -4983,15 +5468,20 @@ function rewriteMintlifyMountedLinks(body, pageIds) {
   };
   return replaceOutsideCode(body, (text) => text.replace(/(\]\()(\/[^\s)]+)(\))/g, (_match, before, target, after) => `${before}${rewrite(target)}${after}`).replace(/(\b(?:href|to)=(['"]))(\/[^'"\n]+)\2/g, (_match, before, quote, target) => `${before}${rewrite(target)}${quote}`));
 }
-function preserveDocusaurusLinkedAnchors(pages) {
+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;
-    const fragment = target.slice(hash2 + 1);
-    if (!/^[A-Za-z0-9_.:-]{1,120}$/.test(fragment)) 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;
@@ -5066,6 +5556,43 @@ function preserveDocusaurusLinkedAnchors(pages) {
     ]).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 slug2 = heading[1].replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[`*_]/g, "").normalize("NFKD").toLowerCase().replace(/[^\p{L}\p{N}\s-]/gu, "").trim().replace(/\s+/g, "-");
+    const id = `${date}-${slug2}`;
+    if (!slug2 || existingIds.has(id)) return [line];
+    existingIds.add(id);
+    return [`<a id="${id}" />`, "", line];
+  }).join("\n");
+}
 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, "/");
@@ -5113,7 +5640,11 @@ function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
   }
   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;
@@ -5348,8 +5879,11 @@ function migrateRepository(options) {
   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);
@@ -5384,8 +5918,13 @@ function migrateRepository(options) {
         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("/");
@@ -5440,6 +5979,7 @@ function migrateRepository(options) {
   }
   const pages = [];
   const assets = [];
+  const remoteApiSpecs = [];
   const referencedAssetPaths = /* @__PURE__ */ new Map();
   const addAssetReference = (assetPath, referencingPage) => {
     const referrers = referencedAssetPaths.get(assetPath);
@@ -5447,6 +5987,7 @@ function migrateRepository(options) {
     else referencedAssetPaths.set(assetPath, /* @__PURE__ */ new Set([referencingPage]));
   };
   const docusaurusDescriptors = [];
+  const docusaurusDocCardRoutes = /* @__PURE__ */ new Set();
   const seenPageIds = /* @__PURE__ */ new Set();
   const fernIdRenames = /* @__PURE__ */ new Map();
   let skipped = 0;
@@ -5541,6 +6082,10 @@ function migrateRepository(options) {
       }
       raw = escapeFernLiteralBraces(protectedMath.body);
     }
+    const hasDocusaurusDocCardList = platform === "docusaurus" && /<DocCardList\b[^>]*\/>/.test(raw);
+    if (hasDocusaurusDocCardList) {
+      raw = raw.replace(/<DocCardList\b[^>]*\/>/g, '<div data-thally-doc-card-list="" />');
+    }
     let docusaurusDescriptor;
     const page = parseMarkdownPage({
       id,
@@ -5574,9 +6119,9 @@ function migrateRepository(options) {
       // hierarchy (never just its own segment) and wins over a docs.yml slug.
       ...platform === "fern" ? {
         resolveIdentity: (frontmatter, fallback) => {
-          const slug = typeof frontmatter.slug === "string" ? frontmatter.slug.trim() : "";
-          if (!slug) return fallback;
-          const overridden = pageIdFromReference(slug, true);
+          const slug2 = typeof frontmatter.slug === "string" ? frontmatter.slug.trim() : "";
+          if (!slug2) return fallback;
+          const overridden = pageIdFromReference(slug2, true);
           if (!overridden) return fallback;
           fernIdRenames.set(fallback.navigationId, overridden);
           return { ...fallback, id: overridden, navigationId: overridden };
@@ -5587,6 +6132,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);
@@ -5596,6 +6146,9 @@ function migrateRepository(options) {
       page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, fernProjectRoot, (assetPath) => {
         addAssetReference(assetPath, file.relativePath);
       });
+      page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, repositoryDir, (assetPath) => {
+        addAssetReference(assetPath, file.relativePath);
+      });
       page.body = stripFernBasePathFromLinks(page.body, fernBasePath);
       page.body = stripFernBasePathFromLinks(page.body, fernVersionPath);
     }
@@ -5650,6 +6203,9 @@ function migrateRepository(options) {
     }
     seenPageIds.add(page.id);
     pages.push(page);
+    if (hasDocusaurusDocCardList) {
+      docusaurusDocCardRoutes.add(page.navigationId);
+    }
     if (platform === "mintlify") {
       const sourcePath = exactReferenceKey(file.relativePath);
       if (sourcePath !== page.id && /^[A-Za-z0-9_./-]+$/.test(sourcePath)) {
@@ -5667,6 +6223,43 @@ function migrateRepository(options) {
     }
   }
   const docusaurusAssetRoot = docusaurusProjectRoot ?? repositoryDir;
+  const fernBrandAssetPaths = /* @__PURE__ */ new Map();
+  const fernReferencedAssets = [];
+  if (platform === "fern" && fernProjectRoot) {
+    const seen = /* @__PURE__ */ new Set();
+    const addFernAsset = (candidate, source) => {
+      try {
+        const absolutePath = source ? resolveWithinRoot(fernProjectRoot, source.replace(/^\/+/, ""), repositoryDir) : resolveWithin(repositoryDir, candidate);
+        if (!existsSync5(absolutePath) || !lstatSync5(absolutePath).isFile()) return;
+        const realRoot = realpathSync2(repositoryDir);
+        const realPath = realpathSync2(absolutePath);
+        const confined = relative5(realRoot, realPath);
+        if (confined === ".." || confined.startsWith(`..${sep2}`) || isAbsolute2(confined)) return;
+        const withinFern = relative5(fernProjectRoot, absolutePath);
+        const assetRelative = withinFern !== ".." && !withinFern.startsWith(`..${sep2}`) && !isAbsolute2(withinFern) ? withinFern : relative5(repositoryDir, absolutePath);
+        const assetPath = normalizeAssetPath(assetRelative.replace(/\\/g, "/"));
+        if (!assetPath || !ASSET_EXTENSIONS.has(extname5(assetPath).toLowerCase())) return;
+        if (source) {
+          fernBrandAssetPaths.set(source, assetPath);
+          addAssetReference(assetPath, "fern/docs.yml");
+        }
+        if (seen.has(absolutePath)) return;
+        seen.add(absolutePath);
+        fernReferencedAssets.push({ absolutePath, relativePath: assetPath });
+      } catch {
+      }
+    };
+    for (const path of referencedAssetPaths.keys()) addFernAsset(path);
+    for (const value of [fernRawConfig?.logo, fernRawConfig?.favicon]) {
+      if (typeof value === "string") addFernAsset("", value);
+      else if (value && typeof value === "object" && !Array.isArray(value)) {
+        const variants = value;
+        for (const candidate of [variants.light, variants.dark, variants.src, variants.srcDark]) {
+          if (typeof candidate === "string") addFernAsset("", candidate);
+        }
+      }
+    }
+  }
   const repositoryAssets = platform === "docusaurus" && configuredDocsDir && !options.docusaurusSkipAssets ? ["static", "public"].flatMap((directory) => {
     const root = resolveWithin(docusaurusAssetRoot, directory);
     if (!existsSync5(root) || !lstatSync5(root).isDirectory()) return [];
@@ -5676,10 +6269,10 @@ function migrateRepository(options) {
     }));
   }) : [];
   const assetCandidates = [];
-  for (const file of [...files, ...repositoryAssets]) {
+  for (const file of [...files, ...repositoryAssets, ...fernReferencedAssets]) {
     const firstSegment = file.relativePath.split("/", 1)[0].toLowerCase();
     if (!ASSET_EXTENSIONS.has(extname5(file.relativePath).toLowerCase())) continue;
-    if (platform !== "mintlify" && !ASSET_DIRECTORIES.has(firstSegment)) continue;
+    if (platform !== "mintlify" && !ASSET_DIRECTORIES.has(firstSegment) && !(platform === "fern" && referencedAssetPaths.has(file.relativePath))) continue;
     const isDocusaurusStatic = platform === "docusaurus" && firstSegment === "static";
     const assetPath = normalizeAssetPath(firstSegment === "public" ? file.relativePath.slice("public/".length) : isDocusaurusStatic ? file.relativePath.slice("static/".length) : file.relativePath);
     if (!assetPath) continue;
@@ -5725,6 +6318,7 @@ function migrateRepository(options) {
       routePrefix: options.docusaurusRoutePrefix
     });
     docsConfig = projected.docsConfig;
+    expandDocusaurusDocCardLists(pages, docsConfig, docusaurusDocCardRoutes);
     warnings.push(...projected.warnings);
     for (const page of projected.generatedPages) {
       if (seenPageIds.has(page.id)) continue;
@@ -5740,7 +6334,8 @@ function migrateRepository(options) {
       const descriptor = descriptorByNavigationId.get(page.navigationId);
       if (descriptor) page.body = rewriteDocusaurusLinks(page.body, descriptor, docusaurusDescriptors, {
         sourceOrigin,
-        onExternalLink: (target) => externalizedLinks.add(target)
+        onExternalLink: (target) => externalizedLinks.add(target),
+        assetPaths: new Set(assets.map((asset) => asset.path))
       });
     }
     if (externalizedLinks.size > 0) warnings.push({
@@ -5831,7 +6426,7 @@ function migrateRepository(options) {
     }
     if (resolvedSpecs.length > 0) docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs);
   } else if (platform === "mintlify") {
-    const resolvedSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings);
+    const resolvedSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs);
     for (const spec of resolvedSpecs) {
       if (!assets.some((asset) => asset.path === spec.filename)) {
         assets.push({ path: spec.filename, content: spec.content });
@@ -5895,10 +6490,10 @@ function migrateRepository(options) {
         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.label;
@@ -5911,8 +6506,97 @@ function migrateRepository(options) {
       skipped += pluginBundle.stats.skipped;
     }
   }
+  if (platform === "docusaurus") {
+    const copiedAssets = new Set(assets.map((asset) => asset.path));
+    for (const page of pages) {
+      page.body = rewriteDocusaurusLinks(page.body, {
+        sourcePath: page.source ?? page.navigationId,
+        docId: page.navigationId,
+        navigationId: page.navigationId,
+        title: page.title
+      }, [], { assetPaths: copiedAssets });
+    }
+    const importedRoutes = new Set(pages.map((page) => page.navigationId));
+    docsConfig.tabs = docsConfig.tabs.map((tab) => {
+      if (tab.href) return tab;
+      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)));
-  if (platform === "docusaurus") preserveDocusaurusLinkedAnchors(pages);
+  if (platform === "docusaurus") addDocusaurusTranslatedHeadingAliases(pages);
+  if (platform === "fern" && fernProjectRoot) {
+    const sourcePath = (page) => {
+      const fragment = page.source.split("#", 2)[1];
+      if (!fragment) return null;
+      try {
+        return relative5(fernProjectRoot, resolveWithin(repositoryDir, decodeURIComponent(fragment))).replace(/\\/g, "/");
+      } catch {
+        return null;
+      }
+    };
+    const routes = /* @__PURE__ */ new Map();
+    for (const page of pages) {
+      const source = sourcePath(page);
+      if (source) routes.set(source, page.id);
+    }
+    for (const page of pages) {
+      const source = sourcePath(page);
+      if (source) page.body = rewriteFernRelativePageLinks(page.body, source, routes);
+    }
+  }
+  preserveLinkedAnchors(pages);
   if (platform === "fern" && fernRawConfig) {
     const sourceSiteUrl = fernSourceSiteUrl(fernRawConfig);
     if (sourceSiteUrl) {
@@ -5953,20 +6637,168 @@ function migrateRepository(options) {
 ${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 = fernBrandAssetPaths.get(value) ?? 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 (platform === "docusaurus" && docusaurusSettings?.navbarTitle && !logoLight) {
+    docsConfig = { ...docsConfig, navbar: { ...docsConfig.navbar, logo: null } };
+  }
+  if (mintlifyConfig) {
+    const appearance = mintlifyConfig.appearance && typeof mintlifyConfig.appearance === "object" ? mintlifyConfig.appearance : null;
+    const defaultMode = appearance?.default;
+    if (defaultMode === "light" || defaultMode === "dark" || defaultMode === "system") {
+      docsConfig = { ...docsConfig, appearance: { ...docsConfig.appearance, default: defaultMode } };
+    }
+    const background = mintlifyConfig.background && typeof mintlifyConfig.background === "object" ? mintlifyConfig.background : null;
+    if (background) {
+      const decoration = background.decoration;
+      const image = publicBrandPath(background.image);
+      const imageDark = publicBrandPath(background.imageDark);
+      docsConfig = {
+        ...docsConfig,
+        background: {
+          ...docsConfig.background,
+          ...decoration === "none" || decoration === "grid" || decoration === "gradient" ? { decoration } : {},
+          ...image ? { image } : {},
+          ...imageDark ? { imageDark } : {}
+        }
+      };
+    }
+  }
+  if (platform === "docusaurus") {
+    docsConfig = { ...docsConfig, appearance: { ...docsConfig.appearance, default: docusaurusSettings?.defaultColorMode ?? "light" } };
+  }
+  if (faviconLight) docsConfig = {
+    ...docsConfig,
+    favicon: { light: faviconLight, ...faviconDark ? { dark: faviconDark } : {} }
+  };
+  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",
     platform,
     pages,
     assets,
+    ...remoteApiSpecs.length > 0 ? { remoteApiSpecs } : {},
     ...componentMigrator ? { componentFiles: componentMigrator.files() } : {},
     docsConfig,
     ...mintlifyConfig ? {
@@ -5980,6 +6812,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.navbarTitle || docusaurusSettings.name ? { name: docusaurusSettings.navbarTitle ?? docusaurusSettings.name } : {},
+        ...docusaurusSettings.description ? { description: docusaurusSettings.description } : {},
+        ...themeColors ? { colors: themeColors } : {}
+      }
     } : themeColors ? {
       site: { colors: themeColors }
     } : {},
@@ -5998,6 +6836,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,
@@ -6099,7 +6938,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";
@@ -6247,10 +7086,10 @@ async function readResponseBody(response) {
   }
   return new TextDecoder().decode(body);
 }
-var defaultMigrationFetcher = async (url, request) => {
+var defaultMigrationFetcher = async (url, request2) => {
   const response = await fetch(url, {
     headers: {
-      Accept: request.accept,
+      Accept: request2.accept,
       "User-Agent": "Thally-Migrate/1.0 (+https://thally.io)"
     },
     redirect: "follow",
@@ -6276,7 +7115,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) {
@@ -6387,7 +7226,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();
@@ -6485,7 +7324,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) {
@@ -6534,7 +7373,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;
@@ -6559,7 +7398,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());
@@ -6940,7 +7779,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();
@@ -6984,7 +7823,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();
@@ -7005,7 +7844,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();
@@ -7028,7 +7867,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
@@ -7049,7 +7888,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] ?? "";
@@ -7082,7 +7921,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) {
@@ -7090,7 +7929,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) {
@@ -7126,7 +7965,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 {
@@ -7256,7 +8095,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) => {
@@ -7317,7 +8156,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) {
@@ -7356,7 +8195,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())
@@ -7665,6 +8504,202 @@ async function migrateUrl(options) {
     }
   };
 }
+
+// src/remote-api.ts
+import { createHash as createHash2 } from "crypto";
+import { lookup } from "dns/promises";
+import { request } from "https";
+import { isIP } from "net";
+import { parse as parseYaml6 } from "yaml";
+var MAX_SPEC_BYTES = 25e6;
+var MAX_REDIRECTS = 3;
+function isPublicAddress(address, family) {
+  if (family === 4) {
+    const parts = address.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)) return false;
+    const [a, b] = parts;
+    return !(a === 0 || a === 10 || a === 127 || a >= 224 || a === 100 && b >= 64 && b <= 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && (b === 0 || b === 168) || a === 198 && (b === 18 || b === 19) || a === 203 && b === 0 || a === 198 && b === 51);
+  }
+  return family === 6 && /^[23][0-9a-f]{0,3}:/i.test(address) && !/^2001:db8:/i.test(address);
+}
+function validatedSpecUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.username || url.password || isIP(url.hostname)) {
+    throw new Error("Remote OpenAPI references must use an HTTPS domain without credentials or an IP literal.");
+  }
+  url.hash = "";
+  return url;
+}
+async function getPinnedAddress(url) {
+  const addresses = await lookup(url.hostname, { all: true });
+  if (addresses.length === 0 || addresses.some((candidate) => !isPublicAddress(candidate.address, candidate.family))) {
+    throw new Error("The OpenAPI host did not resolve exclusively to public addresses.");
+  }
+  return addresses[0];
+}
+async function requestPinnedSpec(url) {
+  const pinned = await getPinnedAddress(url);
+  return new Promise((resolve3, reject) => {
+    const req = request(url, {
+      headers: { Accept: "application/json, application/yaml, text/yaml, */*", "User-Agent": "Thally-Migrate/1.0 (+https://thally.io)" },
+      signal: AbortSignal.timeout(3e4),
+      // Node's dual-stack connector asks lookup for `all: true`; that
+      // callback must receive address records, not a single address string.
+      lookup: (_hostname, options, callback) => {
+        if (typeof options === "object" && options.all) callback(null, [pinned]);
+        else callback(null, pinned.address, pinned.family);
+      }
+    }, (response) => {
+      const status = response.statusCode ?? 0;
+      if (status >= 300 && status < 400) {
+        response.resume();
+        resolve3({ status, location: response.headers.location, body: Buffer.alloc(0) });
+        return;
+      }
+      if (status < 200 || status >= 300) {
+        response.resume();
+        reject(new Error(`OpenAPI server returned ${status}.`));
+        return;
+      }
+      const statedBytes = Number(response.headers["content-length"] ?? 0);
+      if (statedBytes > MAX_SPEC_BYTES) {
+        response.destroy();
+        reject(new Error("Remote OpenAPI spec exceeds the 25 MB import limit."));
+        return;
+      }
+      const chunks = [];
+      let bytes = 0;
+      response.on("data", (chunk) => {
+        bytes += chunk.length;
+        if (bytes > MAX_SPEC_BYTES) {
+          response.destroy(new Error("Remote OpenAPI spec exceeds the 25 MB import limit."));
+          return;
+        }
+        chunks.push(chunk);
+      });
+      response.on("end", () => resolve3({ status, body: Buffer.concat(chunks) }));
+      response.on("error", reject);
+    });
+    req.on("error", reject);
+    req.end();
+  });
+}
+async function downloadSpec(value, fetcher) {
+  let url = validatedSpecUrl(value);
+  if (fetcher) {
+    const response = await fetcher(url, { accept: "application/json, application/yaml, text/yaml" });
+    validatedSpecUrl(response.finalUrl.toString());
+    const body = Buffer.from(response.body);
+    if (body.length > MAX_SPEC_BYTES) throw new Error("Remote OpenAPI spec exceeds the 25 MB import limit.");
+    return body;
+  }
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    const response = await requestPinnedSpec(url);
+    if (response.status >= 300 && response.status < 400) {
+      if (!response.location || hop === MAX_REDIRECTS) throw new Error("Remote OpenAPI spec redirected too many times.");
+      url = validatedSpecUrl(new URL(response.location, url).toString());
+      continue;
+    }
+    return response.body;
+  }
+  throw new Error("Remote OpenAPI spec redirected too many times.");
+}
+function parseOpenApi(content, extension) {
+  const text = content.toString("utf8");
+  const parsed = extension === "yaml" || !text.trimStart().startsWith("{") ? parseYaml6(text) : JSON.parse(text);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("OpenAPI spec is not an object.");
+  const document = parsed;
+  if (typeof document.openapi !== "string" || !/^3\./.test(document.openapi)) {
+    throw new Error("Remote specification is not OpenAPI 3.x.");
+  }
+  if (!document.paths || typeof document.paths !== "object" || Array.isArray(document.paths)) {
+    throw new Error("Remote OpenAPI spec has no paths object.");
+  }
+  const paths = Object.entries(document.paths);
+  if (paths.length > 5e3) throw new Error("Remote OpenAPI spec has too many paths to import.");
+  const operations = [];
+  for (const [path, value] of paths) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    for (const [method, raw] of Object.entries(value)) {
+      if (!/^(get|post|put|patch|delete|head|options|trace)$/i.test(method) || !raw || typeof raw !== "object" || Array.isArray(raw)) continue;
+      const operation = raw;
+      const tags = Array.isArray(operation.tags) ? operation.tags : [];
+      operations.push({
+        method: method.toLowerCase(),
+        path,
+        tag: typeof tags[0] === "string" ? tags[0] : "API Reference",
+        summary: typeof operation.summary === "string" ? operation.summary : String(operation.operationId ?? "")
+      });
+    }
+  }
+  return operations;
+}
+function slug(value) {
+  return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function operationTarget(operation) {
+  const path = operation.path.split("/").filter(Boolean).map((part) => part.replace(/[{}]/g, "").replace(/[^a-zA-Z0-9-]/g, "-").replace(/-+/g, "-").toLowerCase());
+  return `/api/default/${[...path, operation.method].join("/")}`;
+}
+async function hydrateRemoteApiSpecs(bundle, fetcher) {
+  if (!bundle.remoteApiSpecs?.length) return bundle;
+  const assets = [...bundle.assets];
+  const tabs = bundle.docsConfig.tabs.map((tab) => ({ ...tab }));
+  const redirects = [...bundle.docsConfig.redirects ?? []];
+  const warnings = [...bundle.warnings];
+  const authoredLinks = /* @__PURE__ */ new Set();
+  for (const page of bundle.pages) {
+    for (const match of page.body.matchAll(/\/[a-z0-9_/-]+/gi)) {
+      const segments = match[0].split("/").filter(Boolean);
+      if (segments.length < 3) continue;
+      const section = segments[0].toLowerCase();
+      if (section.includes("api") || section.includes("reference")) authoredLinks.add(match[0]);
+    }
+  }
+  for (const reference of bundle.remoteApiSpecs) {
+    for (let index = warnings.length - 1; index >= 0; index--) {
+      if (warnings[index].source === reference.url && warnings[index].message.includes("requires a network download")) warnings.splice(index, 1);
+    }
+    try {
+      const url = validatedSpecUrl(reference.url);
+      const extension = /\.ya?ml$/i.test(url.pathname) ? "yaml" : "json";
+      const body = await downloadSpec(reference.url, fetcher);
+      const operations = parseOpenApi(body, extension);
+      const filename = `openapi-${createHash2("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
+      assets.push({ path: filename, content: body });
+      const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
+      if (tab) tab.api = { source: `/${filename}` };
+      else tabs.push({ tab: reference.tabLabel ?? "API Reference", api: { source: `/${filename}` } });
+      const routes = /* @__PURE__ */ new Map();
+      for (const operation of operations) {
+        const key = `${slug(operation.tag)}/${slug(operation.summary)}`;
+        if (routes.has(key)) routes.set(key, null);
+        else routes.set(key, operationTarget(operation));
+      }
+      const existingSources = new Set(redirects.map((redirect) => redirect.source));
+      for (const source of authoredLinks) {
+        const parts = source.split("/").filter(Boolean);
+        const key = parts.slice(-2).join("/");
+        const destination = routes.get(key);
+        if (!destination || existingSources.has(source)) continue;
+        redirects.push({ source, destination, permanent: false });
+        existingSources.add(source);
+      }
+    } catch (error) {
+      warnings.push({
+        code: "fetch-failed",
+        source: reference.url,
+        message: `Remote OpenAPI spec could not be imported: ${error instanceof Error ? error.message : String(error)}`
+      });
+    }
+  }
+  return {
+    ...bundle,
+    assets,
+    docsConfig: { ...bundle.docsConfig, tabs, ...redirects.length > 0 ? { redirects } : {} },
+    warnings
+  };
+}
 export {
   addMintlifyDirectoryRedirects,
   buildNavigationFromPages,
@@ -7673,6 +8708,7 @@ export {
   detectRepositoryDocsDir,
   detectRepositoryPlatform,
   gitmodulePaths,
+  hydrateRemoteApiSpecs,
   mergeMigrationConfig,
   migrateRepository,
   migrateUrl,