@thallylabs/migrate 0.2.40 → 0.2.41

package/dist/index.js

@@ -1370,8 +1370,29 @@ ${trimmed.slice(0, marker).trimEnd()}`;
 function headingIdMarker(id) {
   return `{/* #${id} */}`;
 }
+var HEADING_ID_WORD = /[\p{L}\p{M}\p{N}_+&/@\u2019\u201c\u201d\u2014\u2013\u2192]/u;
 function mintlifyHeadingSlug(text3) {
-  return text3.replace(/\u200b/g, "").normalize("NFC").trim().toLowerCase().replace(/[.\s]+/g, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "").replace(/[^\p{L}\p{M}\p{N}_\-+&/\u2019\u201c\u201d\u2014\u2013\u2192]/gu, "");
+  const chars = [...text3.replace(/[\u200b*]/g, "").normalize("NFC").trim().toLowerCase()];
+  const isWord = (char) => char !== void 0 && HEADING_ID_WORD.test(char);
+  let id = "";
+  let afterDash = false;
+  let endsWithDash = false;
+  chars.forEach((char, index) => {
+    const before = chars[index - 1];
+    const after = chars[index + 1];
+    endsWithDash = false;
+    if (isWord(char)) {
+      id += char;
+      afterDash = false;
+    } else if (/[\s-]/.test(char) || char === "." && isWord(after) || char === "(" && isWord(before) && (isWord(after) || after === "{") || char === ")" && after !== void 0 && !/\s/.test(after)) {
+      if (id && !afterDash) id += "-";
+      afterDash = true;
+      endsWithDash = true;
+    } else if (char === "{" || char === ":" || char === '"') {
+      afterDash = false;
+    }
+  });
+  return endsWithDash ? id.replace(/-$/, "") : id;
 }
 function thallyHeadingSlug(text3) {
   return text3.normalize("NFC").toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/(^-|-$)/g, "");
@@ -1383,7 +1404,7 @@ function typesetQuotes(text3) {
   }).join("");
 }
 function plainHeadingText(source) {
-  return source.replace(/\{\/\*[\s\S]*?\*\/\}/g, " ").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<\/?[A-Za-z][^>]*>/g, "").replace(/`([^`]*)`/g, "$1").replace(/(\*\*|__|~~|\*)/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/\\([\\`*_{}[\]()#+.!&<>|~-])/g, "$1");
+  return source.replace(/\{\/\*[\s\S]*?\*\/\}/g, " ").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<\/?[A-Za-z][^>]*>/g, "").replace(/`([^`]*)`/g, "$1").replace(/(?<!\\)(\*\*|__|~~|\*)/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/\\([\\`*_{}[\]()#+.!&<>|~-])/g, "$1");
 }
 function markMintlifyHeadings(body) {
   let fence;
@@ -2587,7 +2608,7 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   }
   if (runMintlify) rewritten = normalizeMintlifyParameterAnchors(rewritten);
   rewritten = replaceOutsideCode(rewritten, (segment) => {
-    let result = convertHtmlStyleAttributes(segment).replace(/<!--([\s\S]*?)-->/g, (_match, content) => mdxComment(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>");
+    let result = convertHtmlStyleAttributes(segment).replace(/<!--([\s\S]*?)-->/g, (_match, content) => mdxComment(content)).replace(/<Danger(\s[^>]*)?>/g, "<Error$1>").replace(/<\/Danger>/g, "</Error>").replace(/<Warn(\s[^>]*)?>/g, "<Warning$1>").replace(/<\/Warn>/g, "</Warning>").replace(/<Tree\.Folder/g, "<Folder").replace(/<\/Tree\.Folder>/g, "</Folder>").replace(/<Tree\.File/g, "<File").replace(/<\/Tree\.File>/g, "</File>");
     if (runDocusaurus) {
       result = result.replace(/<TabItem\b([^<>]*)>/g, (_match, attributes) => {
         const title = attributes.match(/\blabel=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean) ?? attributes.match(/\bvalue=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean) ?? "Tab";
@@ -2596,7 +2617,7 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
       result = normalizeDocusaurusLinkTags(result).replace(/<(?:DocCardList|TOCInline)\b[^<>]*\/>/g, "");
     }
     if (runMintlify) {
-      result = normalizeMintlifyUpdateLabels(result).replace(/<FileTree(\s[^>]*)?>/g, "<Tree$1>").replace(/<\/FileTree>/g, "</Tree>").replace(/<GitHub\.Repo/g, "<GitHub").replace(/<\/GitHub\.Repo>/g, "</GitHub>").replace(/<Column(\s[^>]*)?>/g, "<div$1>").replace(/<\/Column>/g, "</div>");
+      result = normalizeMintlifyUpdateLabels(result).replace(/<FileTree(\s[^>]*)?>/g, "<Tree$1>").replace(/<\/FileTree>/g, "</Tree>").replace(/<GitHub\.Repo/g, "<GitHub").replace(/<\/GitHub\.Repo>/g, "</GitHub>").replace(/<Callout(\s[^<>]*)?>/g, (tag) => tag.replace(/(\s)type=(?:"[^"]*"|'[^']*'|\{[^{}]*\})/, '$1type="info"')).replace(/<Column(\s[^>]*)?>/g, "<div$1>").replace(/<\/Column>/g, "</div>");
       result = pinStepsTitleSize(result);
     }
     if (runFern) {
@@ -2615,6 +2636,16 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   }
   return normalizeFlowParagraphContainers(normalized);
 }
+function externalPageUrl(value) {
+  const url = typeof value === "string" ? value.trim() : "";
+  if (!/^https?:\/\/[^\s]+$/i.test(url)) return void 0;
+  try {
+    new URL(url);
+    return url;
+  } catch {
+    return void 0;
+  }
+}
 function parseMarkdownPage(input) {
   const parsed = parseFrontmatter(input.raw);
   const fallbackIdentity = {
@@ -2639,6 +2670,7 @@ function parseMarkdownPage(input) {
   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 externalUrl = input.platform === "mintlify" ? externalPageUrl(parsed.data.url) : void 0;
   const description = typeof parsed.data.description === "string" && parsed.data.description.trim() ? parsed.data.description.trim() : typeof parsed.data.openapi === "string" && parsed.data.openapi.trim() ? "" : firstParagraph(body);
   const page = {
     id: identity.id,
@@ -2654,7 +2686,9 @@ function parseMarkdownPage(input) {
     keywords,
     mode,
     hidden: parsed.data.hidden === true ? true : void 0,
-    noindex: parsed.data.noindex === true || parsed.data.noindex === "true" ? true : void 0,
+    // The path of a page that links elsewhere redirects, so it has no business in a sitemap.
+    noindex: parsed.data.noindex === true || parsed.data.noindex === "true" || externalUrl ? true : void 0,
+    ...externalUrl ? { externalUrl } : {},
     ...Object.keys(meta).length > 0 ? { meta } : {},
     openapi: typeof parsed.data.openapi === "string" ? parsed.data.openapi.trim() : void 0,
     ...apiFrontmatter(parsed.data, input.warn),
@@ -4391,12 +4425,17 @@ function addMintlifyHomepageRedirects(config, pages) {
   const homepage = config.tabs.filter((tab) => !tab.hidden).map((tab) => firstPage([...tab.pages ?? [], ...tab.groups ?? []])).find(Boolean);
   if (!homepage) return config;
   const redirects = [...config.redirects ?? []];
-  const sources = new Set(redirects.map((redirect) => (redirect.source.replace(/\/$/, "") || "/").toLowerCase()));
+  const routeKey = (route) => (route.split(/[?#]/, 1)[0].replace(/\/$/, "") || "/").toLowerCase();
+  const sources = new Set(redirects.map((redirect) => routeKey(redirect.source)));
   const roots = ["", ...(config.i18n?.locales ?? []).filter((locale) => locale.code !== config.i18n?.defaultLocale).filter((locale) => homepage !== "introduction" || pages.some((page) => page.locale === locale.code && page.navigationId === homepage)).map((locale) => locale.code)];
+  const homeLinksElsewhere = pages.some((page) => page.id === "introduction" && page.externalUrl);
   for (const locale of roots) {
+    if (!locale && homeLinksElsewhere) continue;
     const source = locale ? `/${locale}` : "/";
     if (sources.has(source.toLowerCase())) continue;
-    redirects.push({ source, destination: `${locale ? `/${locale}` : ""}/${homepage}`, permanent: true });
+    const destination = `${locale ? `/${locale}` : ""}/${homepage}`;
+    if (redirects.some((redirect) => routeKey(redirect.source) === destination.toLowerCase() && routeKey(redirect.destination) === source.toLowerCase())) continue;
+    redirects.push({ source, destination, permanent: true });
   }
   return { ...config, redirects };
 }
@@ -4593,7 +4632,7 @@ function mergeApiGroups(existing, incoming) {
   return merged.length > 0 ? merged : void 0;
 }
 var hasNavigationChildren = (node) => ["groups", "pages"].some((key) => Array.isArray(node[key]) && node[key].length > 0);
-function mintlifyNavigationApiReferences(config) {
+function mintlifyNavigationApiReferences(config, tabFor) {
   const navigation = objectValue2(config.navigation) ?? config;
   const references = [];
   const defaultLanguage = pickDefaultLanguage(
@@ -4617,7 +4656,7 @@ function mintlifyNavigationApiReferences(config) {
         references.push({
           value,
           kind,
-          tabLabel,
+          tabLabel: tabFor?.(node) ?? tabLabel,
           ...sibling,
           ...typeof directory2 === "string" && directory2.trim() ? { directory: directory2.trim() } : {},
           ...operations.length > 0 ? { operations } : {},
@@ -4972,6 +5011,21 @@ function convertNavigationValues(values, context) {
     return page ? [page] : [];
   });
 }
+var API_TAB_CONTAINER = /* @__PURE__ */ Symbol("apiTabContainer");
+function takeApiTabSlots(tabs) {
+  const slots = [];
+  const real = [];
+  tabs.forEach((tab, index) => {
+    const container = tab[API_TAB_CONTAINER];
+    if (!container) {
+      real.push(tab);
+      return;
+    }
+    const template = Object.fromEntries(Object.entries(tab).filter(([key]) => key !== "groups"));
+    slots.push({ container, slot: { tab: template, preceding: tabs.slice(0, index).map((earlier) => earlier.tab).reverse() } });
+  });
+  return { tabs: real, slots };
+}
 function convertContainerToTabs(containerValue, context, fallbackTab, trace, depth = 0) {
   const rawContainer = objectValue2(containerValue);
   if (!rawContainer) return [];
@@ -5048,6 +5102,17 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
     ...convertNavigationValues(values, context),
     ...Array.isArray(container.menu) ? convertMenuItems(container.menu, context) : []
   ];
+  if (children.length === 0 && depth > 0 && context.operationGroups && !context.otherLanguage && !context.operations.gated && !context.operations.hidden && specSource(rawContainer.openapi) && operationGroups(rawContainer).length > 0) {
+    const placeholder2 = {
+      tab: fallbackTab,
+      groups: [],
+      ...containerPresentation(container),
+      ...projectedHref(container.href) ? { href: projectedHref(container.href) } : {},
+      ...container.hidden === true ? { hidden: true } : {},
+      [API_TAB_CONTAINER]: rawContainer
+    };
+    return [placeholder2];
+  }
   return children.length > 0 ? [{
     tab: fallbackTab,
     ...hasRootNodes ? { pages: children } : { groups: children },
@@ -5228,6 +5293,8 @@ function projectedCompatibleConfig(config, warnings) {
   return {
     // Mintlify pages show a group eyebrow above the title and no breadcrumb trail.
     breadcrumbs: false,
+    // Mintlify typesets straight quotes in prose as curly ones.
+    smartQuotes: true,
     // `styling.eyebrows: "breadcrumbs"` shows the whole group path; "section" (the default) shows the nearest group.
     ...objectValue2(config.styling)?.eyebrows === "breadcrumbs" ? { eyebrow: "path" } : {},
     ...projectedTheme(config.theme) ? { theme: projectedTheme(config.theme) } : {},
@@ -5479,6 +5546,9 @@ function projectMintlifyNavigation(config, options = {}) {
       }
     }
   }
+  const taken = takeApiTabSlots(tabs);
+  tabs = taken.tabs;
+  const apiTabSlots = taken.slots;
   if (tabs.length === 0) {
     warnings.push({
       code: "unsupported-config",
@@ -5524,6 +5594,7 @@ function projectMintlifyNavigation(config, options = {}) {
   }) : [];
   if (versions.length > 1) {
     tabs = annotateVersions(tabs);
+    for (const entry of apiTabSlots) [entry.slot.tab] = annotateVersions([entry.slot.tab]);
     for (const [locale, items] of Object.entries(localizedNavigation)) localizedNavigation[locale] = annotateVersions(items);
   }
   const redirects = Array.isArray(config.redirects) ? config.redirects.flatMap((value) => {
@@ -5547,11 +5618,13 @@ function projectMintlifyNavigation(config, options = {}) {
     }];
   }) : [];
   collectReferenceAccess(navigation, OPEN_NAVIGATION_ACCESS, options.pathPrefix, appearances);
+  const keepsCollectionNamedGroup = [tabs, ...Object.values(localizedNavigation)].some((items) => items.some((item) => item.groups?.some((group) => group.group === (item.displayLabel ?? item.tab))));
   return {
     docsConfig: {
       tabs,
-      ...projectionTrace.rootContainerKind === "dropdowns" || versions.length > 1 || shortcuts.length > 0 ? { navigation: {
+      ...projectionTrace.rootContainerKind === "dropdowns" || versions.length > 1 || shortcuts.length > 0 || keepsCollectionNamedGroup ? { navigation: {
         ...projectionTrace.rootContainerKind === "dropdowns" ? { display: "dropdown" } : {},
+        ...keepsCollectionNamedGroup ? { groupHeadings: "all" } : {},
         ...versions.length > 1 ? { versions } : {},
         ...shortcuts.length > 0 ? { shortcuts } : {}
       } } : {},
@@ -5563,6 +5636,7 @@ function projectMintlifyNavigation(config, options = {}) {
     pageReferences: references,
     referenceAccess: appearances,
     gatedSourceRefs,
+    apiTabSlots,
     warnings
   };
 }
@@ -9074,6 +9148,9 @@ function destinationRoute(destination) {
 function pageRoutes(pages) {
   return pages.flatMap((page) => [`/${page.id}`, `/${page.id.replace(/\/index$/, "")}`]);
 }
+function pageEntryRoutes(page) {
+  return [.../* @__PURE__ */ new Set([...pageRoutes([page]), ...page.id === "introduction" ? ["/"] : []])];
+}
 function servedRoutes(pages) {
   return new Set(pageRoutes(pages).map((route) => route.toLowerCase()));
 }
@@ -9138,11 +9215,13 @@ function dropConflictingRedirects(config, pages, warnings) {
   const loopingByCase = [];
   const folded = redirectChains();
   const asWritten = redirectChains();
+  const rootRedirected = config.redirects.some((redirect) => literalRoute(redirect.source) === "/");
   const redirects = config.redirects.filter((redirect) => {
     const source = literalRoute(redirect.source);
     if (!source) return true;
     const writtenSource = exactRoute(redirect.source);
-    if (served.has(source)) {
+    const retiresRootAlias = source === "/introduction" && !rootRedirected && destinationRoute(redirect.destination) === "/";
+    if (served.has(source) && !retiresRootAlias) {
       const hides = servedAsWritten.has(writtenSource) ? hidden : hiddenByCase;
       hides.push(redirect.source);
       return false;
@@ -12337,12 +12416,19 @@ function mintlifyTopLevelApiReferences(config) {
 function specFileCandidates(files) {
   return files.filter((file) => /\.(?:json|ya?ml)$/i.test(file.relativePath)).map((file) => ({ sourcePath: file.relativePath, filename: specRefBaseName(file.relativePath) }));
 }
-function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, nameSpec, pages = []) {
+function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, nameSpec, pages = [], apiTabSlots = []) {
   if (!mintlifyConfig) return [];
+  const slotByContainer = new Map(apiTabSlots.map(({ container, slot }) => [container, slot]));
+  const slotByLabel = new Map(apiTabSlots.map(({ slot }) => [slot.tab.tab, slot]));
   const references = [
     ...mintlifyTopLevelApiReferences(mintlifyConfig),
-    ...mintlifyNavigationApiReferences(mintlifyConfig)
+    ...mintlifyNavigationApiReferences(mintlifyConfig, (container) => slotByContainer.get(container)?.tab.tab)
   ];
+  const endpointPagesOf = (reference) => {
+    const directory2 = reference.groups ? endpointDirectory(reference.directory) : void 0;
+    const slot = reference.tabLabel ? slotByLabel.get(reference.tabLabel) : void 0;
+    return directory2 === void 0 ? void 0 : { directory: directory2, ...slot ? { slot } : {} };
+  };
   const known = new Set(references.map((reference) => canonicalSpecRef(reference.value)));
   const specFiles = specFileCandidates(files);
   const namedFiles = /* @__PURE__ */ new Map();
@@ -12383,6 +12469,14 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
         if (reference.groups) {
           const merged = mergeApiGroups(shared.target.groups, reference.groups);
           if (merged) shared.target.groups = merged;
+          const own2 = endpointPagesOf(reference);
+          if (shared.directory === void 0) {
+            shared.directory = own2?.directory ?? null;
+            if (own2) shared.target.endpointPages = own2;
+          } else if (shared.directory !== (own2?.directory ?? null)) {
+            shared.directory = null;
+            delete shared.target.endpointPages;
+          }
         } else if (listsNothing(reference)) {
           shared.unlisted = true;
           delete shared.target.groups;
@@ -12401,11 +12495,12 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
       continue;
     }
     if (/^https:\/\//i.test(reference.value)) {
-      const remote = { url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, ...groups ? { groups } : {} };
+      const pagesTarget = endpointPagesOf(reference);
+      const remote = { url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, ...groups ? { groups } : {}, ...groups && pagesTarget ? { endpointPages: pagesTarget } : {} };
       mountDirectory(remote, reference);
       remoteSpecs.push(remote);
       remoteByKey.set(dedupeKey, remote);
-      groupTargets.set(dedupeKey, { target: remote, unlisted: listsNothing(reference), withheld: reference.operationsWithheld === true });
+      groupTargets.set(dedupeKey, { target: remote, unlisted: listsNothing(reference), withheld: reference.operationsWithheld === true, ...groups ? { directory: pagesTarget?.directory ?? null } : {} });
       warnings.push({
         code: "unsupported-config",
         message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} requires a network download before this import is complete.`,
@@ -12426,12 +12521,12 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
       });
       continue;
     }
-    if (reference.directory) {
-      warnings.push({
-        code: "unsupported-config",
-        message: `The OpenAPI spec "${reference.value}"${tabSuffix} was limited to pages under "${reference.directory}" in the source, but Thally's API reference always covers a whole tab, so it was migrated as the tab's full API reference. Links in page bodies and Mintlify endpoint URLs under "${reference.directory}/<tag>/<operation>" are redirected to the matching endpoints where one exists (a separate warning counts any endpoint redirects that were skipped); check any other links to "${reference.directory}/..." manually.`
-      });
-    }
+    const directoryWarning = reference.directory ? {
+      code: "unsupported-config",
+      message: `The OpenAPI spec "${reference.value}"${tabSuffix} was limited to pages under "${reference.directory}" in the source, but Thally's API reference always covers a whole tab, so it was migrated as the tab's full API reference. Links in page bodies and Mintlify endpoint URLs under "${reference.directory}/<tag>/<operation>" are redirected to the matching endpoints where one exists (a separate warning counts any endpoint redirects that were skipped); check any other links to "${reference.directory}/..." manually.`
+    } : void 0;
+    const deferWarning = Boolean(groups && endpointPagesOf(reference));
+    if (directoryWarning && !deferWarning) warnings.push(directoryWarning);
     const content = readSpecFile(match.absolutePath, match.relativePath, warnings);
     if (!content) continue;
     const spec = {
@@ -12444,10 +12539,11 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, n
       ...reference.pageOnly ? { pageOnly: true } : {},
       sourcePath: match.relativePath,
       directory: reference.directory,
-      ...groups ? { groups } : {}
+      ...groups ? { groups } : {},
+      ...deferWarning ? { endpointPages: endpointPagesOf(reference), directoryWarning } : {}
     };
     specs.push(spec);
-    groupTargets.set(dedupeKey, { target: spec, unlisted: listsNothing(reference), withheld: reference.operationsWithheld === true });
+    groupTargets.set(dedupeKey, { target: spec, unlisted: listsNothing(reference), withheld: reference.operationsWithheld === true, ...groups ? { directory: endpointPagesOf(reference)?.directory ?? null } : {} });
   }
   for (const { target: target2, unlisted, withheld } of groupTargets.values()) {
     if (withheld && !unlisted && !target2.groups) target2.navigation = false;
@@ -12503,20 +12599,52 @@ function apiTabSpecIds(tabs) {
 }
 var flagged = (value) => value === true || value === "true";
 var isWithheld = (node) => flagged(node["x-hidden"]) || flagged(node["x-excluded"]);
+var isRecord2 = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+function resolveLocalSpecRef(document, ref) {
+  if (ref !== "#" && !ref.startsWith("#/")) return void 0;
+  let node = document;
+  for (const segment of ref.slice(2).split("/").filter(Boolean)) {
+    if (!isRecord2(node) && !Array.isArray(node)) return void 0;
+    let decoded = segment;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+    }
+    node = node[decoded.replace(/~1/g, "/").replace(/~0/g, "~")];
+  }
+  return node;
+}
+function viewSpecPathItem(document, entry) {
+  const chain = [entry];
+  let current = entry;
+  while (typeof current.$ref === "string") {
+    const target2 = resolveLocalSpecRef(document, current.$ref);
+    if (!isRecord2(target2) || chain.includes(target2)) break;
+    chain.push(target2);
+    current = target2;
+  }
+  const item = Object.assign({}, ...[...chain].reverse());
+  delete item.$ref;
+  return { item, withheld: chain.some(isWithheld) };
+}
 function parseOpenApiOperationsForLinking(content) {
-  let document;
+  const document = readSpecDocument(content);
+  return visibleOperations(document, isRecord2(document) ? document.paths : void 0);
+}
+function readSpecDocument(content) {
   try {
-    document = parseSpecDocument(content.toString("utf8")).document;
+    return parseSpecDocument(content.toString("utf8")).document;
   } catch {
-    return [];
+    return void 0;
   }
-  const paths = document && typeof document === "object" ? document.paths : null;
-  if (!paths || typeof paths !== "object") return [];
+}
+function visibleOperations(document, entries) {
+  if (!isRecord2(entries)) return [];
   const operations = [];
-  for (const [path, pathItem] of Object.entries(paths)) {
-    if (!pathItem || typeof pathItem !== "object") continue;
-    const item = pathItem;
-    if (isWithheld(item)) continue;
+  for (const [path, pathItem] of Object.entries(entries)) {
+    if (!isRecord2(pathItem)) continue;
+    const { item, withheld } = viewSpecPathItem(document, pathItem);
+    if (withheld) continue;
     for (const method of OPENAPI_HTTP_METHODS) {
       const operation = item[method];
       if (!operation || typeof operation !== "object") continue;
@@ -12528,7 +12656,8 @@ function parseOpenApiOperationsForLinking(content) {
         path,
         tag: tags[0],
         summary: typeof op.summary === "string" ? op.summary : void 0,
-        operationId: typeof op.operationId === "string" ? op.operationId : void 0
+        operationId: typeof op.operationId === "string" ? op.operationId : void 0,
+        description: typeof op.description === "string" ? op.description : void 0
       });
     }
   }
@@ -12549,13 +12678,26 @@ function servedOperations(source, parsed) {
   });
 }
 var mountPrefix = (directory2) => directory2.replace(/^\/+|\/+$/g, "").toLowerCase();
+function mintlifyEndpointUrl(directory2, operation) {
+  const tag = mintlifyUrlSlug(operation.tag ?? "default");
+  const leaf = mintlifyUrlSlug(operation.summary?.trim() || operation.operationId?.trim() || `${operation.method} ${operation.path}`);
+  return {
+    tag,
+    leaf,
+    url: `${directory2}/${tag}/${leaf}`.replace(/^\/+|\/+$/g, ""),
+    title: operation.summary?.trim() || operation.operationId?.trim() || `${operation.method.toUpperCase()} ${operation.path}`
+  };
+}
 function apiOperationLinkMap(sources, docsConfig, otherMounts = []) {
   const map = /* @__PURE__ */ new Map();
   const prefixLandings = /* @__PURE__ */ new Map();
   const mintlifyPages = /* @__PURE__ */ new Map();
   const duplicatePages = [];
   const parsedByFile = /* @__PURE__ */ new Map();
-  const bound = apiTabSpecIds(docsConfig.tabs).flatMap(({ tab, specId }) => sources.filter((entry) => tab.api?.source === specAssetPath(entry.filename) && (!entry.tab || entry.tab === tab.tab)).map((source) => ({ source, specId })));
+  const bound = [
+    ...apiTabSpecIds(docsConfig.tabs).flatMap(({ tab, specId }) => sources.filter((entry) => !entry.endpointPages && tab.api?.source === specAssetPath(entry.filename) && (!entry.tab || entry.tab === tab.tab)).map((source) => ({ source, specId }))),
+    ...sources.filter((entry) => entry.endpointPages).map((source) => ({ source }))
+  ];
   const mounts = new Set([...bound.map(({ source }) => source.prefix ? mountPrefix(source.prefix) : ""), ...otherMounts.map(mountPrefix)].filter(Boolean));
   const underDeeperMount = (route, own2) => {
     const lower = route.toLowerCase();
@@ -12565,9 +12707,12 @@ function apiOperationLinkMap(sources, docsConfig, otherMounts = []) {
     if (!source.prefix) return;
     const base = source.prefix.replace(/^\/+|\/+$/g, "");
     const prefix = mountPrefix(source.prefix);
-    if (prefix) prefixLandings.set(prefix, specId === "default" ? "/api" : `/api/${specId}`);
+    if (prefix && specId !== void 0) prefixLandings.set(prefix, specId === "default" ? "/api" : `/api/${specId}`);
     for (const operation of servedOperations(source, parsedByFile)) {
-      const thallyHref = `/api/${specId}/${thallyOperationSlugSegments(operation.path, operation.method).join("/")}`;
+      const endpoint = mintlifyEndpointUrl(base, operation);
+      if (specId === void 0 && (!endpoint.tag || !endpoint.leaf)) continue;
+      const thallyHref = specId === void 0 ? `/${endpoint.url}` : `/api/${specId}/${thallyOperationSlugSegments(operation.path, operation.method).join("/")}`;
+      if (specId === void 0 && prefix && !prefixLandings.has(prefix)) prefixLandings.set(prefix, thallyHref);
       const leafCandidates = /* @__PURE__ */ new Set();
       if (operation.operationId) {
         const parts = operation.operationId.split(/[_.]/).filter(Boolean);
@@ -12580,17 +12725,17 @@ function apiOperationLinkMap(sources, docsConfig, otherMounts = []) {
       if (operation.operationId) leafCandidates.add(mintlifyOperationSlugSegment(operation.operationId));
       leafCandidates.add(mintlifyOperationSlugSegment(`${operation.method} ${operation.path}`));
       const tagSegment = mintlifyOperationSlugSegment(operation.tag ?? "default");
-      const mintlifyTag = mintlifyUrlSlug(operation.tag ?? "default");
-      const mintlifyLeaf = mintlifyUrlSlug(operation.summary?.trim() || operation.operationId?.trim() || `${operation.method} ${operation.path}`);
-      const canonical2 = `${base}/${mintlifyTag}/${mintlifyLeaf}`.replace(/^\/+|\/+$/g, "");
+      const { tag: mintlifyTag, leaf: mintlifyLeaf, url: canonical2 } = endpoint;
       if (mintlifyTag && mintlifyLeaf && !underDeeperMount(canonical2, prefix)) {
-        if (!mintlifyPages.has(canonical2)) mintlifyPages.set(canonical2, thallyHref);
-        else if (mintlifyPages.get(canonical2) !== thallyHref && !duplicatePages.includes(canonical2)) duplicatePages.push(canonical2);
+        if (specId !== void 0) {
+          if (!mintlifyPages.has(canonical2)) mintlifyPages.set(canonical2, thallyHref);
+          else if (mintlifyPages.get(canonical2) !== thallyHref && !duplicatePages.includes(canonical2)) duplicatePages.push(canonical2);
+        }
         if (!map.has(canonical2.toLowerCase())) map.set(canonical2.toLowerCase(), thallyHref);
       }
       const tagRoot = `${base}/${mintlifyTag}`.replace(/^\/+|\/+$/g, "");
       if (mintlifyTag && !underDeeperMount(tagRoot, prefix)) {
-        if (!mintlifyPages.has(tagRoot)) mintlifyPages.set(tagRoot, thallyHref);
+        if (specId !== void 0 && !mintlifyPages.has(tagRoot)) mintlifyPages.set(tagRoot, thallyHref);
         if (!map.has(tagRoot.toLowerCase())) map.set(tagRoot.toLowerCase(), thallyHref);
       }
       for (const leaf of leafCandidates) {
@@ -12631,6 +12776,150 @@ function linkApiMounts(sources, docsConfig, pages, warnings, reservedMounts = []
   rewriteApiLinksInPages(pages, maps.operationLinks, maps.prefixLandings, warnings, { mounts: reservedMounts, redirects: docsConfig.redirects });
   return mintlifyEndpointRedirects(maps, pages, docsConfig.redirects ?? [], warnings);
 }
+var DEFAULT_ENDPOINT_DIRECTORY = "api-reference";
+function endpointDirectory(directory2) {
+  const value = (directory2 ?? DEFAULT_ENDPOINT_DIRECTORY).replace(/^\/+|\/+$/g, "");
+  const plain = (segment) => /^[\p{L}\p{N}_&-][\p{L}\p{N}_&.-]*$/u.test(segment) && Buffer.byteLength(`${segment}.mdx`) <= 255;
+  return value && value.split("/").every(plain) ? value : void 0;
+}
+function createEndpointPageLedger(pages) {
+  return { owners: new Map(pages.map((page) => [page.id.toLowerCase(), { id: page.id, operation: null }])), duplicates: [], unnamed: [] };
+}
+function reportEndpointPages(ledger, warnings) {
+  const names = (urls) => `${urls.slice(0, 10).join(", ")}${urls.length > 10 ? ", ..." : ""}`;
+  if (ledger.duplicates.length > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      message: `${ledger.duplicates.length} Mintlify endpoint URL${ledger.duplicates.length === 1 ? " is" : "s are"} shared by more than one operation (same tag and summary), so only the first operation has a page at each: ${names(ledger.duplicates.map((url) => `/${url}`))}.`
+    });
+  }
+  if (ledger.unnamed.length > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      message: `${ledger.unnamed.length} listed operation${ledger.unnamed.length === 1 ? " has" : "s have"} no page because ${ledger.unnamed.length === 1 ? "its" : "their"} tag or title leaves no usable page name: ${names(ledger.unnamed)}.`
+    });
+  }
+}
+function endpointDescription(description, title) {
+  const text3 = (description ?? "").split(/\r?\n\s*\r?\n/, 1)[0].replace(/<[^>]*>/g, " ").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/[`*~]|__/g, "").replace(/^\s*#+\s*/, "").replace(/\s+/g, " ").trim();
+  const sentence = /^(.+?[.!?])(?=\s|$)/.exec(text3)?.[1] ?? text3;
+  const limited = sentence.length > 300 ? `${sentence.slice(0, 297).replace(/\s+\S*$/, "")}...` : sentence;
+  return limited || title;
+}
+function insertEndpointTab(tabs, tab, preceding) {
+  if (preceding.length === 0) {
+    tabs.unshift(tab);
+    return;
+  }
+  for (const label of preceding) {
+    const index = tabs.findIndex((candidate) => candidate.tab === label);
+    if (index !== -1) {
+      tabs.splice(index + 1, 0, tab);
+      return;
+    }
+  }
+  tabs.push(tab);
+}
+function addEndpointPages(options) {
+  const { tabs, pages, ledger, spec } = options;
+  const operations = parseOpenApiOperationsForLinking(spec.content);
+  if (operations.length === 0) return null;
+  const existing = spec.tabLabel ? tabs.find((tab) => tab.tab === spec.tabLabel) : tabs.find((tab) => !tab.hidden && tab.tab.toLowerCase().includes("api"));
+  if (existing?.api) return null;
+  const byKey = new Map(operations.map((operation) => [`${operation.method} ${operation.path}`, operation]));
+  const listed = [];
+  const pageFor = (reference) => {
+    const [method, ...path] = reference.trim().split(/\s+/);
+    const operation = byKey.get(`${method.toLowerCase()} ${path.join(" ")}`);
+    if (!operation) return void 0;
+    const key = `${operation.method.toUpperCase()} ${operation.path}`;
+    const endpoint = mintlifyEndpointUrl(spec.target.directory, operation);
+    if (!endpoint.tag || !endpoint.leaf || Buffer.byteLength(`${endpoint.tag}.mdx`) > 255 || Buffer.byteLength(`${endpoint.leaf}.mdx`) > 255) {
+      if (!ledger.unnamed.includes(key)) ledger.unnamed.push(key);
+      return void 0;
+    }
+    const identity = `${spec.assetPath} ${key}`;
+    const owner = ledger.owners.get(endpoint.url.toLowerCase());
+    if (owner && owner.operation !== null && owner.operation !== identity) {
+      if (!ledger.duplicates.includes(endpoint.url)) ledger.duplicates.push(endpoint.url);
+      return void 0;
+    }
+    if (!owner) {
+      pages.push({
+        id: endpoint.url,
+        navigationId: endpoint.url,
+        title: endpoint.title,
+        description: endpointDescription(operation.description, endpoint.title),
+        // The summary belongs to metadata; keep full spec prose in the safe
+        // operation Markdown renderer rather than copying it into executable MDX.
+        descriptionPlacement: "operation",
+        keywords: [],
+        body: "",
+        source: "docs.json",
+        openapi: `${spec.assetPath} ${key}`
+      });
+      ledger.owners.set(endpoint.url.toLowerCase(), { id: endpoint.url, operation: identity });
+    }
+    listed.push(key);
+    return owner?.id ?? endpoint.url;
+  };
+  const convert2 = (nodes) => nodes.flatMap((node) => {
+    if (typeof node === "string") {
+      const id = pageFor(node);
+      return id ? [id] : [];
+    }
+    const pagesOf = convert2(node.pages);
+    return pagesOf.length > 0 ? [{ group: node.group, ...node.icon ? { icon: node.icon } : {}, pages: pagesOf }] : [];
+  });
+  const groups = convert2(spec.groups);
+  if (groups.length === 0) return null;
+  if (existing) {
+    if (existing.groups || !existing.pages) existing.groups = [...existing.groups ?? [], ...groups];
+    else existing.pages = [...existing.pages, ...groups];
+  } else {
+    const { slot } = spec.target;
+    const tab = {
+      ...slot?.tab ?? { tab: spec.tabLabel ?? "API Reference", ...spec.icon ? { icon: spec.icon } : {}, ...spec.hidden ? { hidden: true } : {} },
+      groups
+    };
+    if (slot) insertEndpointTab(tabs, tab, slot.preceding);
+    else insertApiTab(tabs, tab, spec.parentTab);
+  }
+  if (!tabs.some((tab) => tab.api?.source === spec.assetPath)) {
+    insertApiTab(tabs, { tab: `OpenAPI: ${spec.source}`, hidden: true, api: { source: spec.assetPath } });
+  }
+  return { operations: listed };
+}
+function specLookupOrder(tabs, versions = []) {
+  const collected = (tab) => !tab.hidden || Boolean(tab.version && versions.some((version) => version.label === tab.version));
+  const sources = [...tabs.filter(collected), ...tabs.filter((tab) => !collected(tab))].flatMap((tab) => tab.api ? [tab.api.source] : []);
+  return [...new Set(sources)];
+}
+function publishedOperationKeys(content) {
+  const document = readSpecDocument(content);
+  const table = (field) => visibleOperations(document, isRecord2(document) ? document[field] : void 0);
+  return /* @__PURE__ */ new Set([
+    ...table("paths").map((operation) => `${operation.method} ${operation.path}`),
+    ...table("webhooks").map((operation) => `webhook ${operation.path}`)
+  ]);
+}
+function qualifyDisplacedBareRefs(options) {
+  const { pages, before, after, content, qualifier } = options;
+  if (before.join("\n") === after.join("\n")) return;
+  const published = /* @__PURE__ */ new Map();
+  const firstPublishing = (order, key) => order.find((source) => {
+    if (!published.has(source)) published.set(source, publishedOperationKeys(content(source) ?? Buffer.alloc(0)));
+    return published.get(source).has(key);
+  });
+  for (const page of pages) {
+    const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;
+    if (!ref || ref.specRef) continue;
+    const [method, ...rest] = ref.operation.trim().split(/\s+/);
+    const key = `${method.toLowerCase()} ${rest.join(" ")}`;
+    const reached = firstPublishing(before, key);
+    if (reached !== void 0 && reached !== firstPublishing(after, key)) page.openapi = withSpecRef(ref, qualifier(reached));
+  }
+}
 function rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings, answered = {}) {
   if (operationLinks.size === 0 && prefixLandings.size === 0) return;
   const unmatched = /* @__PURE__ */ new Set();
@@ -13878,6 +14167,7 @@ function migrateRepository(options) {
   const referenceOrder = /* @__PURE__ */ new Map();
   let docusaurusSidebars = null;
   let mintlifyConfig = null;
+  let mintlifyApiTabSlots = [];
   const mintlifyNavigationAccess = /* @__PURE__ */ new Map();
   let fernRawConfig = null;
   let fernBasePath = "";
@@ -13922,6 +14212,7 @@ function migrateRepository(options) {
           }
         });
         docsConfig = projected.docsConfig;
+        mintlifyApiTabSlots = projected.apiTabSlots;
         warnings.push(...projected.warnings);
         for (const repo of projected.gatedSourceRefs) gatedSourceRepos.add(repo.toLowerCase());
         for (const appearance of projected.referenceAccess) {
@@ -15029,7 +15320,8 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       warnings.push({ code: "gated-page", message: sharedSpecMessage(path, excluded), source: path });
     };
     const nameSpec = createSpecAssetNamer();
-    const allSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs, nameSpec, pages.filter((page) => !restrictedPages.has(page)));
+    const generatedEndpointPages = /* @__PURE__ */ new Set();
+    const allSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs, nameSpec, pages.filter((page) => !restrictedPages.has(page)), mintlifyApiTabSlots);
     const navigation = navigationSpecContext(mintlifyConfig, (path) => resolvePageIdentity(path)?.id ?? null);
     const defaultSources = /* @__PURE__ */ new Set([
       ...allSpecs.filter((spec) => !spec.pageOnly && spec.tabLabel === void 0).map((spec) => spec.sourcePath),
@@ -15072,12 +15364,61 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
         spec.pageReferenced = namedByPages.has(spec);
         spec.generatedNavigation = Boolean(spec.directory) && !publishedSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, true));
       }
-      docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs, warnings);
+      const listingSpecs = resolvedSpecs.filter((spec) => spec.groups && spec.endpointPages);
+      const unbound = docsConfig;
+      docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs.filter((spec) => !listingSpecs.includes(spec)), warnings);
+      const ledger = createEndpointPageLedger(pages);
+      const tabs = docsConfig.tabs.map((tab) => ({ ...tab }));
+      const pagesBefore = pages.length;
+      const endpointSpecs = /* @__PURE__ */ new Set();
+      for (const spec of listingSpecs) {
+        if (!spec.groups || !spec.endpointPages) continue;
+        const added = addEndpointPages({
+          tabs,
+          pages,
+          ledger,
+          spec: {
+            assetPath: specAssetPath(spec.filename),
+            source: spec.sourcePath,
+            content: spec.content,
+            groups: spec.groups,
+            target: spec.endpointPages,
+            tabLabel: spec.tabLabel,
+            parentTab: spec.parentTab,
+            icon: spec.icon,
+            hidden: spec.hidden
+          }
+        });
+        if (!added) continue;
+        spec.endpointOperations = added.operations;
+        endpointSpecs.add(spec);
+      }
+      reportEndpointPages(ledger, warnings);
+      for (const spec of resolvedSpecs) if (spec.directoryWarning && !endpointSpecs.has(spec)) warnings.push(spec.directoryWarning);
+      for (const page of pages.slice(pagesBefore)) generatedEndpointPages.add(page);
+      docsConfig = injectOpenApiSpecs({ ...docsConfig, tabs }, listingSpecs.filter((spec) => !endpointSpecs.has(spec)), warnings);
+      if (remoteApiSpecs.length === 0 && endpointSpecs.size > 0) {
+        const bySource = new Map(resolvedSpecs.map((spec) => [specAssetPath(spec.filename), spec]));
+        qualifyDisplacedBareRefs({
+          pages,
+          before: specLookupOrder(injectOpenApiSpecs(unbound, resolvedSpecs).tabs, docsConfig.navigation?.versions),
+          after: specLookupOrder(docsConfig.tabs, docsConfig.navigation?.versions),
+          content: (source) => bySource.get(source)?.content,
+          qualifier: (source) => bySource.get(source)?.sourcePath ?? source
+        });
+      }
+      const mountOf = (spec) => endpointSpecs.has(spec) ? { prefix: spec.endpointPages?.directory, operations: spec.endpointOperations } : { prefix: spec.directory };
       if (remoteApiSpecs.length > 0) {
-        localApiMounts.push(...resolvedSpecs.flatMap((spec) => spec.directory ? [{ filename: spec.filename, directory: spec.directory, ...spec.tabLabel ? { tab: spec.tabLabel } : {} }] : []));
+        localApiMounts.push(...resolvedSpecs.flatMap((spec) => {
+          const { prefix, operations } = mountOf(spec);
+          return prefix ? [{ filename: spec.filename, directory: prefix, ...spec.tabLabel ? { tab: spec.tabLabel } : {}, ...operations ? { endpointOperations: operations } : {} }] : [];
+        }));
       } else {
         const endpointRedirects = linkApiMounts(
-          resolvedSpecs.map((spec) => ({ filename: spec.filename, content: spec.content, prefix: spec.directory, ...spec.tabLabel ? { tab: spec.tabLabel } : {} })),
+          resolvedSpecs.map((spec) => {
+            const { prefix, operations } = mountOf(spec);
+            return { filename: spec.filename, content: spec.content, prefix, ...operations ? { endpointPages: true, operations } : {}, ...spec.tabLabel ? { tab: spec.tabLabel } : {} };
+          }),
           docsConfig,
           pages,
           warnings
@@ -15134,7 +15475,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       }
       return sameName ? "the file could not be read as an OpenAPI document" : `no file exists at "${key}"`;
     };
-    rewriteMintlifyPageSpecRefs(pages, pageSpecs, new Set(remoteApiSpecs.map((spec) => spec.url)), warnings, explainMissingSpec);
+    rewriteMintlifyPageSpecRefs(pages.filter((page) => !generatedEndpointPages.has(page)), pageSpecs, new Set(remoteApiSpecs.map((spec) => spec.url)), warnings, explainMissingSpec);
     if (docsConfig.tabs.some((tab) => tab.api)) docsConfig = { ...docsConfig, api: { ...docsConfig.api, specLink: false } };
   }
   if (platform === "mintlify") {
@@ -15356,6 +15697,24 @@ ${body}`;
   if (docsConfig.redirects) {
     docsConfig = dropConflictingRedirects(dropUnroutableRedirects(docsConfig, warnings), [...pages, ...sourceRefPages], warnings);
   }
+  const redirectSources = new Map((docsConfig.redirects ?? []).map((redirect) => [(redirect.source.replace(/\/+$/, "") || "/").toLowerCase(), redirect.destination]));
+  const linkRedirects = [];
+  for (const page of [...pages, ...sourceRefPages]) {
+    if (!page.externalUrl) continue;
+    for (const source of pageEntryRoutes(page)) {
+      const existing = redirectSources.get(source.toLowerCase());
+      if (existing !== void 0) {
+        warnings.push({
+          code: "unsupported-config",
+          message: `Page "${page.id}" links to ${stripControlCharacters(page.externalUrl)}, but "${source}" already redirects to ${stripControlCharacters(existing)}; that redirect was kept, so "${source}" does not open the link.`
+        });
+        continue;
+      }
+      redirectSources.set(source.toLowerCase(), page.externalUrl);
+      linkRedirects.push({ source, destination: page.externalUrl, permanent: false });
+    }
+  }
+  if (linkRedirects.length > 0) docsConfig = { ...docsConfig, redirects: [...docsConfig.redirects ?? [], ...linkRedirects] };
   if (pages.length === 0) {
     const reasons = warnings.map((warning) => warning.message);
     throw new Error(reasons.length ? `No importable Markdown or MDX pages were found in the repository. Warnings encountered during migration:
@@ -15439,7 +15798,7 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     });
   }
   if (!docsConfig.navigation?.display && docsConfig.tabs.filter((tab) => !tab.hidden).length > 6) {
-    docsConfig = { ...docsConfig, navigation: { display: "dropdown" } };
+    docsConfig = { ...docsConfig, navigation: { display: "dropdown", ...docsConfig.navigation?.groupHeadings ? { groupHeadings: docsConfig.navigation.groupHeadings } : {} } };
   }
   const themeColors = mintlifyConfig ? mintlifyThemeColors(mintlifyConfig.colors) : fernRawConfig ? fernThemeColors(fernRawConfig.colors) ?? (fernRawConfig["global-theme"] === "nvidia" ? { primary: "#76B900" } : void 0) : isTopLevelDocusaurus ? presentation?.colors ?? readDocusaurusThemeColor(docusaurusProjectRoot) : void 0;
   const assetPaths = new Set(assets.map((asset) => asset.path));
@@ -15635,7 +15994,7 @@ function renderPage(bundle, page) {
     page.icon ? `icon: ${yamlString(page.icon)}` : null,
     page.iconType ? `iconType: ${yamlString(page.iconType)}` : null,
     `description: ${yamlString(page.description)}`,
-    page.descriptionPlacement === "body" ? "descriptionPlacement: body" : null,
+    page.descriptionPlacement === "body" || page.descriptionPlacement === "operation" ? `descriptionPlacement: ${page.descriptionPlacement}` : 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,
@@ -18164,6 +18523,12 @@ function slug(value) {
 function operationTarget(specId, operation) {
   return `/api/${specId}/${thallyOperationSlugSegments(operation.path, operation.method).join("/")}`;
 }
+function bindApiTab(tabs, reference, api) {
+  const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
+  if (tab) tab.api = api;
+  else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api }, reference.parentTab);
+  return tab?.tab ?? reference.tabLabel ?? "API Reference";
+}
 async function hydrateRemoteApiSpecs(bundle, fetcher) {
   if (!bundle.remoteApiSpecs?.length) return bundle;
   const assets = [...bundle.assets];
@@ -18172,7 +18537,8 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
   const warnings = [...bundle.warnings];
   const pages = bundle.pages.map((page) => ({ ...page }));
   const authoredLinks = /* @__PURE__ */ new Set();
-  const served = servedRoutes(pages);
+  const ledger = createEndpointPageLedger(pages);
+  const pagesBefore = pages.length;
   const endpointUrls = /* @__PURE__ */ new Map();
   for (const page of bundle.pages) {
     for (const match of page.body.matchAll(/\/[a-z0-9_/-]+/gi)) {
@@ -18183,6 +18549,10 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
     }
   }
   const bound = [];
+  const apiTabs = bundle.docsConfig.tabs.map((tab) => ({ ...tab }));
+  for (const mount of bundle.localApiMounts ?? []) {
+    if (mount.endpointOperations) bindApiTab(apiTabs, { tabLabel: mount.tab }, { source: `openapi/${mount.filename}` });
+  }
   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);
@@ -18202,11 +18572,29 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
         const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;
         if (ref?.specRef === reference.url) page.openapi = withSpecRef(ref, `openapi/${filename}`);
       }
-      const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
+      bindApiTab(apiTabs, reference, { source: `openapi/${filename}` });
+      const endpoint = reference.groups && reference.endpointPages ? addEndpointPages({
+        tabs,
+        pages,
+        ledger,
+        spec: {
+          assetPath: `openapi/${filename}`,
+          source: reference.url,
+          content: body,
+          groups: reference.groups,
+          target: reference.endpointPages,
+          tabLabel: reference.tabLabel,
+          parentTab: reference.parentTab,
+          icon: reference.icon,
+          hidden: reference.hidden
+        }
+      }) : null;
+      if (endpoint) {
+        bound.push({ reference, filename, content: body, operations, tabName: reference.tabLabel ?? "API Reference", endpointOperations: endpoint.operations });
+        continue;
+      }
       const api = { source: `openapi/${filename}`, ...reference.navigation === false ? { navigation: false } : {}, ...reference.groups ? { groups: reference.groups } : {} };
-      if (tab) tab.api = api;
-      else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api }, reference.parentTab);
-      bound.push({ reference, filename, content: body, operations, tabName: tab?.tab ?? reference.tabLabel ?? "API Reference" });
+      bound.push({ reference, filename, content: body, operations, tabName: bindApiTab(tabs, reference, api) });
     } catch (error) {
       warnings.push({
         code: "fetch-failed",
@@ -18215,19 +18603,22 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
       });
     }
   }
+  const pageMounts = bound.flatMap(({ reference, endpointOperations }) => endpointOperations && reference.endpointPages ? [reference.endpointPages.directory] : []);
   const directories = [
     ...(bundle.localApiMounts ?? []).map(({ directory: directory2 }) => directory2),
-    ...bundle.remoteApiSpecs.flatMap((reference) => (reference.directories ?? []).map(({ directory: directory2 }) => directory2))
+    ...bundle.remoteApiSpecs.flatMap((reference) => (reference.directories ?? []).map(({ directory: directory2 }) => directory2)),
+    ...pageMounts
   ];
   const endpointRedirects = linkApiMounts(
     [
-      ...(bundle.localApiMounts ?? []).map(({ filename, directory: directory2, tab }) => ({
+      ...(bundle.localApiMounts ?? []).map(({ filename, directory: directory2, tab, endpointOperations }) => ({
         filename,
         content: Buffer.from(assets.find((asset) => asset.path === `openapi/${filename}`)?.content ?? []),
         prefix: directory2,
+        ...endpointOperations ? { endpointPages: true, operations: endpointOperations } : {},
         ...tab ? { tab } : {}
       })),
-      ...bound.flatMap(({ reference, filename, content, tabName }) => (reference.directories ?? []).map(({ directory: directory2, operations: listed }) => ({ filename, content, prefix: directory2, tab: tabName, ...listed ? { operations: listed } : {} })))
+      ...bound.flatMap(({ reference, filename, content, tabName, endpointOperations }) => endpointOperations && reference.endpointPages ? [{ filename, content, prefix: reference.endpointPages.directory, tab: tabName, endpointPages: true, operations: endpointOperations }] : (reference.directories ?? []).map(({ directory: directory2, operations: listed }) => ({ filename, content, prefix: directory2, tab: tabName, ...listed ? { operations: listed } : {} })))
     ],
     { ...bundle.docsConfig, tabs, redirects },
     pages,
@@ -18238,6 +18629,18 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
     redirects.push(redirect);
     endpointUrls.set(literalRoute(redirect.source) ?? redirect.source, redirect.destination);
   }
+  reportEndpointPages(ledger, warnings);
+  qualifyDisplacedBareRefs({
+    pages,
+    before: specLookupOrder(apiTabs, bundle.docsConfig.navigation?.versions),
+    after: specLookupOrder(tabs, bundle.docsConfig.navigation?.versions),
+    content: (source) => {
+      const asset = assets.find((entry) => entry.path === source);
+      return asset ? Buffer.from(asset.content) : void 0;
+    },
+    qualifier: (source) => source
+  });
+  const served = servedRoutes(pages);
   const existingSources = new Set(redirects.map((redirect) => literalRoute(redirect.source) ?? redirect.source.toLowerCase()));
   const mounts = directories.map(mountPrefix).filter(Boolean);
   const underMount = (source) => mounts.some((prefix) => source.toLowerCase() === `/${prefix}` || source.toLowerCase().startsWith(`/${prefix}/`));
@@ -18262,12 +18665,19 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
     const endpoint = endpointUrls.get(literalRoute(redirect.destination) ?? "");
     return endpoint ? { ...redirect, destination: endpoint } : redirect;
   });
+  const boundConfig = { ...bundle.docsConfig, tabs, ...direct.length > 0 ? { redirects: direct } : {} };
+  const newPages = pages.slice(pagesBefore);
+  const withDirectories = bundle.platform === "mintlify" && newPages.length > 0 ? addMintlifyDirectoryRedirects(boundConfig, newPages) : boundConfig;
+  const linkRedirects = new Set(pages.flatMap((page) => page.externalUrl ? pageEntryRoutes(page).map((source) => `${source} ${page.externalUrl}`) : []));
+  const isLinkRedirect = (redirect) => linkRedirects.has(`${redirect.source} ${redirect.destination}`);
+  const links = (withDirectories.redirects ?? []).filter(isLinkRedirect);
+  const unchecked = links.length > 0 ? { ...withDirectories, redirects: withDirectories.redirects.filter((redirect) => !isLinkRedirect(redirect)) } : withDirectories;
+  const checked = dropConflictingRedirects(dropUnroutableRedirects(unchecked, warnings), pages, warnings);
   return {
     ...bundle,
     pages,
     assets,
-    // Redirects added above meet the same checks as any other: none may fail the build, hide a page that exists, or loop.
-    docsConfig: dropConflictingRedirects(dropUnroutableRedirects({ ...bundle.docsConfig, tabs, ...direct.length > 0 ? { redirects: direct } : {} }, warnings), pages, warnings),
+    docsConfig: links.length > 0 ? { ...checked, redirects: [...checked.redirects ?? [], ...links] } : checked,
     warnings
   };
 }