@thallylabs/migrate 0.2.18 → 0.2.21

package/README.md

@@ -40,6 +40,13 @@ instead of silently dropping that API tab's reference. AsyncAPI has no Thally
 renderer, so it always produces a clear warning naming the spec instead of
 disappearing.
 
+Page `openapi:` frontmatter with a spec prefix
+(`openapi: "specs/openapi-b.yaml GET /widgets/{id}"`) is rewritten to where the
+spec lands in the output (`/openapi-b.yaml GET /widgets/{id}`). A prefix naming
+a spec that was not migrated is kept and reported. Manual API pages keep their
+`api:` and `authMethod:` frontmatter, and `api.mdx.server` / `api.mdx.auth` map
+into `docs.json`; invalid values are dropped with a warning.
+
 In-content links to auto-generated API operation pages are rewritten to the
 matching Thally `/api/...` route. A link under a known API section that matches
 no operation points to that section's overview page instead, and one warning

package/dist/index.d.ts

@@ -128,6 +128,16 @@ interface MigrationDocsConfig {
     analytics?: {
         enabled?: boolean;
     };
+    /** Manual API pages: default server(s) and auth for `api:` frontmatter pages. */
+    api?: {
+        mdx?: {
+            server?: string | Array<string>;
+            auth?: {
+                method?: 'bearer' | 'basic' | 'key';
+                name?: string;
+            };
+        };
+    };
     /** Third-party analytics in Mintlify's `integrations` shape; validated again by the renderer. */
     integrations?: {
         ga4?: {
@@ -179,6 +189,10 @@ interface MigrationPage {
     noindex?: boolean;
     /** OpenAPI operation key rendered by Thally instead of ordinary MDX. */
     openapi?: string;
+    /** Manual API page: `METHOD <url-or-path>`; rendered by Thally's playground. */
+    api?: string;
+    /** Page-level playground auth override: bearer | basic | key | none. */
+    authMethod?: string;
     body: string;
     source: string;
     /** Set when the page's frontmatter was invalid YAML; the page is kept with a best-effort salvage. */
@@ -463,6 +477,8 @@ declare function parseMarkdownPage(input: {
     platform?: MigrationPlatform;
     /** Resolve platform-specific routes from the already-parsed frontmatter. */
     resolveIdentity?: (frontmatter: Record<string, unknown>, fallback: MarkdownPageIdentity) => MarkdownPageIdentity;
+    /** Receives a message when frontmatter is dropped or altered. */
+    warn?: (message: string) => void;
 }): MigrationPage | null;
 
 /**

package/dist/index.js

@@ -263,7 +263,8 @@ function unwrapDocusaurusMdxCodeBlocks(body) {
   }
   return isMdxCodeBlock ? body : output.join("\n");
 }
-function normalizeExplicitHeadingIds(raw) {
+var HTML_ID = /^[^\s"'<>`{}&]+$/u;
+function normalizeExplicitHeadingIds(raw, warn) {
   const { front, body } = splitFrontmatterBlock(raw);
   return front + replaceOutsideCode(body, (segment) => segment.split("\n").map((line) => {
     if (!/^[ \t]{0,3}#{1,6}[ \t]+/.test(line)) return line;
@@ -272,10 +273,12 @@ function normalizeExplicitHeadingIds(raw) {
       const marker = trimmed.lastIndexOf(" {#");
       if (marker >= 0) {
         const id = trimmed.slice(marker + 3, -1);
-        if (/^[A-Za-z][A-Za-z0-9_-]*$/.test(id)) {
-          return `<a id="${id}"></a>
-${trimmed.slice(0, marker).trimEnd()}`;
-        }
+        const heading = trimmed.slice(0, marker).trimEnd();
+        if (/[{}]/.test(id)) return line;
+        if (HTML_ID.test(id)) return `<a id="${id}"></a>
+${heading}`;
+        warn?.(`Heading anchor {#${id}} is not a valid HTML id and was removed from "${heading.replace(/^\s*#+\s*/, "")}".`);
+        return heading;
       }
     }
     if (trimmed.endsWith("*/}")) {
@@ -283,7 +286,7 @@ ${trimmed.slice(0, marker).trimEnd()}`;
       if (marker >= 0) {
         const comment = trimmed.slice(marker + 4, -3).trim();
         const id = comment.startsWith("#") ? comment.slice(1) : "";
-        if (/^[A-Za-z][A-Za-z0-9_.:-]*$/.test(id)) {
+        if (HTML_ID.test(id)) {
           return `<a id="${id}"></a>
 ${trimmed.slice(0, marker).trimEnd()}`;
         }
@@ -671,13 +674,25 @@ function maskCode(body) {
   if (fenceBuffer.length) lines.push(stash(fenceBuffer.join("\n")));
   return {
     masked: lines.join("\n"),
-    unmask: (text2) => text2.replace(/\u0000(\d+)\u0000/g, (_match, index) => blocks[Number(index)])
+    unmask: (text2) => text2.replace(/\u0000(\d+)\u0000/g, (_match, index) => blocks[Number(index)]),
+    openFence: codeFence
   };
 }
+function closeOpenFence(body) {
+  const { openFence } = maskCode(body);
+  return openFence ? `${body}${body.endsWith("\n") ? "" : "\n"}${openFence}
+` : body;
+}
 function replaceOutsideCode(body, transform) {
   const { masked, unmask } = maskCode(body);
   return unmask(transform(masked));
 }
+function mdxComment(text2) {
+  return `{/*${text2.replace(/\*\//g, "* /")}*/}`;
+}
+function replaceOutsideCodeAndComments(body, transform) {
+  return replaceOutsideCode(body, (masked) => masked.split(/(\{\s*\/\*[\s\S]*?\*\/\s*\})/).map((part, index) => index % 2 ? part : transform(part)).join(""));
+}
 function rewriteFernRelativePageLinks(body, currentSourcePath, routesBySourcePath) {
   const rewrite = (target) => {
     if (!target || target.startsWith("/") || target.startsWith("#") || target.startsWith("?") || target.includes("\\") || /[\u0000-\u001f\u007f]/.test(target) || /^[A-Za-z][A-Za-z\d+.-]*:/.test(target)) return target;
@@ -739,7 +754,7 @@ function normalizeFernFileTrees(body) {
   ));
 }
 function normalizeHtmlComments(body) {
-  return replaceOutsideCode(body, (whole) => whole.replace(/<!--([\s\S]*?)-->/g, (_match, comment) => `{/*${comment}*/}`));
+  return replaceOutsideCode(body, (whole) => whole.replace(/<!--([\s\S]*?)-->/g, (_match, comment) => mdxComment(comment)));
 }
 function normalizeFernCallouts(body) {
   return replaceOutsideCode(body, (whole) => {
@@ -1230,7 +1245,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) => `{/*${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(/<Check(\s[^>]*)?>/g, "<Note$1>").replace(/<\/Check>/g, "</Note>").replace(/<Tree\.Folder/g, "<Folder").replace(/<\/Tree\.Folder>/g, "</Folder>").replace(/<Tree\.File/g, "<File").replace(/<\/Tree\.File>/g, "</File>");
     if (runDocusaurus) {
       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";
@@ -1290,11 +1305,26 @@ function parseMarkdownPage(input) {
     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,
+    ...apiFrontmatter(parsed.data, input.warn),
     body,
     source: input.source,
     ...parsed.error ? { frontmatterError: parsed.error } : {}
   };
 }
+var AUTH_METHODS = /* @__PURE__ */ new Set(["bearer", "basic", "key", "none"]);
+function apiFrontmatter(data, warn) {
+  const result = {};
+  if (data.api !== void 0 && data.api !== null) {
+    if (typeof data.api === "string" && data.api.trim()) result.api = data.api.trim();
+    else warn?.(`The page's "api" frontmatter is not a "METHOD url-or-path" string and was dropped.`);
+  }
+  if (data.authMethod !== void 0 && data.authMethod !== null) {
+    const method = typeof data.authMethod === "string" ? data.authMethod.trim().toLowerCase() : "";
+    if (AUTH_METHODS.has(method)) result.authMethod = method;
+    else warn?.(`The page's "authMethod" frontmatter ${JSON.stringify(data.authMethod)} is not one of bearer, basic, key, none and was dropped.`);
+  }
+  return result;
+}
 
 // src/path.ts
 import { isAbsolute, relative, resolve, sep } from "path";
@@ -2365,7 +2395,8 @@ function neutralizeUnresolvableImportsWithoutAst(content, currentFile, warn) {
   });
   for (const { name, specifier } of dropped) {
     warn(`Component import ${JSON.stringify(specifier)} could not be resolved because this page has invalid MDX (see the previous warning), so the import and its usage were removed to keep the site building.`, currentFile);
-    result = result.replace(new RegExp(`<${name}(?:\\s[^>]*)?/>`, "g"), `{/* Removed <${name}>: unresolved during fallback migration */}`).replace(new RegExp(`<${name}(?:\\s[^>]*)?>[\\s\\S]*?<\\/${name}>`, "g"), `{/* Removed <${name}>: unresolved during fallback migration */}`);
+    const removed = mdxComment(` Removed <${name}>: unresolved during fallback migration `);
+    result = replaceOutsideCodeAndComments(result, (segment) => segment.replace(new RegExp(`<${name}(?:\\s[^>]*)?/>`, "g"), removed).replace(new RegExp(`<${name}(?:\\s[^>]*)?>[\\s\\S]*?<\\/${name}>`, "g"), removed));
   }
   return result;
 }
