@thallylabs/migrate 0.2.1 → 0.2.2

package/dist/index.js

@@ -2,7 +2,7 @@
 import { spawn } from "child_process";
 import {
   existsSync as existsSync3,
-  lstatSync as lstatSync2,
+  lstatSync as lstatSync3,
   readFileSync as readFileSync3,
   readdirSync
 } from "fs";
@@ -16,16 +16,29 @@ import { parse as parseYaml } from "yaml";
 
 // src/path.ts
 import { isAbsolute, relative, resolve, sep } from "path";
-var SAFE_SEGMENT = /[^a-z0-9._-]+/g;
-function slugifySegment(value) {
+var SAFE_SEGMENT = /[^a-z0-9._-]+/gi;
+function trimTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end--;
+  return value.slice(0, end);
+}
+function trimEdgeSlashes(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value.charCodeAt(start) === 47) start++;
+  while (end > start && value.charCodeAt(end - 1) === 47) end--;
+  return value.slice(start, end);
+}
+function slugifySegment(value, preserveCase = false) {
   let decoded = value;
   try {
     decoded = decodeURIComponent(value);
   } catch {
   }
-  return decoded.toLowerCase().replace(/\.(?:html?|mdx?)$/i, "").replace(SAFE_SEGMENT, "-").replace(/(^-|-$)/g, "");
+  const normalized = preserveCase ? decoded : decoded.toLowerCase();
+  return normalized.replace(/\.(?:html?|mdx?)$/i, "").replace(SAFE_SEGMENT, "-").replace(/(^-|-$)/g, "");
 }