@@ -3028,7 +3059,7 @@ ${inlineSource}` });
       const start = node.position.start.offset;
       const end = node.position.end.offset;
       const videoId = youtubeEmbedVideoId(node, specifier);
-      const value = videoId ? `<iframe width="560" height="315" src="https://www.youtube.com/embed/${videoId}" title="Embedded video" allowFullScreen />` : `{/* Removed <${node.name}>: unsupported import '${specifier}' */}`;
+      const value = videoId ? `<iframe width="560" height="315" src="https://www.youtube.com/embed/${videoId}" title="Embedded video" allowFullScreen />` : mdxComment(` Removed <${node.name}>: unsupported import '${specifier}' `);
       edits.push({ start, end, value });
     });
     const rendered = applyReplacements(content, edits);
@@ -3906,6 +3937,39 @@ function projectedCompatibleConfig(config, warnings) {
     ...typeof feedback?.thumbsRating === "boolean" ? { feedback: { thumbsRating: feedback.thumbsRating } } : {}
   };
 }
+function projectedApiMdx(config, warnings) {
+  const mdx = objectValue2(objectValue2(config.api)?.mdx);
+  if (!mdx) return {};
+  const warn = (message) => warnings.push({ code: "unsupported-config", message });
+  const rawServers = mdx.server === void 0 ? [] : Array.isArray(mdx.server) ? mdx.server : [mdx.server];
+  const servers = rawServers.filter((entry) => {
+    const valid = typeof entry === "string" && /^https?:\/\/[^\s/@?#]+(?:\/[^\s?#]*)?$/i.test(entry.trim());
+    if (!valid) warn(`api.mdx.server entry ${JSON.stringify(entry)} is not an absolute http(s) URL and was dropped.`);
+    return valid;
+  }).map((entry) => entry.trim());
+  const auth = objectValue2(mdx.auth);
+  const method = typeof auth?.method === "string" ? auth.method.toLowerCase() : void 0;
+  const name = typeof auth?.name === "string" && auth.name.trim() ? auth.name.trim() : void 0;
+  let projectedAuth;
+  if (mdx.auth !== void 0 && auth && method !== void 0) {
+    if (method === "bearer" || method === "basic" || method === "key" && name) {
+      projectedAuth = { method, ...name ? { name } : {} };
+    } else {
+      warn(`api.mdx.auth method ${JSON.stringify(auth.method)} is not supported (bearer, basic, or key with a name) and was dropped.`);
+    }
+  } else if (mdx.auth !== void 0 && !auth) {
+    warn("api.mdx.auth is not an object and was dropped.");
+  }
+  if (servers.length === 0 && !projectedAuth) return {};
+  return {
+    api: {
+      mdx: {
+        ...servers.length > 0 ? { server: servers.length === 1 && typeof mdx.server === "string" ? servers[0] : servers } : {},
+        ...projectedAuth ? { auth: projectedAuth } : {}
+      }
+    }
+  };
+}
 var NEXT_REDIRECT_PARAM_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function translateRedirectWildcards(source, destination) {
   const sourceSegments = source.split("/");
@@ -4093,6 +4157,7 @@ function projectMintlifyNavigation(config, options = {}) {
       tabs,
       ...projectionTrace.rootContainerKind === "dropdowns" ? { navigation: { display: "dropdown" } } : {},
       ...projectedCompatibleConfig(config, warnings),
+      ...projectedApiMdx(config, warnings),
       ...i18n ? { i18n } : {},
       ...redirects.length > 0 ? { redirects } : {}
     },
@@ -5661,6 +5726,26 @@ function projectFernNavigation(input) {
   };
 }
 
+// src/openapi-ref.ts
+function unquote(value) {
+  const trimmed = value.trim();
+  const quote = trimmed[0];
+  return (quote === '"' || quote === "'") && trimmed.length >= 2 && trimmed.endsWith(quote) ? trimmed.slice(1, -1).trim() : trimmed;
+}
+function splitOpenApiRef(raw) {
+  const value = unquote(raw);
+  const match = /^(?:(.+?)\s+)?((?:webhook\s+[^\s/]\S*)|(?:[A-Za-z]+\s+\/.*))$/i.exec(value);
+  if (!match) return null;
+  const specRef = match[1] ? unquote(match[1]) : void 0;
+  return { ...specRef ? { specRef } : {}, operation: match[2] };
+}
+function specRefBaseName(specRef) {
+  return specRef.trim().replace(/\\/g, "/").split(/[?#]/, 1)[0].split("/").filter(Boolean).pop()?.toLowerCase() ?? "";
+}
+function withSpecRef(ref, specRef) {
+  return `${specRef} ${ref.operation}`;
+}
+
 // src/analytics.ts
 var GA4_ID = /^G-[A-Z0-9]{4,20}$/;
 var GTM_ID = /^GTM-[A-Z0-9]{4,12}$/;
@@ -6572,7 +6657,7 @@ function selectGroupWithinBudget(scanned, rank, warnings, allVersionPrefixes, la
   const dropped = ranked.slice(budget).map(({ file }) => file);
   if (warnings) {
     const droppedPages = label === "file" ? dropped.filter((file) => isDocumentationExtension(file.relativePath)) : dropped;
-    const noun = label === "file" ? "page" : "image or media file";
+    const noun = label === "file" ? "page" : label === "snippet" ? "snippet file" : "image or media file";
     const droppedVersions = /* @__PURE__ */ new Set();
     for (const file of dropped) {
       const firstSegment = file.relativePath.split("/", 1)[0];
@@ -6582,16 +6667,19 @@ function selectGroupWithinBudget(scanned, rank, warnings, allVersionPrefixes, la
     const rest = droppedPages.length - examples.length;
     warnings.push({
       code: "limit-reached",
-      message: `This repository has more than ${budget} ${label === "file" ? "files" : "assets"}, so only the first ${budget} (in navigation order, default version first) were migrated. ${droppedPages.length} ${noun}(s) were left out` + (examples.length > 0 ? `: ${examples.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}` : "") + (droppedVersions.size > 0 ? ` (versions: ${[...droppedVersions].slice(0, 5).join(", ")}${droppedVersions.size > 5 ? `, and ${droppedVersions.size - 5} more` : ""})` : "") + (label === "file" ? ". To include them, run the migration on a smaller part of the repository with --docs-dir." : ". Copy them into public/ manually if your pages use them.")
+      message: `This repository has more than ${budget} ${label === "file" ? "files" : label === "snippet" ? "snippets" : "assets"}, so only the first ${budget} (in navigation order, default version first) were migrated. ${droppedPages.length} ${noun}(s) were left out` + (examples.length > 0 ? `: ${examples.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}` : "") + (droppedVersions.size > 0 ? ` (versions: ${[...droppedVersions].slice(0, 5).join(", ")}${droppedVersions.size > 5 ? `, and ${droppedVersions.size - 5} more` : ""})` : "") + (label === "asset" ? ". Copy them into public/ manually if your pages use them." : ". To include them, run the migration on a smaller part of the repository with --docs-dir.")
     });
   }
   return ranked.slice(0, budget).map(({ file }) => file);
 }
 function selectFilesWithinBudget(scanned, rank, warnings, allVersionPrefixes, budget = MAX_SOURCE_FILES) {
   const isAsset = (file) => ASSET_EXTENSIONS.has(extname6(file.relativePath).toLowerCase());
+  const isSnippet = (file) => file.relativePath.split("/").some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase()));
+  const snippetFiles = scanned.filter((file) => !isAsset(file) && isSnippet(file));
   const assetFiles = scanned.filter(isAsset);
-  const otherFiles = scanned.filter((file) => !isAsset(file));
+  const otherFiles = scanned.filter((file) => !isAsset(file) && !isSnippet(file));
   return [
+    ...selectGroupWithinBudget(snippetFiles, rank, warnings, allVersionPrefixes, "snippet", budget),
     ...selectGroupWithinBudget(otherFiles, rank, warnings, allVersionPrefixes, "file", budget),
     ...selectGroupWithinBudget(assetFiles, rank, warnings, allVersionPrefixes, "asset", budget)
   ];
@@ -6792,6 +6880,27 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
   }
   return specs;
 }
+function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings) {
+  for (const page of pages) {
+    const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;
+    if (!ref?.specRef) continue;
+    if (/^https?:\/\//i.test(ref.specRef)) {
+      if (!remoteUrls.has(ref.specRef)) {
+        warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the remote OpenAPI spec "${ref.specRef}", which is not referenced from docs.json and was not migrated; the page will not render an endpoint.`, source: page.source });
+      }
+      continue;
+    }
+    const key = ref.specRef.split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^(?:\.\/)+/, "").replace(/^\/+/, "");
+    const byPath = specs.find((spec) => spec.sourcePath === key);
+    const byName = specs.filter((spec) => spec.filename.toLowerCase() === specRefBaseName(key));
+    const match = byPath ?? (byName.length === 1 ? byName[0] : void 0);
+    if (match) {
+      page.openapi = withSpecRef(ref, specAssetPath(match.filename));
+    } else {
+      warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the OpenAPI spec "${ref.specRef}", which is not referenced from docs.json and was not migrated; the page will not render an endpoint. Add the spec to a tab's api setting.`, source: page.source });
+    }
+  }
+}
 var OPENAPI_HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
 var FERN_CRUD_METHOD_NAMES = {
   findall: "list",
@@ -7069,6 +7178,13 @@ function interpolateSnippet(snippet, attributes, children) {
     });
   }).join("\n");
 }
+function isolateFences(snippet, source, start, end) {
+  const fence = /^\s*(?:`{3,}|~{3,})/;
+  const lines = snippet.split("\n");
+  const before = source.slice(source.lastIndexOf("\n", start - 1) + 1, start);
+  const after = source.slice(end, source.indexOf("\n", end) < 0 ? void 0 : source.indexOf("\n", end));
+  return `${fence.test(lines[0]) && /\S/.test(before) ? "\n" : ""}${snippet}${fence.test(lines[lines.length - 1]) && /\S/.test(after) ? "\n" : ""}`;
+}
 function snippetComponentBody(source, componentName) {
   const parsed = ts3.createSourceFile("snippet.tsx", source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
   for (const statement of parsed.statements) {
@@ -7517,7 +7633,7 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
           message: `Imported snippet ${sourcePath} could not be resolved and was left as a comment.`,
           source: relative5(repositoryRoot, currentFile).replace(/\\/g, "/")
         });
-        snippets.set(componentName, `{/* Missing imported snippet: ${sourcePath} */}`);
+        snippets.set(componentName, mdxComment(` Missing imported snippet: ${sourcePath} `));
         return "";
       }
     }
@@ -7586,48 +7702,49 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
     if (declaration) preservedDeclarations.set(componentName, declaration);
     else snippets.set(componentName, snippetComponentBody(nested, componentName));
   }
-  let result = withoutImports;
-  for (const [componentName, snippet] of snippets) {
-    result = result.replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)\\s*/>`, "g"), (_tag, attributes) => {
-      return interpolateSnippet(snippet, attributes);
-    }).replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)>([\\s\\S]*?)<\\/${componentName}>`, "g"), (_tag, attributes, children) => {
-      return interpolateSnippet(snippet, attributes, children);
-    });
-  }
-  result = result.replace(SNIPPET_TAG_PATTERN, (_tag, doubleQuoted, singleQuoted) => {
-    const filePath = doubleQuoted ?? singleQuoted;
-    try {
-      const candidate = [
-        () => resolveWithin(siteRoot, `snippets/${filePath}`),
-        () => resolveSnippetPath(filePath, currentFile, repositoryRoot, siteRoot)
-      ].map((resolveCandidate) => {
-        try {
-          return resolveCandidate();
-        } catch {
-          return void 0;
-        }
-      }).find((path) => path !== void 0 && existsSync5(path) && lstatSync5(path).isFile());
-      if (!candidate) throw new Error("file not found");
-      const blocked = blockInline(candidate, filePath, `Snippet file="${filePath}"`);
-      if (blocked) return blocked;
-      return inlineMdxSnippets(
-        withoutFrontmatter(readFileSync5(candidate, "utf8")),
-        candidate,
-        repositoryRoot,
-        warnings,
-        depth + 1,
-        siteRoot,
-        globalAliases,
-        gate
-      );
-    } catch {
-      warnings.push({
-        code: "missing-page",
-        message: `Snippet file="${filePath}" could not be resolved and was left as a comment.`,
-        source: relative5(repositoryRoot, currentFile).replace(/\\/g, "/")
+  let result = replaceOutsideCodeAndComments(withoutImports, (segment) => {
+    for (const [componentName, snippet] of snippets) {
+      segment = segment.replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)\\s*/>`, "g"), (tag, attributes, offset, source2) => {
+        return isolateFences(interpolateSnippet(snippet, attributes), source2, offset, offset + tag.length);
+      }).replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)>([\\s\\S]*?)<\\/${componentName}>`, "g"), (tag, attributes, children, offset, source2) => {
+        return isolateFences(interpolateSnippet(snippet, attributes, children), source2, offset, offset + tag.length);
       });
-      return `{/* Missing snippet: ${filePath} */}`;
     }
+    return segment.replace(SNIPPET_TAG_PATTERN, (tag, doubleQuoted, singleQuoted, offset, source2) => {
+      const filePath = doubleQuoted ?? singleQuoted;
+      try {
+        const candidate = [
+          () => resolveWithin(siteRoot, `snippets/${filePath}`),
+          () => resolveSnippetPath(filePath, currentFile, repositoryRoot, siteRoot)
+        ].map((resolveCandidate) => {
+          try {
+            return resolveCandidate();
+          } catch {
+            return void 0;
+          }
+        }).find((path) => path !== void 0 && existsSync5(path) && lstatSync5(path).isFile());
+        if (!candidate) throw new Error("file not found");
+        const blocked = blockInline(candidate, filePath, `Snippet file="${filePath}"`);
+        if (blocked) return blocked;
+        return isolateFences(inlineMdxSnippets(
+          withoutFrontmatter(readFileSync5(candidate, "utf8")),
+          candidate,
+          repositoryRoot,
+          warnings,
+          depth + 1,
+          siteRoot,
+          globalAliases,
+          gate
+        ), source2, offset, offset + tag.length);
+      } catch {
+        warnings.push({
+          code: "missing-page",
+          message: `Snippet file="${filePath}" could not be resolved and was left as a comment.`,
+          source: relative5(repositoryRoot, currentFile).replace(/\\/g, "/")
+        });
+        return mdxComment(` Missing snippet: ${filePath} `);
+      }
+    });
   });
   if (preservedDeclarations.size > 0) {
     const frontmatter = result.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
@@ -7636,7 +7753,7 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
 
 ${result.slice(prefix.length)}`;
   }