-function pageIdFromReference(value) {
+function pageIdFromReference(value, preserveCase = false) {
   const withoutQuery = value.split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^\/+/, "");
   if (!withoutQuery || withoutQuery.includes("\0")) return null;
   const rawSegments = withoutQuery.split("/").filter(Boolean);
@@ -35,7 +48,7 @@ function pageIdFromReference(value) {
   if (!/^(?:index|readme)$/i.test(last)) {
     baseSegments[baseSegments.length - 1] = last;
   }
-  const segments = baseSegments.map(slugifySegment).filter(Boolean);
+  const segments = baseSegments.map((segment) => slugifySegment(segment, preserveCase)).filter(Boolean);
   return segments.join("/") || "introduction";
 }
 function resolveWithin(root, candidate) {
@@ -585,7 +598,7 @@ function normalizeMdx(body) {
   return normalizeDocusaurusAdmonitions(body).replace(/^import\s+(?:Tabs|TabItem|Link|DocCardList|TOCInline)\s+from\s+['"]@(?:theme|docusaurus)\/[^'"]+['"]\s*;?\s*$/gm, "").replace(/<TabItem\b([^>]*)>/g, (_match, attributes) => {
     const title = attributes.match(/\blabel=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean) ?? attributes.match(/\bvalue=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean) ?? "Tab";
     return `<Tab title="${title.replace(/"/g, "&quot;")}">`;
-  }).replace(/<\/TabItem>/g, "</Tab>").replace(/<Link\b([^>]*)\bto=(?:"([^"]*)"|'([^']*)')([^>]*)>/g, (_match, before, doubleQuoted, singleQuoted, after) => `<a${before}href="${doubleQuoted ?? singleQuoted}"${after}>`).replace(/<\/Link>/g, "</a>").replace(/<(?:DocCardList|TOCInline)\b[^>]*\/>/g, "").replace(/<!--([\s\S]*?)-->/g, (_match, content) => `{/*${content}*/}`).replace(/<Danger(\s[^>]*)?>/g, "<Error$1>").replace(/<\/Danger>/g, "</Error>").replace(/<Check(\s[^>]*)?>/g, "<Note$1>").replace(/<\/Check>/g, "</Note>").replace(/<Tree\.Folder/g, "<Folder").replace(/<\/Tree\.Folder>/g, "</Folder>").replace(/<Tree\.File/g, "<File").replace(/<\/Tree\.File>/g, "</File>");
+  }).replace(/<\/TabItem>/g, "</Tab>").replace(/<Link\b([^>]*)\bto=(?:"([^"]*)"|'([^']*)')([^>]*)>/g, (_match, before, doubleQuoted, singleQuoted, after) => `<a${before}href="${doubleQuoted ?? singleQuoted}"${after}>`).replace(/<\/Link>/g, "</a>").replace(/<(?:DocCardList|TOCInline)\b[^>]*\/>/g, "").replace(/<!--([\s\S]*?)-->/g, (_match, content) => `{/*${content}*/}`).replace(/<Danger(\s[^>]*)?>/g, "<Error$1>").replace(/<\/Danger>/g, "</Error>").replace(/<Warn(\s[^>]*)?>/g, "<Warning$1>").replace(/<\/Warn>/g, "</Warning>").replace(/<Check(\s[^>]*)?>/g, "<Note$1>").replace(/<\/Check>/g, "</Note>").replace(/<Tree\.Folder/g, "<Folder").replace(/<\/Tree\.Folder>/g, "</Folder>").replace(/<Tree\.File/g, "<File").replace(/<\/Tree\.File>/g, "</File>");
 }
 function parseMarkdownPage(input) {
   const parsed = parseFrontmatter(input.raw);
@@ -598,14 +611,23 @@ function parseMarkdownPage(input) {
   const body = normalizeMdx(parsed.content).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 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;
+  const mode = sourceMode === "frame" ? "wide" : ["default", "wide", "custom", "center", "home"].includes(sourceMode ?? "") ? sourceMode : void 0;
   const description = typeof parsed.data.description === "string" && parsed.data.description.trim() ? parsed.data.description.trim() : firstParagraph(body);
   return {
     id: identity.id,
     navigationId: identity.navigationId,
     locale: identity.locale,
     title,
+    navTitle,
     description,
+    badge,
     keywords,
+    mode,
+    hidden: parsed.data.hidden === true ? true : void 0,
+    noindex: parsed.data.noindex === true || parsed.data.noindex === "true" ? true : void 0,
     openapi: typeof parsed.data.openapi === "string" ? parsed.data.openapi.trim() : void 0,
     body,
     source: input.source
@@ -613,8 +635,24 @@ function parseMarkdownPage(input) {
 }
 
 // src/navigation.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as readFileSync2, realpathSync } from "fs";
 import { dirname, extname as extname2, relative as relative2 } from "path";
+var MAX_MINTLIFY_CONFIG_BYTES = 2e6;
+function addMintlifyDirectoryRedirects(config, pages) {
+  const pageIds = new Set(pages.filter((page) => !page.locale).map((page) => page.navigationId));
+  const redirects = [...config.redirects ?? []];
+  const redirectSources = new Set(redirects.map((redirect) => redirect.source.replace(/\/$/, "") || "/"));
+  for (const page of pages) {
+    if (page.locale || !/(?:^|\/)(?:overview|introduction)$/.test(page.navigationId)) continue;
+    const parent = page.navigationId.replace(/\/(?:overview|introduction)$/, "");
+    if (!parent || pageIds.has(parent)) continue;
+    const source = `/${parent}`;
+    if (redirectSources.has(source)) continue;
+    redirects.push({ source, destination: `/${page.navigationId}`, permanent: false });
+    redirectSources.add(source);
+  }
+  return redirects.length > 0 ? { ...config, redirects } : config;
+}
 var LANGUAGE_LABELS = {
   ar: "Arabic",
   de: "German",
@@ -636,6 +674,15 @@ var LANGUAGE_LABELS = {
 function objectValue2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
+function projectedHref(value) {
+  if (typeof value !== "string") return void 0;
+  const href = value.trim();
+  if (!href || /[\u0000-\u001f\u007f]/.test(href)) return void 0;
+  if (/^(?:javascript|data|vbscript|file):/i.test(href)) return void 0;
+  const scheme = href.match(/^([a-z][a-z0-9+.-]*):/i)?.[1].toLowerCase();
+  if (scheme && !["http", "https", "mailto", "tel"].includes(scheme)) return void 0;
+  return href;
+}
 function labelFor(value, fallback) {
   for (const key of ["tab", "group", "anchor", "product", "dropdown", "version", "menu", "label", "name", "title"]) {
     if (typeof value[key] === "string" && value[key]) return String(value[key]);
@@ -649,11 +696,27 @@ function jsonPointer(root, pointer) {
   if (!pointer || pointer === "#") return root;
   const tokens = pointer.replace(/^#\/?/, "").split("/").filter(Boolean);
   return tokens.reduce((current, token) => {
+    if (Array.isArray(current)) {
+      const index = Number(token);
+      return Number.isSafeInteger(index) && index >= 0 ? current[index] : void 0;
+    }
     const object = objectValue2(current);
     if (!object) return void 0;
     return object[token.replace(/~1/g, "/").replace(/~0/g, "~")];
   }, root);
 }
+function readMintlifyJson(path, repositoryRoot) {
+  if (!existsSync2(path) || !lstatSync2(path).isFile()) {
+    throw new Error(`Mintlify config reference is not a regular file: ${relative2(repositoryRoot, path)}`);
+  }
+  const realPath = realpathSync(path);
+  const realRoot = realpathSync(repositoryRoot);
+  resolveWithin(realRoot, relative2(realRoot, realPath));
+  if (lstatSync2(realPath).size > MAX_MINTLIFY_CONFIG_BYTES) {
+    throw new Error(`Mintlify config reference exceeded ${MAX_MINTLIFY_CONFIG_BYTES / 1e6} MB: ${relative2(repositoryRoot, path)}`);
+  }
+  return JSON.parse(readFileSync2(realPath, "utf8"));
+}
 function resolveJsonReferences(value, currentFile, repositoryRoot, stack) {
   if (Array.isArray(value)) {
     return value.map((entry) => resolveJsonReferences(entry, currentFile, repositoryRoot, stack));
@@ -668,11 +731,17 @@ function resolveJsonReferences(value, currentFile, repositoryRoot, stack) {
     const stackKey = `${referencedFile}#${pointer}`;
     if (stack.has(stackKey)) throw new Error(`Circular Mintlify $ref: ${object.$ref}`);
     stack.add(stackKey);
-    const referencedRoot = JSON.parse(readFileSync2(referencedFile, "utf8"));
+    const referencedRoot = readMintlifyJson(referencedFile, repositoryRoot);
     const referenced = jsonPointer(referencedRoot, pointer ? `#${pointer}` : "");
     const resolved = resolveJsonReferences(referenced, referencedFile, repositoryRoot, stack);
     stack.delete(stackKey);
-    return resolved;
+    const siblings = Object.fromEntries(
+      Object.entries(object).filter(([key]) => key !== "$ref").map(([key, entry]) => [
+        key,
+        resolveJsonReferences(entry, currentFile, repositoryRoot, stack)
+      ])
+    );
+    return objectValue2(resolved) ? { ...resolved, ...siblings } : resolved;
   }
   return Object.fromEntries(
     Object.entries(object).map(([key, entry]) => [
@@ -684,18 +753,33 @@ function resolveJsonReferences(value, currentFile, repositoryRoot, stack) {
 function readMintlifyConfig(repositoryRoot) {
   const configPath = ["docs.json", "mint.json"].map((filename) => resolveWithin(repositoryRoot, filename)).find(existsSync2);
   if (!configPath) return null;
-  const raw = JSON.parse(readFileSync2(configPath, "utf8"));
+  const raw = readMintlifyJson(configPath, repositoryRoot);
   return resolveJsonReferences(raw, configPath, repositoryRoot, /* @__PURE__ */ new Set());
 }
-function normalizePageRef(value) {
+function normalizePageRef(value, pathPrefix = "") {
   if (/^(?:https?:)?\/\//i.test(value) || value.startsWith("#")) return null;
-  const ref = localReference(value).replace(/^\/+/, "").replace(/\.(?:mdx?|rst|txt)$/i, "");
-  return pageIdFromReference(ref);
+  let ref = localReference(value).split("?", 1)[0].replace(/^\/+/, "");
+  const prefix = trimEdgeSlashes(pathPrefix);
+  if (prefix && (ref === prefix || ref.startsWith(`${prefix}/`))) {
+    ref = ref === prefix ? "introduction" : ref.slice(prefix.length + 1);
+  }
+  ref = ref.replace(/\.(?:mdx?|rst|txt)$/i, "");
+  return pageIdFromReference(ref, true);
+}
+function warnOnce(context, key, message) {
+  if (context.warningKeys.has(key)) return;
+  context.warningKeys.add(key);
+  context.warnings.push({ code: "unsupported-config", message });
+}
+function iconName(value) {
+  if (typeof value === "string" && value) return value;
+  const icon = objectValue2(value);
+  return typeof icon?.name === "string" && icon.name ? icon.name : void 0;
 }
 function registerReference(value, context) {
   const localePrefix = context.locale ? `${context.locale}/` : "";
   const localizedValue = localePrefix && value.replace(/^\/+/, "").startsWith(localePrefix) ? value.replace(/^\/+/, "").slice(localePrefix.length) : value;
-  const navigationId = normalizePageRef(localizedValue);
+  const navigationId = normalizePageRef(localizedValue, context.pathPrefix);
   if (!navigationId) return null;
   const key = `${context.locale ?? ""}:${value}`;
   if (!context.seenReferences.has(key)) {
@@ -709,6 +793,17 @@ function convertPage(value, context) {
   const object = objectValue2(value);
   if (!object) return null;
   if (typeof object.page === "string") return registerReference(object.page, context);
+  const href = projectedHref(object.href);
+  if (href && !object.pages && !object.groups) {
+    const page = registerReference(href, context);
+    if (page) return page;
+    warnOnce(
+      context,
+      "external-page-link",
+      "External links nested inside a Mintlify sidebar cannot be represented as Thally pages and were omitted."
+    );
+    return null;
+  }
   const pages = Array.isArray(object.pages) ? object.pages : [];
   if ("group" in object || pages.length > 0) {
     const children = [];
@@ -723,7 +818,8 @@ function convertPage(value, context) {
     if (children.length === 0) return null;
     return {
       group: labelFor(object, "Documentation"),
-      ...typeof object.icon === "string" ? { icon: object.icon } : {},
+      ...iconName(object.icon) ? { icon: iconName(object.icon) } : {},
+      ...object.hidden === true ? { hidden: true } : {},
       pages: children
     };
   }
@@ -750,12 +846,20 @@ function convertContainerToTabs(containerValue, context, fallbackTab) {
       const object = objectValue2(value);
       if (!object) return [];
       const tab = labelFor(object, `${fallbackTab} ${index + 1}`);
-      if (typeof object.href === "string" && !object.pages && !object.groups) {
-        return [{ tab, href: object.href }];
+      const href = projectedHref(object.href);
+      if (href && !object.pages && !object.groups) {
+        return [{ tab, href, ...object.hidden === true ? { hidden: true } : {} }];
       }
       const nested = convertContainerToTabs(object, context, tab);
       if (nested.length > 0) {
-        if (nested.length === 1) return [{ ...nested[0], tab }];
+        if (nested.length === 1) {
+          return [{
+            ...nested[0],
+            tab,
+            ...href ? { href } : {},
+            ...object.hidden === true ? { hidden: true } : {}
+          }];
+        }
         return nested.map((item) => ({ ...item, tab: `${tab}: ${item.tab}` }));
       }
       return [];
@@ -768,38 +872,168 @@ function convertContainerToTabs(containerValue, context, fallbackTab) {
   ];
   if (typeof container.root === "string") rawPages.unshift(container.root);
   const groups = convertGroups(rawPages, context, "Overview");
-  return groups.length > 0 ? [{ tab: fallbackTab, groups }] : [];
+  return groups.length > 0 ? [{
+    tab: fallbackTab,
+    groups,
+    ...projectedHref(container.href) ? { href: projectedHref(container.href) } : {},
+    ...container.hidden === true ? { hidden: true } : {}
+  }] : [];
+}
+function projectedTheme(value) {
+  if (value === "maple") return "maple";
+  if (["aspen", "luma", "sequoia"].includes(String(value))) return "sharp";
+  if (["almond", "palm"].includes(String(value))) return "minimal";
+  return typeof value === "string" ? "default" : void 0;
+}
+function projectedNavbar(value) {
+  const navbar = objectValue2(value);
+  if (!navbar) return void 0;
+  const links = Array.isArray(navbar.links) ? navbar.links.flatMap((entry) => {
+    const link = objectValue2(entry);
+    const href = projectedHref(link?.href);
+    if (!link || !href) return [];
+    const label = typeof link.label === "string" ? link.label : typeof link.name === "string" ? link.name : "";
+    if (!label) return [];
+    return [{ label, href, ...link.type === "github" ? { type: "github" } : {} }];
+  }) : [];
+  const primaryValue = objectValue2(navbar.primary);
+  const primaryHref = projectedHref(primaryValue?.href);
+  const primary = primaryValue && primaryHref ? {
+    label: typeof primaryValue.label === "string" ? primaryValue.label : primaryValue.type === "github" ? "GitHub" : "Get started",
+    href: primaryHref
+  } : void 0;
+  return links.length > 0 || primary ? { ...links.length > 0 ? { links } : {}, ...primary ? { primary } : {} } : void 0;
+}
+function projectedGlobalNavigationLinks(value) {
+  const global = objectValue2(value);
+  if (!global) return [];
+  const links = [];
+  const visit = (entry) => {
+    if (Array.isArray(entry)) {
+      entry.forEach(visit);
+      return;
+    }
+    const item = objectValue2(entry);
+    if (!item) return;
+    const href = projectedHref(item.href);
+    if (href) {
+      const label = labelFor(item, "");
+      if (label) links.push({ label, href });
+    }
+    for (const key of ["tabs", "anchors", "dropdowns", "products", "versions", "languages", "menus"]) {
+      if (Array.isArray(item[key])) visit(item[key]);
+    }
+  };
+  visit(global);
+  return links;
+}
+function projectedFooter(value) {
+  const footer = objectValue2(value);
+  if (!footer) return void 0;
+  const socials = objectValue2(footer.socials);
+  const socialLinks = socials ? Object.fromEntries(Object.entries(socials).flatMap(([key, value2]) => {
+    const href = projectedHref(value2);
+    return href ? [[key, href]] : [];
+  })) : void 0;
+  const links = Array.isArray(footer.links) ? footer.links.flatMap((entry) => {
+    const column = objectValue2(entry);
+    if (!column || !Array.isArray(column.items)) return [];
+    const heading = typeof column.heading === "string" ? column.heading : typeof column.header === "string" ? column.header : "";
+    const items = column.items.flatMap((item) => {
+      const link = objectValue2(item);
+      const href = projectedHref(link?.href);
+      return link && typeof link.label === "string" && href ? [{ label: link.label, href }] : [];
+    });
+    return heading && items.length > 0 ? [{ heading, items }] : [];
+  }) : [];
+  return socialLinks && Object.keys(socialLinks).length > 0 || links.length > 0 ? { ...socialLinks && Object.keys(socialLinks).length > 0 ? { socials: socialLinks } : {}, ...links.length > 0 ? { links } : {} } : void 0;
+}
+function projectedFont(value) {
+  if (typeof value === "string" && value) return { family: value };
+  const font = objectValue2(value);
+  if (!font) return void 0;
+  const family = typeof font.family === "string" ? font.family : typeof font.name === "string" ? font.name : void 0;
+  if (!family) return void 0;
+  const weight = Array.isArray(font.weight) ? font.weight.map(String) : Array.isArray(font.weights) ? font.weights.map(String) : void 0;
+  return { family, ...weight && weight.length > 0 ? { weight } : {} };
+}
+function projectedCompatibleConfig(config) {
+  const banner = objectValue2(config.banner);
+  const bannerContent = banner && (typeof banner.content === "string" || objectValue2(banner.content)) ? banner.content : void 0;
+  const bannerType = banner && ["info", "warning", "critical"].includes(String(banner.type ?? banner.variant)) ? String(banner.type ?? banner.variant) : void 0;
+  const bannerColor = objectValue2(banner?.color);
+  const bodyFont = projectedFont(objectValue2(config.fonts)?.body ?? config.fonts);
+  const headingFont = projectedFont(objectValue2(config.fonts)?.heading);
+  const feedback = objectValue2(config.feedback);
+  const seo = objectValue2(config.seo);
+  const navbar = projectedNavbar(config.navbar);
+  const globalLinks = projectedGlobalNavigationLinks(objectValue2(config.navigation)?.global);
+  const navbarLinks = [...new Map(
+    [...navbar?.links ?? [], ...globalLinks].map((link) => [`${link.label}:${link.href}`, link])
+  ).values()];
+  const projectedNavigation = navbarLinks.length > 0 || navbar?.primary ? { ...navbarLinks.length > 0 ? { links: navbarLinks } : {}, ...navbar?.primary ? { primary: navbar.primary } : {} } : void 0;
+  return {
+    ...projectedTheme(config.theme) ? { theme: projectedTheme(config.theme) } : {},
+    ...bannerContent ? {
+      banner: {
+        content: bannerContent,
+        ...banner?.dismissible === false ? { dismissible: false } : {},
+        ...typeof banner?.id === "string" ? { id: banner.id } : {},
+        ...typeof banner?.revision === "string" ? { revision: banner.revision } : {},
+        ...bannerType ? { type: bannerType } : {},
+        ...bannerColor ? { color: {
+          ...typeof bannerColor.light === "string" ? { light: bannerColor.light } : {},
+          ...typeof bannerColor.dark === "string" ? { dark: bannerColor.dark } : {}
+        } } : {}
+      }
+    } : {},
+    ...projectedNavigation ? { navbar: projectedNavigation } : {},
+    ...projectedFooter(config.footer) ? { footer: projectedFooter(config.footer) } : {},
+    ...bodyFont || headingFont ? { fonts: { ...bodyFont ? { body: bodyFont } : {}, ...headingFont ? { heading: headingFont } : {} } } : {},
+    ...seo?.indexing === "all" ? { seo: { indexing: "all" } } : {},
+    ...typeof feedback?.thumbsRating === "boolean" ? { feedback: { thumbsRating: feedback.thumbsRating } } : {}
+  };
 }
-function projectMintlifyNavigation(config) {
+function projectMintlifyNavigation(config, options = {}) {
   const warnings = [];
   const references = [];
   const seenReferences = /* @__PURE__ */ new Set();
+  const warningKeys = /* @__PURE__ */ new Set();
   const navigation = objectValue2(config.navigation) ?? config;
   const languages = Array.isArray(navigation.languages) ? navigation.languages.map(objectValue2).filter((value) => Boolean(value)) : [];
   let tabs = [];
   let i18n;
   if (languages.length > 0) {
-    const defaultLanguage = languages.find((entry) => entry.language === "en") ?? languages[0];
+    const defaultLanguage = languages.find((entry) => entry.default === true) ?? languages[0];
     const defaultLocale = String(defaultLanguage.language ?? "en");
     const locales = languages.map((entry) => {
       const code = String(entry.language ?? entry.locale ?? "en");
-      return { code, label: LANGUAGE_LABELS[code] ?? code.toUpperCase() };
+      let label = LANGUAGE_LABELS[code];
+      try {
+        label ??= new Intl.DisplayNames(["en"], { type: "language" }).of(code) ?? void 0;
+      } catch {
+      }
+      return { code, label: label ?? code.toUpperCase() };
     });
     i18n = { defaultLocale, locales };
     for (const language of languages) {
       const locale = String(language.language ?? language.locale ?? defaultLocale);
       const context = {
         locale,
+        pathPrefix: options.pathPrefix,
         references,
-        seenReferences
+        seenReferences,
+        warnings,
+        warningKeys
       };
       const languageTabs = convertContainerToTabs(language, context, "Documentation");
       if (language === defaultLanguage) tabs = languageTabs;
     }
   } else {
-    tabs = convertContainerToTabs(navigation, { references, seenReferences }, "Documentation");
+    const context = { references, seenReferences, warnings, warningKeys, pathPrefix: options.pathPrefix };
+    tabs = convertContainerToTabs(navigation, context, "Documentation");
     if (tabs.length === 0 && Array.isArray(config.navigation)) {
-      const groups = convertGroups(config.navigation, { references, seenReferences }, "Overview");
+      const groups = convertGroups(config.navigation, context, "Overview");
       if (groups.length > 0) tabs = [{ tab: "Documentation", groups }];
     }
   }
@@ -809,20 +1043,25 @@ function projectMintlifyNavigation(config) {
       message: "Mintlify navigation could not be projected; generated navigation will be used."
     });
   }
-  if (!tabs.some((tab) => tab.tab.toLowerCase() === "changelog")) {
-    tabs.push({ tab: "Changelog", href: "/changelog" });
-  }
   const redirects = Array.isArray(config.redirects) ? config.redirects.flatMap((value) => {
     const redirect = objectValue2(value);
     if (!redirect || typeof redirect.source !== "string" || typeof redirect.destination !== "string") return [];
+    const source = redirect.source.trim();
+    const destination = redirect.destination.trim();
+    if (!source.startsWith("/") || !destination.startsWith("/") || source.startsWith("//") || destination.startsWith("//")) return [];
     return [{
-      source: redirect.source,
-      destination: redirect.destination,
+      source,
+      destination,
       ...typeof redirect.permanent === "boolean" ? { permanent: redirect.permanent } : {}
     }];
   }) : [];
   return {
-    docsConfig: { tabs, ...i18n ? { i18n } : {}, ...redirects.length > 0 ? { redirects } : {} },
+    docsConfig: {
+      tabs,
+      ...projectedCompatibleConfig(config),
+      ...i18n ? { i18n } : {},
+      ...redirects.length > 0 ? { redirects } : {}
+    },
     pageReferences: references,
     warnings
   };
@@ -991,12 +1230,50 @@ var DOCUSAURUS_CONFIG_FILENAMES = [
 function hasDocusaurusConfig(directory) {
   return DOCUSAURUS_CONFIG_FILENAMES.some((filename) => {
     const path = resolveWithin(directory, filename);
-    return existsSync3(path) && lstatSync2(path).isFile();
+    return existsSync3(path) && lstatSync3(path).isFile();
+  });
+}
+function hasMintlifyConfig(directory) {
+  return ["docs.json", "mint.json"].some((filename) => {
+    const path = resolveWithin(directory, filename);
+    if (!existsSync3(path) || !lstatSync3(path).isFile()) return false;
+    if (filename === "mint.json") return true;
+    try {
+      const config = JSON.parse(readFileSync3(path, "utf8"));
+      return String(config.$schema ?? "").includes("mintlify") || "navigation" in config;
+    } catch {
+      return false;
+    }
   });
 }
+function findMintlifyProjectRoot(repositoryDir, docsDir) {
+  if (docsDir !== void 0) {
+    let candidate = trimTrailingSlashes(docsDir);
+    while (true) {
+      const path = resolveWithin(repositoryDir, candidate || ".");
+      if (hasMintlifyConfig(path)) return path;
+      if (!candidate) break;
+      const parent = dirname2(candidate);
+      candidate = parent === "." ? "" : parent;
+    }
+  }
+  const queue = [{ directory: repositoryDir, depth: 0 }];
+  let visited = 0;
+  while (queue.length > 0 && visited < 500) {
+    const current = queue.shift();
+    visited++;
+    if (hasMintlifyConfig(current.directory)) return current.directory;
+    if (current.depth >= 4) continue;
+    for (const entry of readdirSync(current.directory, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.isSymbolicLink() || IGNORED_DIRECTORIES.has(entry.name)) continue;
+      queue.push({ directory: resolveWithin(current.directory, entry.name), depth: current.depth + 1 });
+    }
+  }
+  return null;
+}
 function findDocusaurusProjectRoot(repositoryDir, docsDir) {
   if (docsDir !== void 0) {
-    let candidate = docsDir.replace(/\/+$/, "");
+    let candidate = trimTrailingSlashes(docsDir);
     while (true) {
       const path = resolveWithin(repositoryDir, candidate || ".");
       if (hasDocusaurusConfig(path)) return path;
@@ -1023,14 +1300,14 @@ function findDocusaurusProjectRoot(repositoryDir, docsDir) {
   return null;
 }
 function readDocusaurusConfigSource(projectRoot) {
-  const path = DOCUSAURUS_CONFIG_FILENAMES.map((filename) => resolveWithin(projectRoot, filename)).find((candidate) => existsSync3(candidate) && lstatSync2(candidate).isFile());
-  if (!path || lstatSync2(path).size > 1e6) return "";
+  const path = DOCUSAURUS_CONFIG_FILENAMES.map((filename) => resolveWithin(projectRoot, filename)).find((candidate) => existsSync3(candidate) && lstatSync3(candidate).isFile());
+  if (!path || lstatSync3(path).size > 1e6) return "";
   return readFileSync3(path, "utf8");
 }
 function primaryDocusaurusDocsDirectory(projectRoot) {
   const source = readDocusaurusConfigSource(projectRoot);
   const configured = source.match(/\bdocs\s*:\s*\{[\s\S]{0,4000}?\bpath\s*:\s*(['"])([^'"]+)\1/)?.[2];
-  return configured?.replace(/^\.\//, "").replace(/\/+$/, "") || "docs";
+  return trimTrailingSlashes(configured?.replace(/^\.\//, "") ?? "") || "docs";
 }
 function additionalDocusaurusPluginRoots(repositoryDir, projectRoot) {
   const source = readDocusaurusConfigSource(projectRoot);
@@ -1038,12 +1315,12 @@ function additionalDocusaurusPluginRoots(repositoryDir, projectRoot) {
   const plugins = [];
   const matcher = /['"]@docusaurus\/plugin-content-docs['"][\s\S]{0,3000}?\bpath\s*:\s*(['"])([^'"]+)\1[\s\S]{0,1000}?\brouteBasePath\s*:\s*(['"])([^'"]+)\3/g;
   for (const match of source.matchAll(matcher)) {
-    const localPath = match[2].replace(/^\.\//, "").replace(/\/+$/, "");
-    const routePrefix = match[4].replace(/^\/+|\/+$/g, "");
+    const localPath = trimTrailingSlashes(match[2].replace(/^\.\//, ""));
+    const routePrefix = trimEdgeSlashes(match[4]);
     if (!localPath || !routePrefix) continue;
     const docsDir = [projectRelative, localPath].filter(Boolean).join("/");
     const absolute = resolveWithin(repositoryDir, docsDir);
-    if (!existsSync3(absolute) || !lstatSync2(absolute).isDirectory()) continue;
+    if (!existsSync3(absolute) || !lstatSync3(absolute).isDirectory()) continue;
     plugins.push({ docsDir, routePrefix });
   }
   return plugins;
@@ -1100,13 +1377,13 @@ async function cloneGitHubRepository(source, targetDir) {
     });
   });
 }
-function detectRepositoryPlatform(repositoryDir) {
-  if (existsSync3(resolveWithin(repositoryDir, "mint.json"))) return "mintlify";
-  const docsJson = resolveWithin(repositoryDir, "docs.json");
+function detectRepositoryPlatform(repositoryDir, docsDir) {
+  if (findMintlifyProjectRoot(repositoryDir, docsDir)) return "mintlify";
+  const selectedRoot = docsDir === void 0 ? repositoryDir : resolveWithin(repositoryDir, docsDir || ".");
+  const docsJson = resolveWithin(selectedRoot, "docs.json");
   if (existsSync3(docsJson)) {
     try {
       const config = JSON.parse(readFileSync3(docsJson, "utf8"));
-      if (String(config.$schema ?? "").includes("mintlify") || "navigation" in config) return "mintlify";
       if (Array.isArray(config.tabs)) return "thally";
     } catch {
     }
@@ -1132,7 +1409,7 @@ function containsMarkdown(directory, depth = 0) {
 function detectRepositoryDocsDir(repositoryDir) {
   for (const candidate of ["docs", "documentation", "content", "pages", "src/content", "src/pages", "guide", "guides", ""]) {
     const path = resolveWithin(repositoryDir, candidate);
-    if (existsSync3(path) && lstatSync2(path).isDirectory() && containsMarkdown(path)) return candidate;
+    if (existsSync3(path) && lstatSync3(path).isDirectory() && containsMarkdown(path)) return candidate;
   }
   return "";
 }
@@ -1154,30 +1431,135 @@ function scanFiles(root) {
 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";
 }
+function exactReferenceKey(value) {
+  return value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/").replace(/\.(?:mdx?|rst|txt)$/i, "");
+}
 function findOpenApi(files) {
   return files.find((file) => OPENAPI_FILENAMES.has(basename(file.relativePath).toLowerCase())) ?? null;
 }
+function findConfiguredMintlifyOpenApi(config, files) {
+  const api = config?.api && typeof config.api === "object" && !Array.isArray(config.api) ? config.api : null;
+  const configured = typeof api?.openapi === "string" ? [api.openapi] : Array.isArray(api?.openapi) ? api.openapi.filter((value) => typeof value === "string") : [];
+  for (const reference of configured) {
+    if (/^(?:https?:)?\/\//i.test(reference)) continue;
+    const key = reference.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/");
+    const match = files.find((file) => file.relativePath === key);
+    if (match) return match;
+  }
+  return null;
+}
 function withoutFrontmatter(value) {
   return value.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trim();
 }
-function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0, siteRoot = repositoryRoot) {
+function staticSnippetProperties(attributes) {
+  const properties = /* @__PURE__ */ new Map();
+  const matcher = /\b([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*"([^"]*)"\s*\}|\{\s*'([^']*)'\s*\})/g;
+  for (const match of attributes.matchAll(matcher)) {
+    properties.set(match[1], match[2] ?? match[3] ?? match[4] ?? match[5] ?? "");
+  }
+  return properties;
+}
+function interpolateSnippet(snippet, attributes) {
+  const properties = staticSnippetProperties(attributes);
+  if (properties.size === 0) return snippet;
+  let fence = "";
+  return snippet.split("\n").map((line) => {
+    const marker = line.match(/^\s*(`{3,}|~{3,})/)?.[1];
+    if (marker) {
+      if (!fence) fence = marker[0];
+      else if (marker[0] === fence) fence = "";
+      return line;
+    }
+    if (fence) return line;
+    return line.replace(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (original, name) => {
+      return properties.get(name) ?? original;
+    });
+  }).join("\n");
+}
+function resolveSnippetPath(sourcePath, currentFile, repositoryRoot, siteRoot) {
+  const repositoryRelative = sourcePath.startsWith("@site/") ? relative3(repositoryRoot, resolveWithin(siteRoot, sourcePath.slice("@site/".length))).replace(/\\/g, "/") : sourcePath.startsWith("/") ? relative3(repositoryRoot, resolveWithin(siteRoot, sourcePath.replace(/^\/+/, ""))).replace(/\\/g, "/") : relative3(repositoryRoot, resolvePath(dirname2(currentFile), sourcePath)).replace(/\\/g, "/");
+  const candidate = resolveWithin(repositoryRoot, repositoryRelative);
+  resolveWithin(repositoryRoot, relative3(repositoryRoot, candidate));
+  return candidate;
+}
+function globalSnippetAliases(files, repositoryRoot, siteRoot) {
+  const aliases = /* @__PURE__ */ new Map();
+  const matcher = /^import\s+(?:\{\s*default\s+as\s+)?([A-Z][A-Za-z0-9_]*)\s*\}?\s+from\s+['"]([^'"]+\.mdx?)['"]\s*;?(?:\s*\/\/.*)?$/gm;
+  for (const file of files) {
+    const segments = file.relativePath.split("/");
+    if (!segments.some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase()))) continue;
+    const basenameWithoutExtension = basename(file.relativePath).replace(/\.mdx?$/i, "");
+    const conventionalAlias = basenameWithoutExtension.split(/[^A-Za-z0-9]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+    if (conventionalAlias) aliases.set(conventionalAlias, file.absolutePath);
+  }
+  for (const file of files) {
+    if (![".md", ".mdx"].includes(extname3(file.relativePath).toLowerCase())) continue;
+    const raw = readFileSync3(file.absolutePath, "utf8");
+    for (const match of raw.matchAll(matcher)) {
+      try {
+        const candidate = resolveSnippetPath(match[2], file.absolutePath, repositoryRoot, siteRoot);
+        if (existsSync3(candidate) && lstatSync3(candidate).isFile()) {
+          aliases.set(match[1], candidate);
+        }
+      } catch {
+      }
+    }
+  }
+  return aliases;
+}
+function repositoryAssetHref(value, currentFile, siteRoot) {
+  const isBracketed = value.startsWith("<") && value.endsWith(">");
+  const raw = isBracketed ? value.slice(1, -1) : value;
+  if (!raw || raw.startsWith("#") || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(raw)) return null;
+  const suffixIndex = raw.search(/[?#]/);
+  const pathname = suffixIndex >= 0 ? raw.slice(0, suffixIndex) : raw;
+  const suffix = suffixIndex >= 0 ? raw.slice(suffixIndex) : "";
+  let decodedPath;
+  try {
+    decodedPath = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  if (!ASSET_EXTENSIONS.has(extname3(decodedPath).toLowerCase())) return null;
+  try {
+    const candidate = decodedPath.startsWith("/") ? resolveWithin(siteRoot, decodedPath.replace(/^\/+/, "")) : resolveWithin(dirname2(currentFile), decodedPath);
+    const siteRelative = relative3(siteRoot, candidate).replace(/\\/g, "/");
+    resolveWithin(siteRoot, siteRelative);
+    if (!existsSync3(candidate) || !lstatSync3(candidate).isFile()) return null;
+    const normalized = normalizeAssetPath(siteRelative);
+    if (!normalized) return null;
+    const rewritten = `/${normalized}${suffix}`;
+    return isBracketed ? `<${rewritten}>` : rewritten;
+  } catch {
+    return null;
+  }
+}
+function rewriteRepositoryAssetLinks(body, currentFile, siteRoot) {
+  return body.replace(/(!?\[[^\]]*\]\()(<[^>]+>|[^)\s]+)([^)]*\))/g, (original, opening, destination, closing) => {
+    const rewritten = repositoryAssetHref(destination, currentFile, siteRoot);
+    return rewritten ? `${opening}${rewritten}${closing}` : original;
+  }).replace(/\b(src|img|image|href)=(['"])([^'"]+)\2/g, (original, property, quote, destination) => {
+    const rewritten = repositoryAssetHref(destination, currentFile, siteRoot);
+    return rewritten ? `${property}=${quote}${rewritten}${quote}` : original;
+  });
+}
+function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0, siteRoot = repositoryRoot, globalAliases = /* @__PURE__ */ new Map()) {
   if (depth >= 8) return raw;
   const snippets = /* @__PURE__ */ new Map();
   const withoutImports = raw.replace(
     /^import\s+(?:\{\s*default\s+as\s+)?([A-Z][A-Za-z0-9_]*)\s*\}?\s+from\s+['"]([^'"]+\.mdx?)['"]\s*;?(?:\s*\/\/.*)?$/gm,
     (_statement, componentName, sourcePath) => {
       try {
-        const repositoryRelative = sourcePath.startsWith("@site/") ? relative3(repositoryRoot, resolveWithin(siteRoot, sourcePath.slice("@site/".length))).replace(/\\/g, "/") : sourcePath.startsWith("/") ? sourcePath.replace(/^\/+/, "") : relative3(repositoryRoot, resolvePath(dirname2(currentFile), sourcePath)).replace(/\\/g, "/");
-        const candidate = resolveWithin(repositoryRoot, repositoryRelative);
-        resolveWithin(repositoryRoot, relative3(repositoryRoot, candidate));
-        if (!existsSync3(candidate) || !lstatSync2(candidate).isFile()) throw new Error("file not found");
+        const candidate = resolveSnippetPath(sourcePath, currentFile, repositoryRoot, siteRoot);
+        if (!existsSync3(candidate) || !lstatSync3(candidate).isFile()) throw new Error("file not found");
         const nested = inlineMdxSnippets(
           withoutFrontmatter(readFileSync3(candidate, "utf8")),
           candidate,
           repositoryRoot,
           warnings,
           depth + 1,
-          siteRoot
+          siteRoot,
+          globalAliases
         );
         snippets.set(componentName, nested);
         return "";
@@ -1192,26 +1574,40 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
       }
     }
   );
+  for (const [componentName, candidate] of globalAliases) {
+    if (snippets.has(componentName) || !new RegExp(`<${componentName}(?:\\s|/?>)`).test(withoutImports)) continue;
+    const nested = inlineMdxSnippets(
+      withoutFrontmatter(readFileSync3(candidate, "utf8")),
+      candidate,
+      repositoryRoot,
+      warnings,
+      depth + 1,
+      siteRoot,
+      globalAliases
+    );
+    snippets.set(componentName, nested);
+  }
   let result = withoutImports;
   for (const [componentName, snippet] of snippets) {
-    result = result.replace(new RegExp(`<${componentName}(?:\\s[^>]*)?\\s*/>`, "g"), snippet).replace(new RegExp(`<${componentName}(?:\\s[^>]*)?>(?:[\\s\\S]*?)<\\/${componentName}>`, "g"), snippet);
+    result = result.replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)\\s*/>`, "g"), (_tag, attributes) => {
+      return interpolateSnippet(snippet, attributes);
+    }).replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)>(?:[\\s\\S]*?)<\\/${componentName}>`, "g"), (_tag, attributes) => {
+      return interpolateSnippet(snippet, attributes);
+    });
   }
   return result;
 }
 function injectOpenApi(config, filename) {
-  const tabs = config.tabs.filter((tab) => !tab.tab.toLowerCase().includes("api"));
-  const apiTab = {
-    tab: "API Reference",
-    api: { source: `/${filename}` }
-  };
-  const changelog = tabs.findIndex((tab) => tab.tab.toLowerCase() === "changelog");
-  if (changelog >= 0) tabs.splice(changelog, 0, apiTab);
-  else tabs.push(apiTab);
+  const tabs = config.tabs.map((tab) => ({ ...tab }));
+  const apiTab = tabs.find((tab) => tab.tab.toLowerCase().includes("api"));
+  if (apiTab) apiTab.api = { source: `/${filename}`, navigation: false };
+  else tabs.push({ tab: "API Reference", api: { source: `/${filename}` } });
   return { ...config, tabs };
 }
 function migrateRepository(options) {
   const repositoryDir = options.repositoryDir;
-  const platform = options.platform ?? detectRepositoryPlatform(repositoryDir);
+  const platform = options.platform ?? detectRepositoryPlatform(repositoryDir, options.docsDir);
+  const mintlifyProjectRoot = platform === "mintlify" ? findMintlifyProjectRoot(repositoryDir, options.docsDir) : null;
   const docusaurusProjectRoot = platform === "docusaurus" ? findDocusaurusProjectRoot(repositoryDir, options.docsDir) : null;
   const configuredDocsDir = (() => {
     if (options.docsDir !== void 0) {
@@ -1226,23 +1622,30 @@ function migrateRepository(options) {
       const projectRelative = relative3(repositoryDir, docusaurusProjectRoot).replace(/\\/g, "/");
       return [projectRelative, primaryDocusaurusDocsDirectory(docusaurusProjectRoot)].filter(Boolean).join("/");
     }
+    if (platform === "mintlify" && mintlifyProjectRoot) {
+      return relative3(repositoryDir, mintlifyProjectRoot).replace(/\\/g, "/");
+    }
     return platform === "mintlify" ? "" : detectRepositoryDocsDir(repositoryDir);
   })();
   const warnings = [];
   let docsConfig = { tabs: [] };
   const referenceMap = /* @__PURE__ */ new Map();
+  const exactReferenceMap = /* @__PURE__ */ new Map();
   const referenceOrder = /* @__PURE__ */ new Map();
   let docusaurusSidebars = null;
+  let mintlifyConfig = null;
   if (platform === "mintlify") {
     try {
-      const config = readMintlifyConfig(repositoryDir);
+      const config = readMintlifyConfig(mintlifyProjectRoot ?? repositoryDir);
       if (config) {
+        mintlifyConfig = config;
         const projected = projectMintlifyNavigation(config);
         docsConfig = projected.docsConfig;
         warnings.push(...projected.warnings);
         for (const [index, reference] of projected.pageReferences.entries()) {
           const key = normalizedReferenceKey(reference.ref);
           referenceMap.set(key, reference);
+          exactReferenceMap.set(exactReferenceKey(reference.ref), reference);
           referenceOrder.set(key, index);
         }
       }
@@ -1264,7 +1667,7 @@ function migrateRepository(options) {
     }
   }
   const contentRoot = resolveWithin(repositoryDir, configuredDocsDir);
-  if (!existsSync3(contentRoot) || !lstatSync2(contentRoot).isDirectory()) {
+  if (!existsSync3(contentRoot) || !lstatSync3(contentRoot).isDirectory()) {
     throw new Error(`Documentation directory does not exist: ${configuredDocsDir || "."}`);
   }
   const files = scanFiles(contentRoot);
@@ -1280,6 +1683,7 @@ function migrateRepository(options) {
     const rightOrder = referenceOrder.get(normalizedReferenceKey(right.relativePath)) ?? Number.MAX_SAFE_INTEGER;
     return leftOrder - rightOrder || left.relativePath.localeCompare(right.relativePath);
   });
+  const snippetAliases = platform === "mintlify" && mintlifyProjectRoot ? globalSnippetAliases(files, repositoryDir, mintlifyProjectRoot) : /* @__PURE__ */ new Map();
   for (const file of pageFiles) {
     if (!isDocumentationExtension(file.relativePath)) continue;
     const sourceSegments = file.relativePath.split("/");
@@ -1288,7 +1692,7 @@ function migrateRepository(options) {
       continue;
     }
     const rootFilename = !file.relativePath.includes("/") ? basename(file.relativePath).toLowerCase() : "";
-    if (!configuredDocsDir && REPOSITORY_ONLY_DOCUMENTS.has(rootFilename)) {
+    if (REPOSITORY_ONLY_DOCUMENTS.has(rootFilename) && !exactReferenceMap.has(exactReferenceKey(file.relativePath))) {
       skipped++;
       continue;
     }
@@ -1297,21 +1701,21 @@ function migrateRepository(options) {
       warnings.push({ code: "skipped-file", message: "Only Markdown and MDX are imported without an explicit converter.", source: file.relativePath });
       continue;
     }
-    const size = lstatSync2(file.absolutePath).size;
+    const size = lstatSync3(file.absolutePath).size;
     if (size > MAX_PAGE_BYTES) {
       skipped++;
       warnings.push({ code: "skipped-file", message: "Page exceeded the 2 MB repository import limit.", source: file.relativePath });
       continue;
     }
     const key = normalizedReferenceKey(file.relativePath);
-    const referenced = referenceMap.get(key);
+    const referenced = exactReferenceMap.get(exactReferenceKey(file.relativePath)) ?? referenceMap.get(key);
     let locale = referenced?.locale;
-    let navigationId = referenced?.navigationId ?? pageIdFromReference(file.relativePath);
+    let navigationId = referenced?.navigationId ?? pageIdFromReference(file.relativePath, platform === "mintlify");
     if (!referenced && localeConfig) {
       const prefix = file.relativePath.split("/", 1)[0];
       if (localeConfig.locales.some((entry) => entry.code === prefix)) {
         locale = prefix;
-        navigationId = pageIdFromReference(file.relativePath.slice(prefix.length + 1));
+        navigationId = pageIdFromReference(file.relativePath.slice(prefix.length + 1), platform === "mintlify");
       }
     }
     if (!navigationId) {
@@ -1327,7 +1731,8 @@ function migrateRepository(options) {
       repositoryDir,
       warnings,
       0,
-      docusaurusProjectRoot ?? repositoryDir
+      mintlifyProjectRoot ?? docusaurusProjectRoot ?? repositoryDir,
+      snippetAliases
     );
     let docusaurusDescriptor;
     const page = parseMarkdownPage({
@@ -1335,11 +1740,11 @@ function migrateRepository(options) {
       navigationId,
       ...locale ? { locale } : {},
       raw,
-      source: `${options.sourceUrl}#${file.relativePath}`,
+      source: `${options.sourceUrl}#${relative3(repositoryDir, file.absolutePath).replace(/\\/g, "/")}`,
       ...platform === "docusaurus" ? {
         resolveIdentity: (frontmatter, fallback) => {
           const resolved = resolveDocusaurusPageIdentity(file.relativePath, frontmatter, fallback);
-          const routePrefix = options.docusaurusRoutePrefix?.replace(/^\/+|\/+$/g, "");
+          const routePrefix = options.docusaurusRoutePrefix === void 0 ? void 0 : trimEdgeSlashes(options.docusaurusRoutePrefix);
           if (!routePrefix) {
             docusaurusDescriptor = resolved.descriptor;
             return resolved.identity;
@@ -1362,6 +1767,9 @@ function migrateRepository(options) {
       skipped++;
       continue;
     }
+    if (platform === "mintlify" && mintlifyProjectRoot) {
+      page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, mintlifyProjectRoot);
+    }
     if (seenPageIds.has(page.id)) {
       skipped++;
       warnings.push({ code: "collision", message: `Multiple source files map to ${page.id}; the first file was kept.`, source: file.relativePath });
@@ -1382,7 +1790,7 @@ function migrateRepository(options) {
   const docusaurusAssetRoot = docusaurusProjectRoot ?? repositoryDir;
   const repositoryAssets = platform === "docusaurus" && configuredDocsDir && !options.docusaurusSkipAssets ? ["static", "public"].flatMap((directory) => {
     const root = resolveWithin(docusaurusAssetRoot, directory);
-    if (!existsSync3(root) || !lstatSync2(root).isDirectory()) return [];
+    if (!existsSync3(root) || !lstatSync3(root).isDirectory()) return [];
     return scanFiles(root).map((file) => ({
       ...file,
       relativePath: `${directory}/${file.relativePath}`
@@ -1391,8 +1799,9 @@ function migrateRepository(options) {
   let totalAssetBytes = 0;
   for (const file of [...files, ...repositoryAssets]) {
     const firstSegment = file.relativePath.split("/", 1)[0].toLowerCase();
-    if (!ASSET_DIRECTORIES.has(firstSegment) || !ASSET_EXTENSIONS.has(extname3(file.relativePath).toLowerCase())) continue;
-    const size = lstatSync2(file.absolutePath).size;
+    if (!ASSET_EXTENSIONS.has(extname3(file.relativePath).toLowerCase())) continue;
+    if (platform !== "mintlify" && !ASSET_DIRECTORIES.has(firstSegment)) continue;
+    const size = lstatSync3(file.absolutePath).size;
     if (size > MAX_ASSET_BYTES || totalAssetBytes + size > MAX_TOTAL_ASSET_BYTES) {
       warnings.push({ code: "limit-reached", message: "An asset was skipped because the migration asset budget was exhausted.", source: file.relativePath });
       continue;
@@ -1430,7 +1839,7 @@ function migrateRepository(options) {
     }
   }
   if (docsConfig.tabs.length === 0) docsConfig = buildNavigationFromPages(pages);
-  const openApi = findOpenApi(files);
+  const openApi = findConfiguredMintlifyOpenApi(mintlifyConfig, files) ?? findOpenApi(files);
   if (openApi) {
     const filename = basename(openApi.relativePath);
     if (!assets.some((asset) => asset.path === filename)) {
@@ -1438,6 +1847,7 @@ function migrateRepository(options) {
     }
     docsConfig = injectOpenApi(docsConfig, filename);
   }
+  if (platform === "mintlify") docsConfig = addMintlifyDirectoryRedirects(docsConfig, pages);
   if (platform === "docusaurus" && docusaurusProjectRoot && !options.docusaurusSkipPlugins) {
     for (const plugin of additionalDocusaurusPluginRoots(repositoryDir, docusaurusProjectRoot)) {
       if (plugin.docsDir === configuredDocsDir) continue;
@@ -1479,6 +1889,12 @@ function migrateRepository(options) {
     pages,
     assets,
     docsConfig,
+    ...mintlifyConfig ? {
+      site: {
+        ...typeof mintlifyConfig.name === "string" ? { name: mintlifyConfig.name } : {},
+        ...typeof mintlifyConfig.description === "string" ? { description: mintlifyConfig.description } : {}
+      }
+    } : {},
     warnings,
     stats: { discovered, imported: pages.length, skipped }
   };
@@ -1492,8 +1908,13 @@ function renderPage(bundle, page) {
   return [
     "---",
     `title: ${yamlString(page.title)}`,
+    page.navTitle ? `navTitle: ${yamlString(page.navTitle)}` : null,
     `description: ${yamlString(page.description)}`,
+    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,
+    page.hidden ? "hidden: true" : null,
+    page.noindex ? "noindex: true" : null,
     page.openapi ? `openapi: ${yamlString(page.openapi)}` : null,
     bundle.sourceKind === "url" ? `source: ${yamlString(page.source)}` : null,
     "---",
@@ -1591,10 +2012,13 @@ var PORTABLE_MDX_COMPONENTS = /* @__PURE__ */ new Set([
   "Color",
   "Column",
   "Columns",
+  "ContentPanel",
   "Danger",
   "Error",
   "Expandable",
   "Agent",
+  "AgentPrompt",
+  "BannerPreview",
   "Embed",
   "File",
   "Folder",
@@ -1785,7 +2209,7 @@ function pageIdForUrl(url, scopePath) {
     else if (path === scopePath) path = "";
     else if (path.startsWith(`${scopePath}/`)) path = path.slice(scopePath.length + 1);
   }
-  return pageIdFromReference(path.replace(/^\/+/, "") || "introduction");
+  return pageIdFromReference(path.replace(/^\/+/, "") || "introduction", true);
 }
 function canonicalLocalizedPageId(id) {
   const [segment, ...rest] = id.split("/");
@@ -1807,6 +2231,72 @@ function detectUrlPlatform(document) {
   if (value.includes("starlight")) return "starlight";
   return "generic";
 }
+function jsonObjectAfterKey(value, key) {
+  let cursor = 0;
+  const marker = `"${key}":`;
+  while (cursor < value.length) {
+    const markerIndex = value.indexOf(marker, cursor);
+    if (markerIndex < 0) return null;
+    let start = markerIndex + marker.length;
+    while (/\s/.test(value[start] ?? "")) start += 1;
+    if (value[start] !== "{") {
+      cursor = start + 1;
+      continue;
+    }
+    let depth = 0;
+    let isQuoted = false;
+    let isEscaped = false;
+    for (let index = start; index < value.length; index += 1) {
+      const character = value[index];
+      if (isQuoted) {
+        if (isEscaped) isEscaped = false;
+        else if (character === "\\") isEscaped = true;
+        else if (character === '"') isQuoted = false;
+        continue;
+      }
+      if (character === '"') {
+        isQuoted = true;
+        continue;
+      }
+      if (character === "{") depth += 1;
+      if (character === "}") {
+        depth -= 1;
+        if (depth !== 0) continue;
+        try {
+          const parsed = JSON.parse(value.slice(start, index + 1));
+          return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+        } catch {
+          break;
+        }
+      }
+    }
+    cursor = start + 1;
+  }
+  return null;
+}
+function embeddedMintlifyConfig(body) {
+  const $ = load(body);
+  const flightPayloads = [];
+  $("script").each((_index, element) => {
+    const script = $(element).text();
+    for (const match of script.matchAll(/self\.__next_f\.push\(\[1,("(?:\\.|[^"\\])*")\]\)/g)) {
+      try {
+        const payload2 = JSON.parse(match[1]);
+        if (typeof payload2 === "string") flightPayloads.push(payload2);
+      } catch {
+      }
+    }
+  });
+  if (flightPayloads.length === 0) return null;
+  const payload = flightPayloads.join("\n");
+  const docsConfig = jsonObjectAfterKey(payload, "docsConfig");
+  const scopedNavigation = jsonObjectAfterKey(payload, "scopedNav");
+  if (!docsConfig && !scopedNavigation) return null;
+  return {
+    ...docsConfig ?? {},
+    ...scopedNavigation ? { navigation: scopedNavigation } : {}
+  };
+}
 function plainDescription(value) {
   return value.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[`*_>#-]/g, "").replace(/\s+/g, " ").trim().slice(0, 240);
 }
@@ -2045,7 +2535,12 @@ function remoteMarkdownMetadata(body) {
   return {
     content: body.slice(contentStart),
     title: scalar("title"),
-    description: scalar("description")
+    description: scalar("description"),
+    sidebarTitle: scalar("sidebarTitle"),
+    tag: scalar("tag"),
+    mode: scalar("mode"),
+    hidden: scalar("hidden") === "true" ? true : void 0,
+    noindex: scalar("noindex") === "true" ? true : void 0
   };
 }
 function stripMintlifyDocumentationIndex(body) {
@@ -2105,6 +2600,11 @@ function markdownPage(document, id) {
     "---",
     `title: ${JSON.stringify(title)}`,
     ...description ? [`description: ${JSON.stringify(description)}`] : [],
+    ...parsed.sidebarTitle ? [`sidebarTitle: ${JSON.stringify(parsed.sidebarTitle)}`] : [],
+    ...parsed.tag ? [`tag: ${JSON.stringify(parsed.tag)}`] : [],
+    ...parsed.mode ? [`mode: ${JSON.stringify(parsed.mode)}`] : [],
+    ...parsed.hidden ? ["hidden: true"] : [],
+    ...parsed.noindex ? ["noindex: true"] : [],
     ...embeddedOpenApi.openapi ? [`openapi: ${JSON.stringify(embeddedOpenApi.openapi)}`] : [],
     "---",
     "",
@@ -2487,7 +2987,7 @@ function htmlTopLevelNavigation(document, source, scopePath) {
   const collectCandidates = (selector) => {
     const candidates2 = [];
     $(selector).each((_containerIndex, container) => {
-      const entries = [];
+      const entries2 = [];
       const seenSections = /* @__PURE__ */ new Set();
       let anchorCount = 0;
       $(container).find("a[href]").each((_index, element) => {
@@ -2503,22 +3003,40 @@ function htmlTopLevelNavigation(document, source, scopePath) {
           const section = targetId.split("/", 1)[0] || "introduction";
           if (!pageId || seenSections.has(section)) return;
           seenSections.add(section);
-          entries.push({ section, label, pageId });
+          entries2.push({ section, label, pageId });
         } catch {
         }
       });
-      if (entries.length > 1) {
-        candidates2.push({ entries, anchorCount });
+      if (entries2.length > 1) {
+        candidates2.push({ entries: entries2, anchorCount });
       }
     });
     return candidates2;
   };
   const tabCandidates = collectCandidates(".nav-tabs");
   const candidates = tabCandidates.length > 0 ? tabCandidates : collectCandidates('nav, [role="navigation"]');
-  return candidates.sort((left, right) => {
+  const entries = candidates.sort((left, right) => {
     const densityDifference = right.entries.length / right.anchorCount - left.entries.length / left.anchorCount;
     return densityDifference || right.entries.length - left.entries.length;
   })[0]?.entries ?? [];
+  const normalizedLabels = entries.map((entry) => entry.label.trim().toLowerCase());
+  if (entries.length > 12 || new Set(normalizedLabels).size !== normalizedLabels.length) return [];
+  return entries;
+}
+function remapNavigationHome(config, sourceHomePageId) {
+  if (!sourceHomePageId || sourceHomePageId === "introduction") return config;
+  const remapGroups = (groups) => groups.map((group) => ({
+    ...group,
+    pages: group.pages.map((page) => typeof page === "string" ? page === sourceHomePageId ? "introduction" : page : remapGroups([page])[0])
+  }));
+  return {
+    ...config,
+    tabs: config.tabs.map((tab) => ({
+      ...tab,
+      ...tab.href === `/${sourceHomePageId}` ? { href: "/" } : {},
+      ...tab.groups ? { groups: remapGroups(tab.groups) } : {}
+    }))
+  };
 }
 function markdownLinks(body) {
   return [...body.matchAll(/\[[^\]]+\]\(([^)\s]+)(?:\s+['"][^'"]*['"])?\)/g)].map((match) => match[1]);
@@ -2583,8 +3101,13 @@ async function migrateUrl(options) {
   }
   const docusaurusDiscovery = platform === "docusaurus" && docusaurusHtmlProbe ? deriveDocusaurusScope(source, docusaurusHtmlProbe, submittedScopePath) : null;
   const scopePath = platform === "mintlify" ? machineIndexScopePath(source, [initial, scopedHtmlProbe]) ?? submittedScopePath : docusaurusDiscovery?.scopePath ?? submittedScopePath;
-  const sourceTopLevelNavigation = platform === "mintlify" && scopedHtmlProbe && /html/i.test(scopedHtmlProbe.contentType) ? htmlTopLevelNavigation(scopedHtmlProbe, source, scopePath) : void 0;
-  const sourceHomePageId = sourceTopLevelNavigation?.[0]?.pageId ?? (platform === "mintlify" && scopePath === "/" ? canonicalLocalizedPageId(pageIdForUrl(source, scopePath) ?? "") || void 0 : void 0);
+  const sourceMintlifyConfig = platform === "mintlify" && scopedHtmlProbe && /html/i.test(scopedHtmlProbe.contentType) ? embeddedMintlifyConfig(scopedHtmlProbe.body) : null;
+  const sourceMintlifyProjection = sourceMintlifyConfig ? projectMintlifyNavigation(sourceMintlifyConfig, { pathPrefix: scopePath }) : null;
+  const hasStructuredMintlifyNavigation = Boolean(
+    sourceMintlifyProjection?.docsConfig.tabs.length && sourceMintlifyProjection.pageReferences.length
+  );
+  const sourceTopLevelNavigation = platform === "mintlify" && !hasStructuredMintlifyNavigation && scopedHtmlProbe && /html/i.test(scopedHtmlProbe.contentType) ? htmlTopLevelNavigation(scopedHtmlProbe, source, scopePath) : void 0;
+  const sourceHomePageId = sourceMintlifyProjection?.pageReferences[0]?.navigationId ?? sourceTopLevelNavigation?.[0]?.pageId ?? (platform === "mintlify" && scopePath === "/" ? canonicalLocalizedPageId(pageIdForUrl(source, scopePath) ?? "") || void 0 : void 0);
   const cache = /* @__PURE__ */ new Map([[source.toString(), initial]]);
   if (docusaurusHtmlProbe) cache.set(docusaurusHtmlProbe.finalUrl.toString(), docusaurusHtmlProbe);
   const queue = [source];
@@ -2605,6 +3128,13 @@ async function migrateUrl(options) {
     queued.add(candidateIdentity(url));
     queue.push(url);
   }
+  for (const reference of sourceMintlifyProjection?.pageReferences ?? []) {
+    let href = reference.ref;
+    if (scopePath !== "/" && href.startsWith("/") && href !== scopePath && !href.startsWith(`${scopePath}/`)) {
+      href = `${scopePath}${href}`;
+    }
+    enqueue(href, source);
+  }
   const navigationProbe = docusaurusHtmlProbe ?? scopedHtmlProbe;
   if (navigationProbe && /html/i.test(navigationProbe.contentType)) {
     for (const link of htmlNavigationLinks(navigationProbe)) enqueue(link, navigationProbe.finalUrl);
@@ -2808,10 +3338,11 @@ async function migrateUrl(options) {
     ...entry,
     pageId: entry.pageId === sourceHomePageId ? "introduction" : entry.pageId
   }));
-  const docsConfig = platform === "docusaurus" ? docusaurusNavigationFromSnapshots(docusaurusSidebars, pages, scopePath) : buildNavigationFromPages(pages, {
+  let docsConfig = platform === "docusaurus" ? docusaurusNavigationFromSnapshots(docusaurusSidebars, pages, scopePath) : hasStructuredMintlifyNavigation && sourceMintlifyProjection ? remapNavigationHome(sourceMintlifyProjection.docsConfig, sourceHomePageId) : buildNavigationFromPages(pages, {
     topLevelTabs: platform === "mintlify",
     topLevelNavigation
   });
+  if (sourceMintlifyProjection) warnings.push(...sourceMintlifyProjection.warnings);
   if (docusaurusRedirects.length > 0) {
     docsConfig.redirects = [...new Map(docusaurusRedirects.map((redirect) => [
       `${redirect.source}:${redirect.destination}`,
@@ -2841,6 +3372,7 @@ async function migrateUrl(options) {
       ]
     };
   }
+  if (platform === "mintlify") docsConfig = addMintlifyDirectoryRedirects(docsConfig, pages);
   return {
     sourceUrl: source.toString(),
     sourceKind: "url",
@@ -2848,6 +3380,12 @@ async function migrateUrl(options) {
     pages,
     assets: openApiAsset ? [{ path: "openapi.yaml", content: openApiAsset }] : [],
     docsConfig,
+    ...sourceMintlifyConfig ? {
+      site: {
+        ...typeof sourceMintlifyConfig.name === "string" ? { name: sourceMintlifyConfig.name } : {},
+        ...typeof sourceMintlifyConfig.description === "string" ? { description: sourceMintlifyConfig.description } : {}
+      }
+    } : {},
     warnings,
     stats: {
       discovered: visited.size,
@@ -2857,6 +3395,7 @@ async function migrateUrl(options) {
   };
 }
 export {
+  addMintlifyDirectoryRedirects,
   buildNavigationFromPages,
   cloneGitHubRepository,
   defaultMigrationFetcher,