-  return depth === 0 ? hoistMdxImports(result) : result;
+  return depth === 0 ? hoistMdxImports(result) : closeOpenFence(result);
 }
 function injectOpenApiSpecs(config, specs, warnings) {
   const tabs = config.tabs.map((tab) => ({ ...tab }));
@@ -8124,7 +8241,7 @@ function migrateRepository(options) {
     const publishedText = trackPublishedRefs ? raw : void 0;
     const pageAssetReferences = [];
     if (platform === "fern" || platform === "mintlify" || platform === "docusaurus") {
-      raw = normalizeExplicitHeadingIds(raw);
+      raw = normalizeExplicitHeadingIds(raw, (message) => warnings.push({ code: "invalid-page", message, source: file.relativePath }));
     }
     if (componentMigrator) {
       const warningsBeforeTransform = warnings.length;
@@ -8159,6 +8276,7 @@ function migrateRepository(options) {
     const page = parseMarkdownPage({
       id,
       navigationId,
+      warn: (message) => warnings.push({ code: "unsupported-config", message, source: relative5(repositoryDir, file.absolutePath).replace(/\\/g, "/") }),
       ...locale ? { locale } : {},
       raw,
       platform,
@@ -8619,6 +8737,7 @@ function migrateRepository(options) {
       }
       if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath);
     }
+    let pageSpecs = resolvedSpecs;
     if (resolvedSpecs.length > 0) {
       docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs, warnings);
       const { operationLinks, prefixLandings } = apiOperationLinkMap(
@@ -8639,10 +8758,12 @@ function migrateRepository(options) {
             assets.push(specAsset(filename, readFileSync5(fallback.absolutePath)));
           }
           docsConfig = injectOpenApiSpecs(docsConfig, [{ filename }]);
+          pageSpecs = [{ filename, sourcePath: fallback.relativePath }];
           if (withheldSpecRefs.some(matches)) warnSharedSpec(fallback.relativePath);
         }
       }
     }
+    rewriteMintlifyPageSpecRefs(pages, pageSpecs, new Set(remoteApiSpecs.map((spec) => spec.url)), warnings);
   }
   if (platform === "mintlify") {
     const sources = new Set((docsConfig.redirects ?? []).map((redirect) => redirect.source));
@@ -9065,6 +9186,8 @@ function renderPage(bundle, page) {
     page.hidden ? "hidden: true" : null,
     page.noindex ? "noindex: true" : null,
     page.openapi ? `openapi: ${yamlString(page.openapi)}` : null,
+    page.api ? `api: ${yamlString(page.api)}` : null,
+    page.authMethod ? `authMethod: ${yamlString(page.authMethod)}` : null,
     bundle.sourceKind === "url" ? `source: ${yamlString(page.source)}` : null,
     "---",
     "",
@@ -10892,6 +11015,7 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
   const tabs = bundle.docsConfig.tabs.map((tab) => ({ ...tab }));
   const redirects = [...bundle.docsConfig.redirects ?? []];
   const warnings = [...bundle.warnings];
+  const pages = bundle.pages.map((page) => ({ ...page }));
   const authoredLinks = /* @__PURE__ */ new Set();
   for (const page of bundle.pages) {
     for (const match of page.body.matchAll(/\/[a-z0-9_/-]+/gi)) {
@@ -10912,6 +11036,10 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
       const operations = parseOpenApi(body, extension);
       const filename = `openapi-${createHash2("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
       assets.push({ path: `openapi/${filename}`, content: body, projectRelative: true });
+      for (const page of pages) {
+        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"));
       if (tab) tab.api = { source: `openapi/${filename}` };
       else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api: { source: `openapi/${filename}` } }, reference.parentTab);
@@ -10940,6 +11068,7 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
   }
   return {
     ...bundle,
+    pages,
     assets,
     docsConfig: { ...bundle.docsConfig, tabs, ...redirects.length > 0 ? { redirects } : {} },
     warnings