@thallylabs/migrate 0.1.2 → 0.2.0

package/dist/index.js

@@ -1,53 +1,18 @@
 // src/repository.ts
 import { spawn } from "child_process";
 import {
-  existsSync as existsSync2,
-  lstatSync,
-  readFileSync as readFileSync2,
+  existsSync as existsSync3,
+  lstatSync as lstatSync2,
+  readFileSync as readFileSync3,
   readdirSync
 } from "fs";
-import { basename, dirname as dirname2, extname as extname2, relative as relative3 } from "path";
+import { basename, dirname as dirname2, extname as extname3, relative as relative3, resolve as resolvePath } from "path";
 
-// src/mdx.ts
-import matter from "gray-matter";
-function titleFromId(id) {
-  const value = id.split("/").at(-1) ?? id;
-  if (value === "introduction") return "Introduction";
-  return value.split(/[-_]/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
-}
-function firstParagraph(content) {
-  for (const block of content.split(/\n\s*\n/)) {
-    const value = block.replace(/\s+/g, " ").trim();
-    if (!value || /^(?:#|```|:::|<|import\s|export\s)/.test(value)) continue;
-    return value.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").slice(0, 240);
-  }
-  return "";
-}
-function normalizeMdx(body) {
-  return body.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>");
-}
-function parseMarkdownPage(input) {
-  const parsed = matter(input.raw);
-  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(input.navigationId ?? input.id);
-  const description = typeof parsed.data.description === "string" && parsed.data.description.trim() ? parsed.data.description.trim() : firstParagraph(body);
-  return {
-    id: input.id,
-    navigationId: input.navigationId ?? input.id,
-    locale: input.locale,
-    title,
-    description,
-    keywords,
-    openapi: typeof parsed.data.openapi === "string" ? parsed.data.openapi.trim() : void 0,
-    body,
-    source: input.source
-  };
-}
-
-// src/navigation.ts
-import { existsSync, readFileSync } from "fs";
-import { dirname, extname, relative as relative2 } from "path";
+// src/docusaurus.ts
+import { existsSync, lstatSync, readFileSync } from "fs";
+import { extname, posix } from "path";
+import JSON5 from "json5";
+import { parse as parseYaml } from "yaml";
 
 // src/path.ts
 import { isAbsolute, relative, resolve, sep } from "path";
@@ -92,7 +57,553 @@ function normalizeAssetPath(value) {
   return segments.join("/");
 }
 
+// src/docusaurus.ts
+var MAX_CONFIG_BYTES = 1e6;
+var CATEGORY_FILENAMES = ["_category_.json", "_category_.yml", "_category_.yaml"];
+var SIDEBAR_FILENAMES = [
+  "sidebars.json",
+  "sidebars.js",
+  "sidebars.cjs",
+  "sidebars.mjs",
+  "sidebars.ts"
+];
+function objectValue(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stripNumberPrefix(value) {
+  return value.replace(/^\d+[-_]+/, "");
+}
+function normalizeDocId(value) {
+  return value.split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^\/+/, "").replace(/\.(?:mdx?)$/i, "").split("/").filter(Boolean).map(stripNumberPrefix).join("/");
+}
+function docusaurusSlugifySegment(value) {
+  let decoded = value;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+  }
+  return decoded.replace(/\.(?:html?|mdx?)$/i, "").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/(^-|-$)/g, "");
+}
+function docusaurusRouteId(value) {
+  const segments = normalizeDocId(value).split("/").map(docusaurusSlugifySegment).filter(Boolean);
+  return segments.join("/") || "introduction";
+}
+function defaultDocusaurusRouteId(value) {
+  const segments = normalizeDocId(value).split("/").filter(Boolean);
+  if (/^(?:index|readme)$/i.test(segments.at(-1) ?? "")) segments.pop();
+  const normalized = segments.map(docusaurusSlugifySegment).filter(Boolean);
+  return normalized.join("/") || "introduction";
+}
+function storageIdForRoute(routeId) {
+  return /(?:^|\/)(?:index|readme)$/i.test(routeId) ? `${routeId}/index` : routeId;
+}
+function titleCase(value) {
+  return stripNumberPrefix(value).replace(/sidebar$/i, "").split(/[-_]/).filter(Boolean).map((word) => ["api", "cli", "sdk", "ui"].includes(word.toLowerCase()) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function routeFromSlug(slug, fallback, sourceDirectory) {
+  if (slug === "/") return "introduction";
+  if (slug.startsWith("/")) return docusaurusRouteId(slug);
+  const fallbackDirectory = sourceDirectory ?? (fallback === "introduction" ? "" : posix.dirname(fallback));
+  const resolved = posix.normalize(posix.join(fallbackDirectory, slug));
+  if (resolved === ".." || resolved.startsWith("../")) return null;
+  return docusaurusRouteId(resolved);
+}
+function resolveDocusaurusPageIdentity(sourcePath, frontmatter, fallback) {
+  const sourceDocId = normalizeDocId(sourcePath);
+  const sourceDirectory = posix.dirname(sourceDocId);
+  const configuredId = typeof frontmatter.id === "string" && frontmatter.id.trim() ? stripNumberPrefix(frontmatter.id.trim()) : null;
+  const docId = configuredId ? normalizeDocId(sourceDirectory === "." ? configuredId : posix.join(sourceDirectory, configuredId)) : sourceDocId;
+  const defaultNavigationId = defaultDocusaurusRouteId(docId) ?? fallback.navigationId;
+  const configuredSlug = typeof frontmatter.slug === "string" ? frontmatter.slug.trim() : "";
+  const navigationId = configuredSlug ? routeFromSlug(
+    configuredSlug,
+    defaultNavigationId,
+    sourceDirectory === "." ? "" : sourceDirectory
+  ) ?? defaultNavigationId : defaultNavigationId;
+  const position = typeof frontmatter.sidebar_position === "number" && Number.isFinite(frontmatter.sidebar_position) ? frontmatter.sidebar_position : void 0;
+  return {
+    identity: { id: storageIdForRoute(navigationId), navigationId },
+    descriptor: {
+      sourcePath: sourcePath.replace(/\\/g, "/"),
+      docId,
+      navigationId,
+      ...position === void 0 ? {} : { sidebarPosition: position }
+    }
+  };
+}
+function sourceReferenceKey(value) {
+  return value.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\.(?:mdx?)$/i, "").replace(/\/$/, "");
+}
+function rewriteDocusaurusLinks(body, current, descriptors) {
+  const routes = /* @__PURE__ */ new Map();
+  for (const descriptor of descriptors) {
+    const sourceKey = sourceReferenceKey(descriptor.sourcePath);
+    routes.set(sourceKey, descriptor.navigationId);
+    routes.set(sourceReferenceKey(descriptor.docId), descriptor.navigationId);
+    routes.set(sourceReferenceKey(descriptor.navigationId), descriptor.navigationId);
+    const sourceRoute = pageIdFromReference(sourceKey);
+    if (sourceRoute) routes.set(sourceRoute, descriptor.navigationId);
+  }
+  const currentDirectory = posix.dirname(sourceReferenceKey(current.sourcePath));
+  function rewriteTarget(target) {
+    if (!target || target.startsWith("#") || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(target)) return target;
+    const suffixIndex = target.search(/[?#]/);
+    const path = suffixIndex >= 0 ? target.slice(0, suffixIndex) : target;
+    const suffix = suffixIndex >= 0 ? target.slice(suffixIndex) : "";
+    const candidates = path.startsWith("/") ? [sourceReferenceKey(path), sourceReferenceKey(path).replace(/^docs\//, "")] : [
+      sourceReferenceKey(posix.normalize(posix.join(currentDirectory, path))),
+      sourceReferenceKey(path)
+    ];
+    const route = candidates.map((candidate) => routes.get(candidate)).find(Boolean);
+    if (!route) return target;
+    return `${route === "introduction" ? "/" : `/${route}`}${suffix}`;
+  }
+  let codeFence = null;
+  return body.split("\n").map((line) => {
+    const fence = line.match(/^\s*(`{3,}|~{3,})/);
+    if (fence) {
+      if (!codeFence) codeFence = fence[1][0];
+      else if (fence[1][0] === codeFence) codeFence = null;
+      return line;
+    }
+    if (codeFence) return line;
+    return line.replace(/(\]\()([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(target)}`).replace(/(\bhref=")([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(target)}${suffix}`);
+  }).join("\n");
+}
+function readBoundedText(path) {
+  if (lstatSync(path).size > MAX_CONFIG_BYTES) {
+    throw new Error("Docusaurus sidebar config exceeded the 1 MB static-parser limit.");
+  }
+  return readFileSync(path, "utf8");
+}
+function matchingObjectLiteral(source, start) {
+  let depth = 0;
+  let quote = null;
+  let isEscaped = false;
+  let lineComment = false;
+  let blockComment = false;
+  let objectStart = -1;
+  for (let index = start; index < source.length; index++) {
+    const char = source[index];
+    const next = source[index + 1];
+    if (lineComment) {
+      if (char === "\n") lineComment = false;
+      continue;
+    }
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        index++;
+      }
+      continue;
+    }
+    if (quote) {
+      if (isEscaped) isEscaped = false;
+      else if (char === "\\") isEscaped = true;
+      else if (char === quote) quote = null;
+      continue;
+    }
+    if (char === "/" && next === "/") {
+      lineComment = true;
+      index++;
+      continue;
+    }
+    if (char === "/" && next === "*") {
+      blockComment = true;
+      index++;
+      continue;
+    }
+    if (char === '"' || char === "'" || char === "`") {
+      quote = char;
+      continue;
+    }
+    if (char === "{") {
+      if (objectStart < 0) objectStart = index;
+      depth++;
+    } else if (char === "}" && objectStart >= 0) {
+      depth--;
+      if (depth === 0) return source.slice(objectStart, index + 1);
+    } else if (objectStart < 0 && !/\s/.test(char)) {
+      return null;
+    }
+  }
+  return null;
+}
+function parseStaticSidebarModule(source) {
+  const bindings = /* @__PURE__ */ new Map();
+  const normalizedSource = replaceExternalFbContent(source);
+  const parseFailures = [];
+  const assignmentPatterns = [
+    /\bmodule\.exports\s*=\s*/g,
+    /\bexport\s+default\s*/g,
+    /\b(?:const|let|var)\s+[A-Za-z_$][\w$]*(?:\s*:\s*[^=;]+)?\s*=\s*/g
+  ];
+  const candidates = assignmentPatterns.flatMap((pattern) => [...normalizedSource.matchAll(pattern)]).sort((left, right) => (left.index ?? 0) - (right.index ?? 0));
+  for (const candidate of candidates) {
+    const literal = matchingObjectLiteral(normalizedSource, (candidate.index ?? 0) + candidate[0].length);
+    if (!literal) continue;
+    try {
+      const substituted = [...bindings].reduce(
+        (value, [name, binding]) => value.replace(
+          new RegExp(`(:\\s*)${name}\\b`, "g"),
+          (_match, prefix) => `${prefix}${JSON.stringify(binding)}`
+        ),
+        literal
+      );
+      const parsed = JSON5.parse(substituted);
+      const object = objectValue(parsed);
+      if (!object) continue;
+      const bindingName = candidate[0].match(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)/)?.[1];
+      if (bindingName) {
+        bindings.set(bindingName, object);
+        continue;
+      }
+      return object;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const line = Number(message.match(/at (\d+):/)?.[1] ?? 0);
+      const context = line > 0 ? literal.split("\n").slice(Math.max(0, line - 2), line + 1).join(" ") : "";
+      parseFailures.push(`${message}${context ? ` near ${context}` : ""}`);
+    }
+  }
+  const exportedBinding = normalizedSource.match(/\bexport\s+default\s+([A-Za-z_$][\w$]*)\b/)?.[1] ?? normalizedSource.match(/\bmodule\.exports\s*=\s*([A-Za-z_$][\w$]*)\b/)?.[1];
+  if (exportedBinding && bindings.has(exportedBinding)) return bindings.get(exportedBinding);
+  throw new Error(`Sidebar config is executable or outside the supported data-only syntax.${parseFailures[0] ? ` ${parseFailures[0]}` : ""}`);
+}
+function replaceExternalFbContent(source) {
+  const marker = "...fbContent(";
+  let result = source;
+  let searchFrom = 0;
+  while (true) {
+    const start = result.indexOf(marker, searchFrom);
+    if (start < 0) return result.replace(/,\s*,/g, ",");
+    const objectStart = result.indexOf("{", start + marker.length);
+    if (objectStart < 0) return result;
+    const objectLiteral = matchingObjectLiteral(result, objectStart);
+    if (!objectLiteral) {
+      searchFrom = start + marker.length;
+      continue;
+    }
+    const objectEnd = objectStart + objectLiteral.length;
+    const close = result.indexOf(")", objectEnd);
+    if (close < 0) return result;
+    const externalMatch = /\bexternal\s*:\s*/g.exec(objectLiteral);
+    let replacement = "";
+    if (externalMatch) {
+      const arrayStart = objectLiteral.indexOf("[", externalMatch.index + externalMatch[0].length);
+      if (arrayStart >= 0) {
+        const array = matchingArrayLiteral(objectLiteral, arrayStart);
+        if (array) replacement = array.slice(1, -1);
+      }
+    }
+    let replaceEnd = close + 1;
+    if (!replacement) {
+      const trailingComma = result.slice(replaceEnd).match(/^\s*,/);
+      if (trailingComma) replaceEnd += trailingComma[0].length;
+    }
+    result = `${result.slice(0, start)}${replacement}${result.slice(replaceEnd)}`;
+    searchFrom = start + replacement.length;
+  }
+}
+function matchingArrayLiteral(source, start) {
+  let depth = 0;
+  let quote = "";
+  let isEscaped = false;
+  for (let index = start; index < source.length; index++) {
+    const character = source[index];
+    if (quote) {
+      if (isEscaped) isEscaped = false;
+      else if (character === "\\") isEscaped = true;
+      else if (character === quote) quote = "";
+      continue;
+    }
+    if (character === '"' || character === "'" || character === "`") {
+      quote = character;
+      continue;
+    }
+    if (character === "[") depth++;
+    if (character === "]" && --depth === 0) return source.slice(start, index + 1);
+  }
+  return null;
+}
+function configuredSidebarPath(repositoryRoot) {
+  for (const filename of ["docusaurus.config.js", "docusaurus.config.ts", "docusaurus.config.mjs"]) {
+    const path = resolveWithin(repositoryRoot, filename);
+    if (!existsSync(path)) continue;
+    const source = readBoundedText(path);
+    const match = source.match(/\bsidebarPath\s*:\s*(?:require\.resolve\(\s*)?(['"])([^'"]+)\1/);
+    if (!match) continue;
+    const candidate = match[2].replace(/^\.\//, "");
+    const resolved = resolveWithin(repositoryRoot, candidate);
+    if (existsSync(resolved) && lstatSync(resolved).isFile()) return candidate;
+  }
+  return null;
+}
+function readDocusaurusSidebars(repositoryRoot) {
+  const configured = configuredSidebarPath(repositoryRoot);
+  const sourcePath = [configured, ...SIDEBAR_FILENAMES].filter((value) => Boolean(value)).find((candidate) => existsSync(resolveWithin(repositoryRoot, candidate)));
+  if (!sourcePath) return null;
+  const absolutePath = resolveWithin(repositoryRoot, sourcePath);
+  const source = readBoundedText(absolutePath);
+  const parsed = extname(sourcePath).toLowerCase() === ".json" ? objectValue(JSON5.parse(source)) : parseStaticSidebarModule(source);
+  if (!parsed) throw new Error("Docusaurus sidebar config must export an object.");
+  return { config: parsed, sourcePath };
+}
+function readCategoryMetadata(contentRoot, directory) {
+  for (const filename of CATEGORY_FILENAMES) {
+    const path = resolveWithin(contentRoot, posix.join(directory, filename));
+    if (!existsSync(path) || !lstatSync(path).isFile()) continue;
+    try {
+      const raw = readBoundedText(path);
+      const parsed = filename.endsWith(".json") ? JSON5.parse(raw) : parseYaml(raw);
+      const object = objectValue(parsed);
+      if (!object) return {};
+      return {
+        ...typeof object.label === "string" ? { label: object.label } : {},
+        ...typeof object.position === "number" ? { position: object.position } : {},
+        ..."link" in object ? { link: object.link } : {}
+      };
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+function descriptorSort(left, right) {
+  const leftPosition = left.sidebarPosition ?? Number.MAX_SAFE_INTEGER;
+  const rightPosition = right.sidebarPosition ?? Number.MAX_SAFE_INTEGER;
+  if (leftPosition !== rightPosition) return leftPosition - rightPosition;
+  return left.sourcePath.localeCompare(right.sourcePath, void 0, { numeric: true });
+}
+function registerDoc(docId, context) {
+  const key = normalizeDocId(docId);
+  const descriptor = context.descriptorByDocId.get(key) ?? context.descriptors.find((page) => page.navigationId === docusaurusRouteId(key));
+  if (!descriptor) {
+    context.warnings.push({
+      code: "missing-page",
+      message: "A Docusaurus sidebar document did not resolve to an imported page.",
+      source: docId
+    });
+    return null;
+  }
+  context.referencedNavigationIds.add(descriptor.navigationId);
+  return descriptor.navigationId;
+}
+function generatedIndexPage(label, linkValue, context) {
+  const link = objectValue(linkValue);
+  if (!link) return null;
+  if (link.type === "doc" && typeof link.id === "string") return registerDoc(link.id, context);
+  if (link.type !== "generated-index") return null;
+  const fallback = `category/${slugifySegment(label)}`;
+  const unprefixedNavigationId = typeof link.slug === "string" ? routeFromSlug(link.slug, fallback) ?? fallback : fallback;
+  const navigationId = context.routePrefix && unprefixedNavigationId !== context.routePrefix && !unprefixedNavigationId.startsWith(`${context.routePrefix}/`) ? posix.join(context.routePrefix, unprefixedNavigationId) : unprefixedNavigationId;
+  if (!context.generatedIds.has(navigationId) && !context.descriptors.some((page) => page.navigationId === navigationId)) {
+    const description = typeof link.description === "string" ? link.description : `Browse the ${label} documentation.`;
+    context.generatedPages.push({
+      id: storageIdForRoute(navigationId),
+      navigationId,
+      title: typeof link.title === "string" ? link.title : label,
+      description,
+      keywords: Array.isArray(link.keywords) ? link.keywords.filter((value) => typeof value === "string") : [],
+      body: description,
+      source: `${context.sourceUrl}#${context.sidebarSource}`
+    });
+    context.generatedIds.add(navigationId);
+  }
+  context.referencedNavigationIds.add(navigationId);
+  return navigationId;
+}
+function autogeneratedItems(dirName, context) {
+  const normalizedDir = dirName === "." ? "" : normalizeDocId(dirName);
+  const inDirectory = context.descriptors.filter((descriptor) => {
+    const source = descriptor.sourcePath.replace(/\.(?:mdx?)$/i, "");
+    return !normalizedDir || source === normalizedDir || source.startsWith(`${normalizedDir}/`);
+  });
+  const directPages = [];
+  const childDirectories = /* @__PURE__ */ new Set();
+  for (const descriptor of inDirectory) {
+    const source = descriptor.sourcePath.replace(/\.(?:mdx?)$/i, "");
+    const relativePath = normalizedDir ? posix.relative(normalizedDir, source) : source;
+    const segments = relativePath.split("/").filter(Boolean);
+    if (segments.length <= 1) directPages.push(descriptor);
+    else childDirectories.add(segments[0]);
+  }
+  const items = directPages.sort(descriptorSort).map((descriptor) => {
+    context.referencedNavigationIds.add(descriptor.navigationId);
+    return descriptor.navigationId;
+  });
+  const groups = [...childDirectories].map((segment) => {
+    const directory = normalizedDir ? posix.join(normalizedDir, segment) : segment;
+    const metadata = readCategoryMetadata(context.contentRoot, directory);
+    const pages = autogeneratedItems(directory, context);
+    const landing = generatedIndexPage(metadata.label ?? titleCase(segment), metadata.link, context);
+    if (landing && !pages.includes(landing)) pages.unshift(landing);
+    return {
+      position: metadata.position ?? Number.MAX_SAFE_INTEGER,
+      segment,
+      group: {
+        group: metadata.label ?? titleCase(segment),
+        pages
+      }
+    };
+  }).sort((left, right) => left.position - right.position || left.segment.localeCompare(right.segment, void 0, { numeric: true }));
+  items.push(...groups.map((entry) => entry.group));
+  return items;
+}
+function convertItems(value, context) {
+  if (typeof value === "string") {
+    const page = registerDoc(value, context);
+    return page ? [page] : [];
+  }
+  if (Array.isArray(value)) return value.flatMap((entry) => convertItems(entry, context));
+  const object = objectValue(value);
+  if (!object) return [];
+  if (object.type === "doc" || object.type === "ref") {
+    const page = typeof object.id === "string" ? registerDoc(object.id, context) : null;
+    return page ? [page] : [];
+  }
+  if (object.type === "autogenerated") {
+    return autogeneratedItems(typeof object.dirName === "string" ? object.dirName : ".", context);
+  }
+  if (object.type === "category") {
+    const label = typeof object.label === "string" ? object.label : "Documentation";
+    const pages = convertItems(object.items, context);
+    const landing = generatedIndexPage(label, object.link, context);
+    if (landing && !pages.includes(landing)) pages.unshift(landing);
+    return pages.length > 0 ? [{ group: label, pages }] : [];
+  }
+  if (object.type === "link" || object.type === "html") return [];
+  return Object.entries(object).flatMap(([label, items]) => {
+    const pages = convertItems(items, context);
+    return pages.length > 0 ? [{ group: label, pages }] : [];
+  });
+}
+function projectDocusaurusNavigation(input) {
+  const warnings = [];
+  const descriptorByDocId = new Map(input.descriptors.map((page) => [page.docId, page]));
+  const context = {
+    contentRoot: input.contentRoot,
+    descriptors: input.descriptors,
+    descriptorByDocId,
+    generatedPages: [],
+    generatedIds: /* @__PURE__ */ new Set(),
+    referencedNavigationIds: /* @__PURE__ */ new Set(),
+    sourceUrl: input.sourceUrl,
+    routePrefix: input.routePrefix ?? "",
+    sidebarSource: input.sidebars?.sourcePath ?? "autogenerated sidebar",
+    warnings
+  };
+  const sidebarEntries = input.sidebars ? Object.entries(input.sidebars.config) : [["docs", [
+    { type: "autogenerated", dirName: "." }
+  ]]];
+  const tabs = sidebarEntries.flatMap(([sidebarId, value]) => {
+    const converted = convertItems(value, context);
+    const loosePages = converted.filter((entry) => typeof entry === "string");
+    const groups = converted.filter((entry) => typeof entry !== "string");
+    if (loosePages.length > 0) groups.unshift({ group: "Overview", pages: loosePages });
+    if (groups.length === 0) return [];
+    return [{
+      tab: sidebarEntries.length === 1 ? "Documentation" : titleCase(sidebarId),
+      groups
+    }];
+  });
+  const unreferenced = input.descriptors.filter((page) => !context.referencedNavigationIds.has(page.navigationId)).sort(descriptorSort).map((page) => page.navigationId);
+  if (unreferenced.length > 0) {
+    if (tabs.length === 0) tabs.push({ tab: "Documentation", groups: [] });
+    tabs[0].groups?.push({ group: "Additional", pages: unreferenced });
+  }
+  return {
+    docsConfig: { tabs },
+    generatedPages: context.generatedPages,
+    referencedNavigationIds: context.referencedNavigationIds,
+    warnings
+  };
+}
+
+// src/mdx.ts
+import matter from "gray-matter";
+function titleFromId(id) {
+  const value = id.split("/").at(-1) ?? id;
+  if (value === "introduction") return "Introduction";
+  return value.split(/[-_]/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function firstParagraph(content) {
+  for (const block of content.split(/\n\s*\n/)) {
+    const value = block.replace(/\s+/g, " ").trim();
+    if (!value || /^(?:#|```|:::|<|import\s|export\s)/.test(value)) continue;
+    return value.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").slice(0, 240);
+  }
+  return "";
+}
+function docusaurusAdmonitionTag(kind) {
+  if (kind === "danger") return "Error";
+  if (kind === "info") return "Info";
+  if (kind === "caution" || kind === "warning") return "Warning";
+  return "Note";
+}
+function normalizeDocusaurusAdmonitions(body) {
+  const lines = body.split("\n");
+  const openAdmonitions = [];
+  let codeFence = null;
+  return lines.map((line) => {
+    const codeMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (codeMatch) {
+      if (!codeFence) codeFence = codeMatch[1][0];
+      else if (codeMatch[1][0] === codeFence) codeFence = null;
+      return line;
+    }
+    if (codeFence) return line;
+    const opening = line.match(/^\s*(:{3,})(note|tip|info|warning|caution|danger)(?:\[([^\]]+)\]|\s+(.+))?\s*$/i);
+    if (opening) {
+      const tag = docusaurusAdmonitionTag(opening[2].toLowerCase());
+      openAdmonitions.push({ delimiter: opening[1], tag });
+      const title = (opening[3] ?? opening[4])?.trim();
+      return title ? `<${tag}>
+**${title}**` : `<${tag}>`;
+    }
+    const closing = line.match(/^\s*(:{3,})\s*$/);
+    const current = openAdmonitions.at(-1);
+    if (closing && current?.delimiter === closing[1]) {
+      openAdmonitions.pop();
+      return `</${current.tag}>`;
+    }
+    return line;
+  }).join("\n");
+}
+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>");
+}
+function parseMarkdownPage(input) {
+  const parsed = matter(input.raw);
+  const fallbackIdentity = {
+    id: input.id,
+    navigationId: input.navigationId ?? input.id,
+    ...input.locale ? { locale: input.locale } : {}
+  };
+  const identity = input.resolveIdentity?.(parsed.data, fallbackIdentity) ?? fallbackIdentity;
+  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 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,
+    description,
+    keywords,
+    openapi: typeof parsed.data.openapi === "string" ? parsed.data.openapi.trim() : void 0,
+    body,
+    source: input.source
+  };
+}
+
 // src/navigation.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { dirname, extname as extname2, relative as relative2 } from "path";
 var LANGUAGE_LABELS = {
   ar: "Arabic",
   de: "German",
@@ -111,7 +622,7 @@ var LANGUAGE_LABELS = {
   uk: "Ukrainian",
   zh: "Chinese"
 };
-function objectValue(value) {
+function objectValue2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
 function labelFor(value, fallback) {
@@ -127,7 +638,7 @@ function jsonPointer(root, pointer) {
   if (!pointer || pointer === "#") return root;
   const tokens = pointer.replace(/^#\/?/, "").split("/").filter(Boolean);
   return tokens.reduce((current, token) => {
-    const object = objectValue(current);
+    const object = objectValue2(current);
     if (!object) return void 0;
     return object[token.replace(/~1/g, "/").replace(/~0/g, "~")];
   }, root);
@@ -136,7 +647,7 @@ function resolveJsonReferences(value, currentFile, repositoryRoot, stack) {
   if (Array.isArray(value)) {
     return value.map((entry) => resolveJsonReferences(entry, currentFile, repositoryRoot, stack));
   }
-  const object = objectValue(value);
+  const object = objectValue2(value);
   if (!object) return value;
   if (typeof object.$ref === "string") {
     const [filePart, pointer = ""] = object.$ref.split("#", 2);
@@ -146,7 +657,7 @@ 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(readFileSync(referencedFile, "utf8"));
+    const referencedRoot = JSON.parse(readFileSync2(referencedFile, "utf8"));
     const referenced = jsonPointer(referencedRoot, pointer ? `#${pointer}` : "");
     const resolved = resolveJsonReferences(referenced, referencedFile, repositoryRoot, stack);
     stack.delete(stackKey);
@@ -160,9 +671,9 @@ function resolveJsonReferences(value, currentFile, repositoryRoot, stack) {
   );
 }
 function readMintlifyConfig(repositoryRoot) {
-  const configPath = ["docs.json", "mint.json"].map((filename) => resolveWithin(repositoryRoot, filename)).find(existsSync);
+  const configPath = ["docs.json", "mint.json"].map((filename) => resolveWithin(repositoryRoot, filename)).find(existsSync2);
   if (!configPath) return null;
-  const raw = JSON.parse(readFileSync(configPath, "utf8"));
+  const raw = JSON.parse(readFileSync2(configPath, "utf8"));
   return resolveJsonReferences(raw, configPath, repositoryRoot, /* @__PURE__ */ new Set());
 }
 function normalizePageRef(value) {
@@ -184,7 +695,7 @@ function registerReference(value, context) {
 }
 function convertPage(value, context) {
   if (typeof value === "string") return registerReference(value, context);
-  const object = objectValue(value);
+  const object = objectValue2(value);
   if (!object) return null;
   if (typeof object.page === "string") return registerReference(object.page, context);
   const pages = Array.isArray(object.pages) ? object.pages : [];
@@ -220,12 +731,12 @@ function convertGroups(values, context, fallbackGroup) {
   return groups;
 }
 function convertContainerToTabs(containerValue, context, fallbackTab) {
-  const container = objectValue(containerValue);
+  const container = objectValue2(containerValue);
   if (!container) return [];
   for (const key of ["tabs", "anchors", "products", "dropdowns", "versions", "menus"]) {
     if (!Array.isArray(container[key])) continue;
     const tabs = container[key].flatMap((value, index) => {
-      const object = objectValue(value);
+      const object = objectValue2(value);
       if (!object) return [];
       const tab = labelFor(object, `${fallbackTab} ${index + 1}`);
       if (typeof object.href === "string" && !object.pages && !object.groups) {
@@ -252,8 +763,8 @@ function projectMintlifyNavigation(config) {
   const warnings = [];
   const references = [];
   const seenReferences = /* @__PURE__ */ new Set();
-  const navigation = objectValue(config.navigation) ?? config;
-  const languages = Array.isArray(navigation.languages) ? navigation.languages.map(objectValue).filter((value) => Boolean(value)) : [];
+  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) {
@@ -291,7 +802,7 @@ function projectMintlifyNavigation(config) {
     tabs.push({ tab: "Changelog", href: "/changelog" });
   }
   const redirects = Array.isArray(config.redirects) ? config.redirects.flatMap((value) => {
-    const redirect = objectValue(value);
+    const redirect = objectValue2(value);
     if (!redirect || typeof redirect.source !== "string" || typeof redirect.destination !== "string") return [];
     return [{
       source: redirect.source,
@@ -305,7 +816,7 @@ function projectMintlifyNavigation(config) {
     warnings
   };
 }
-function titleCase(value) {
+function titleCase2(value) {
   return value.split(/[-_]/).map((word) => ["api", "cli", "sdk", "ui"].includes(word.toLowerCase()) ? word.toUpperCase() : word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
 var TOP_LEVEL_LABELS = {
@@ -317,7 +828,7 @@ var TOP_LEVEL_LABELS = {
   sdk: "SDK"
 };
 function topLevelLabel(segment) {
-  return TOP_LEVEL_LABELS[segment] ?? titleCase(segment);
+  return TOP_LEVEL_LABELS[segment] ?? titleCase2(segment);
 }
 function groupsWithinSection(section, pageIds, sectionLabel = topLevelLabel(section)) {
   const groups = /* @__PURE__ */ new Map();
@@ -329,7 +840,7 @@ function groupsWithinSection(section, pageIds, sectionLabel = topLevelLabel(sect
     groups.set(nestedSegment, group);
   }
   return [...groups].map(([segment, pages]) => ({
-    group: segment === "overview" ? sectionLabel : titleCase(segment),
+    group: segment === "overview" ? sectionLabel : titleCase2(segment),
     pages
   }));
 }
@@ -401,20 +912,20 @@ function buildNavigationFromPages(pages, options = {}) {
     buckets.set(segment, bucket);
   }
   const groups = [...buckets].map(([segment, pageIds]) => ({
-    group: segment === "overview" ? "Overview" : titleCase(segment),
+    group: segment === "overview" ? "Overview" : titleCase2(segment),
     pages: pageIds
   }));
   return { tabs: [{ tab: "Documentation", groups }] };
 }
 function isDocumentationExtension(filename) {
-  return [".md", ".mdx", ".rst", ".txt"].includes(extname(filename).toLowerCase());
+  return [".md", ".mdx", ".rst", ".txt"].includes(extname2(filename).toLowerCase());
 }
 
 // src/repository.ts
 var MAX_SOURCE_FILES = 5e3;
 var MAX_PAGE_BYTES = 2e6;
 var MAX_ASSET_BYTES = 25e6;
-var MAX_TOTAL_ASSET_BYTES = 1e8;
+var MAX_TOTAL_ASSET_BYTES = 5e8;
 var IGNORED_DIRECTORIES = /* @__PURE__ */ new Set([
   ".git",
   ".github",
@@ -461,6 +972,71 @@ var OPENAPI_FILENAMES = /* @__PURE__ */ new Set([
   "swagger.yaml",
   "swagger.yml"
 ]);
+var DOCUSAURUS_CONFIG_FILENAMES = [
+  "docusaurus.config.js",
+  "docusaurus.config.ts",
+  "docusaurus.config.mjs"
+];
+function hasDocusaurusConfig(directory) {
+  return DOCUSAURUS_CONFIG_FILENAMES.some((filename) => {
+    const path = resolveWithin(directory, filename);
+    return existsSync3(path) && lstatSync2(path).isFile();
+  });
+}
+function findDocusaurusProjectRoot(repositoryDir, docsDir) {
+  if (docsDir !== void 0) {
+    let candidate = docsDir.replace(/\/+$/, "");
+    while (true) {
+      const path = resolveWithin(repositoryDir, candidate || ".");
+      if (hasDocusaurusConfig(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 (hasDocusaurusConfig(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 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 "";
+  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";
+}
+function additionalDocusaurusPluginRoots(repositoryDir, projectRoot) {
+  const source = readDocusaurusConfigSource(projectRoot);
+  const projectRelative = relative3(repositoryDir, projectRoot).replace(/\\/g, "/");
+  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, "");
+    if (!localPath || !routePrefix) continue;
+    const docsDir = [projectRelative, localPath].filter(Boolean).join("/");
+    const absolute = resolveWithin(repositoryDir, docsDir);
+    if (!existsSync3(absolute) || !lstatSync2(absolute).isDirectory()) continue;
+    plugins.push({ docsDir, routePrefix });
+  }
+  return plugins;
+}
 function parseGitHubRepositoryUrl(rawUrl) {
   let url;
   try {
@@ -514,21 +1090,22 @@ async function cloneGitHubRepository(source, targetDir) {
   });
 }
 function detectRepositoryPlatform(repositoryDir) {
-  if (existsSync2(resolveWithin(repositoryDir, "mint.json"))) return "mintlify";
+  if (existsSync3(resolveWithin(repositoryDir, "mint.json"))) return "mintlify";
   const docsJson = resolveWithin(repositoryDir, "docs.json");
-  if (existsSync2(docsJson)) {
+  if (existsSync3(docsJson)) {
     try {
-      const config = JSON.parse(readFileSync2(docsJson, "utf8"));
+      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 {
     }
   }
-  if (["docusaurus.config.js", "docusaurus.config.ts", "docusaurus.config.mjs"].some((name) => existsSync2(resolveWithin(repositoryDir, name)))) return "docusaurus";
-  if (existsSync2(resolveWithin(repositoryDir, "SUMMARY.md"))) return "gitbook";
-  if (existsSync2(resolveWithin(repositoryDir, ".vitepress"))) return "vitepress";
-  if (["astro.config.mjs", "astro.config.ts"].some((name) => existsSync2(resolveWithin(repositoryDir, name)))) return "starlight";
-  if (["pages/_meta.json", "_meta.json"].some((name) => existsSync2(resolveWithin(repositoryDir, name)))) return "nextra";
+  if (["docusaurus.config.js", "docusaurus.config.ts", "docusaurus.config.mjs"].some((name) => existsSync3(resolveWithin(repositoryDir, name)))) return "docusaurus";
+  if (findDocusaurusProjectRoot(repositoryDir)) return "docusaurus";
+  if (existsSync3(resolveWithin(repositoryDir, "SUMMARY.md"))) return "gitbook";
+  if (existsSync3(resolveWithin(repositoryDir, ".vitepress"))) return "vitepress";
+  if (["astro.config.mjs", "astro.config.ts"].some((name) => existsSync3(resolveWithin(repositoryDir, name)))) return "starlight";
+  if (["pages/_meta.json", "_meta.json"].some((name) => existsSync3(resolveWithin(repositoryDir, name)))) return "nextra";
   return "unknown";
 }
 function containsMarkdown(directory, depth = 0) {
@@ -536,7 +1113,7 @@ function containsMarkdown(directory, depth = 0) {
   for (const entry of readdirSync(directory, { withFileTypes: true })) {
     if (IGNORED_DIRECTORIES.has(entry.name) || entry.isSymbolicLink()) continue;
     const path = resolveWithin(directory, entry.name);
-    if (entry.isFile() && [".md", ".mdx"].includes(extname2(entry.name).toLowerCase())) return true;
+    if (entry.isFile() && [".md", ".mdx"].includes(extname3(entry.name).toLowerCase())) return true;
     if (entry.isDirectory() && containsMarkdown(path, depth + 1)) return true;
   }
   return false;
@@ -544,7 +1121,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 (existsSync2(path) && lstatSync(path).isDirectory() && containsMarkdown(path)) return candidate;
+    if (existsSync3(path) && lstatSync2(path).isDirectory() && containsMarkdown(path)) return candidate;
   }
   return "";
 }
@@ -572,22 +1149,24 @@ function findOpenApi(files) {
 function withoutFrontmatter(value) {
   return value.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, "").trim();
 }
-function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0) {
+function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0, siteRoot = repositoryRoot) {
   if (depth >= 8) return raw;
   const snippets = /* @__PURE__ */ new Map();
   const withoutImports = raw.replace(
-    /^import\s+([A-Z][A-Za-z0-9_]*)\s+from\s+['"]([^'"]+\.mdx?)['"]\s*;?\s*$/gm,
+    /^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 candidate = sourcePath.startsWith("/") ? resolveWithin(repositoryRoot, sourcePath.replace(/^\/+/, "")) : resolveWithin(dirname2(currentFile), sourcePath);
+        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 (!existsSync2(candidate) || !lstatSync(candidate).isFile()) throw new Error("file not found");
+        if (!existsSync3(candidate) || !lstatSync2(candidate).isFile()) throw new Error("file not found");
         const nested = inlineMdxSnippets(
-          withoutFrontmatter(readFileSync2(candidate, "utf8")),
+          withoutFrontmatter(readFileSync3(candidate, "utf8")),
           candidate,
           repositoryRoot,
           warnings,
-          depth + 1
+          depth + 1,
+          siteRoot
         );
         snippets.set(componentName, nested);
         return "";
@@ -622,10 +1201,27 @@ function injectOpenApi(config, filename) {
 function migrateRepository(options) {
   const repositoryDir = options.repositoryDir;
   const platform = options.platform ?? detectRepositoryPlatform(repositoryDir);
+  const docusaurusProjectRoot = platform === "docusaurus" ? findDocusaurusProjectRoot(repositoryDir, options.docsDir) : null;
+  const configuredDocsDir = (() => {
+    if (options.docsDir !== void 0) {
+      const selected = resolveWithin(repositoryDir, options.docsDir || ".");
+      if (platform === "docusaurus" && hasDocusaurusConfig(selected)) {
+        const projectRelative = relative3(repositoryDir, selected).replace(/\\/g, "/");
+        return [projectRelative, primaryDocusaurusDocsDirectory(selected)].filter(Boolean).join("/");
+      }
+      return options.docsDir;
+    }
+    if (docusaurusProjectRoot) {
+      const projectRelative = relative3(repositoryDir, docusaurusProjectRoot).replace(/\\/g, "/");
+      return [projectRelative, primaryDocusaurusDocsDirectory(docusaurusProjectRoot)].filter(Boolean).join("/");
+    }
+    return platform === "mintlify" ? "" : detectRepositoryDocsDir(repositoryDir);
+  })();
   const warnings = [];
   let docsConfig = { tabs: [] };
   const referenceMap = /* @__PURE__ */ new Map();
   const referenceOrder = /* @__PURE__ */ new Map();
+  let docusaurusSidebars = null;
   if (platform === "mintlify") {
     try {
       const config = readMintlifyConfig(repositoryDir);
@@ -646,16 +1242,27 @@ function migrateRepository(options) {
       });
     }
   }
-  const configuredDocsDir = options.docsDir ?? (platform === "mintlify" ? "" : detectRepositoryDocsDir(repositoryDir));
+  if (platform === "docusaurus") {
+    try {
+      docusaurusSidebars = options.docusaurusSkipSidebar || !docusaurusProjectRoot ? null : readDocusaurusSidebars(docusaurusProjectRoot);
+    } catch (error) {
+      warnings.push({
+        code: "unsupported-config",
+        message: `Docusaurus sidebar could not be read safely: ${error instanceof Error ? error.message : String(error)} Generated navigation will be used.`
+      });
+    }
+  }
   const contentRoot = resolveWithin(repositoryDir, configuredDocsDir);
-  if (!existsSync2(contentRoot) || !lstatSync(contentRoot).isDirectory()) {
+  if (!existsSync3(contentRoot) || !lstatSync2(contentRoot).isDirectory()) {
     throw new Error(`Documentation directory does not exist: ${configuredDocsDir || "."}`);
   }
   const files = scanFiles(contentRoot);
   const pages = [];
   const assets = [];
+  const docusaurusDescriptors = [];
   const seenPageIds = /* @__PURE__ */ new Set();
   let skipped = 0;
+  let discovered = files.length;
   const localeConfig = docsConfig.i18n;
   const pageFiles = [...files].sort((left, right) => {
     const leftOrder = referenceOrder.get(normalizedReferenceKey(left.relativePath)) ?? Number.MAX_SAFE_INTEGER;
@@ -664,21 +1271,22 @@ function migrateRepository(options) {
   });
   for (const file of pageFiles) {
     if (!isDocumentationExtension(file.relativePath)) continue;
-    if (file.relativePath.split("/").some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase()))) {
+    const sourceSegments = file.relativePath.split("/");
+    if (sourceSegments.some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase())) || platform === "docusaurus" && basename(file.relativePath).startsWith("_")) {
       skipped++;
       continue;
     }
     const rootFilename = !file.relativePath.includes("/") ? basename(file.relativePath).toLowerCase() : "";
-    if (REPOSITORY_ONLY_DOCUMENTS.has(rootFilename)) {
+    if (!configuredDocsDir && REPOSITORY_ONLY_DOCUMENTS.has(rootFilename)) {
       skipped++;
       continue;
     }
-    if (![".md", ".mdx"].includes(extname2(file.relativePath).toLowerCase())) {
+    if (![".md", ".mdx"].includes(extname3(file.relativePath).toLowerCase())) {
       skipped++;
       warnings.push({ code: "skipped-file", message: "Only Markdown and MDX are imported without an explicit converter.", source: file.relativePath });
       continue;
     }
-    const size = lstatSync(file.absolutePath).size;
+    const size = lstatSync2(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 });
@@ -702,30 +1310,57 @@ function migrateRepository(options) {
     }
     const isDefaultLocale = !locale || locale === localeConfig?.defaultLocale;
     const id = isDefaultLocale ? navigationId : `${locale}/${navigationId}`;
-    if (seenPageIds.has(id)) {
-      skipped++;
-      warnings.push({ code: "collision", message: `Multiple source files map to ${id}; the first file was kept.`, source: file.relativePath });
-      continue;
-    }
     const raw = inlineMdxSnippets(
-      readFileSync2(file.absolutePath, "utf8"),
+      readFileSync3(file.absolutePath, "utf8"),
       file.absolutePath,
       repositoryDir,
-      warnings
+      warnings,
+      0,
+      docusaurusProjectRoot ?? repositoryDir
     );
+    let docusaurusDescriptor;
     const page = parseMarkdownPage({
       id,
       navigationId,
       ...locale ? { locale } : {},
       raw,
-      source: `${options.sourceUrl}#${file.relativePath}`
+      source: `${options.sourceUrl}#${file.relativePath}`,
+      ...platform === "docusaurus" ? {
+        resolveIdentity: (frontmatter, fallback) => {
+          const resolved = resolveDocusaurusPageIdentity(file.relativePath, frontmatter, fallback);
+          const routePrefix = options.docusaurusRoutePrefix?.replace(/^\/+|\/+$/g, "");
+          if (!routePrefix) {
+            docusaurusDescriptor = resolved.descriptor;
+            return resolved.identity;
+          }
+          const prefixedNavigationId = resolved.identity.navigationId === "introduction" ? routePrefix : `${routePrefix}/${resolved.identity.navigationId}`;
+          const prefixedStorageId = resolved.identity.id === "introduction" ? routePrefix : `${routePrefix}/${resolved.identity.id}`;
+          docusaurusDescriptor = {
+            ...resolved.descriptor,
+            navigationId: prefixedNavigationId
+          };
+          return {
+            ...resolved.identity,
+            id: prefixedStorageId,
+            navigationId: prefixedNavigationId
+          };
+        }
+      } : {}
     });
     if (!page) {
       skipped++;
       continue;
     }
-    seenPageIds.add(id);
+    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 });
+      continue;
+    }
+    seenPageIds.add(page.id);
     pages.push(page);
+    if (docusaurusDescriptor) {
+      docusaurusDescriptors.push({ ...docusaurusDescriptor, title: page.title });
+    }
   }
   const discoveredReferenceKeys = new Set(files.map((file) => normalizedReferenceKey(file.relativePath)));
   for (const [key] of referenceMap) {
@@ -733,32 +1368,98 @@ function migrateRepository(options) {
       warnings.push({ code: "missing-page", message: "A navigation entry did not resolve to a source page.", source: key });
     }
   }
+  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 [];
+    return scanFiles(root).map((file) => ({
+      ...file,
+      relativePath: `${directory}/${file.relativePath}`
+    }));
+  }) : [];
   let totalAssetBytes = 0;
-  for (const file of files) {
+  for (const file of [...files, ...repositoryAssets]) {
     const firstSegment = file.relativePath.split("/", 1)[0].toLowerCase();
-    if (!ASSET_DIRECTORIES.has(firstSegment) || !ASSET_EXTENSIONS.has(extname2(file.relativePath).toLowerCase())) continue;
-    const size = lstatSync(file.absolutePath).size;
+    if (!ASSET_DIRECTORIES.has(firstSegment) || !ASSET_EXTENSIONS.has(extname3(file.relativePath).toLowerCase())) continue;
+    const size = lstatSync2(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;
     }
-    const assetPath = normalizeAssetPath(firstSegment === "public" ? file.relativePath.slice("public/".length) : file.relativePath);
+    const isDocusaurusStatic = platform === "docusaurus" && firstSegment === "static";
+    const assetPath = normalizeAssetPath(firstSegment === "public" ? file.relativePath.slice("public/".length) : isDocusaurusStatic ? file.relativePath.slice("static/".length) : file.relativePath);
     if (!assetPath) continue;
-    assets.push({ path: assetPath, content: readFileSync2(file.absolutePath) });
+    assets.push({ path: assetPath, content: readFileSync3(file.absolutePath) });
     totalAssetBytes += size;
   }
   if (files.length >= MAX_SOURCE_FILES) {
     warnings.push({ code: "limit-reached", message: `Repository discovery stopped at ${MAX_SOURCE_FILES} files.` });
   }
+  if (platform === "docusaurus") {
+    const projected = projectDocusaurusNavigation({
+      sidebars: docusaurusSidebars,
+      descriptors: docusaurusDescriptors,
+      contentRoot,
+      sourceUrl: options.sourceUrl,
+      routePrefix: options.docusaurusRoutePrefix
+    });
+    docsConfig = projected.docsConfig;
+    warnings.push(...projected.warnings);
+    for (const page of projected.generatedPages) {
+      if (seenPageIds.has(page.id)) continue;
+      seenPageIds.add(page.id);
+      pages.push(page);
+    }
+    const descriptorByNavigationId = new Map(
+      docusaurusDescriptors.map((descriptor) => [descriptor.navigationId, descriptor])
+    );
+    for (const page of pages) {
+      const descriptor = descriptorByNavigationId.get(page.navigationId);
+      if (descriptor) page.body = rewriteDocusaurusLinks(page.body, descriptor, docusaurusDescriptors);
+    }
+  }
   if (docsConfig.tabs.length === 0) docsConfig = buildNavigationFromPages(pages);
   const openApi = findOpenApi(files);
   if (openApi) {
     const filename = basename(openApi.relativePath);
     if (!assets.some((asset) => asset.path === filename)) {
-      assets.push({ path: filename, content: readFileSync2(openApi.absolutePath) });
+      assets.push({ path: filename, content: readFileSync3(openApi.absolutePath) });
     }
     docsConfig = injectOpenApi(docsConfig, filename);
   }
+  if (platform === "docusaurus" && docusaurusProjectRoot && !options.docusaurusSkipPlugins) {
+    for (const plugin of additionalDocusaurusPluginRoots(repositoryDir, docusaurusProjectRoot)) {
+      if (plugin.docsDir === configuredDocsDir) continue;
+      const pluginBundle = migrateRepository({
+        ...options,
+        docsDir: plugin.docsDir,
+        platform: "docusaurus",
+        docusaurusRoutePrefix: plugin.routePrefix,
+        docusaurusSkipPlugins: true,
+        docusaurusSkipSidebar: true,
+        docusaurusSkipAssets: true
+      });
+      for (const page of pluginBundle.pages) {
+        if (seenPageIds.has(page.id)) continue;
+        seenPageIds.add(page.id);
+        pages.push(page);
+      }
+      const assetPaths = new Set(assets.map((asset) => asset.path));
+      for (const asset of pluginBundle.assets) {
+        if (assetPaths.has(asset.path)) continue;
+        assetPaths.add(asset.path);
+        assets.push(asset);
+      }
+      const pluginLabel = plugin.routePrefix.split(/[-_/]/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+      docsConfig.tabs.push(...pluginBundle.docsConfig.tabs.map((tab, index) => ({
+        ...tab,
+        tab: index === 0 ? pluginLabel : `${pluginLabel}: ${tab.tab}`
+      })));
+      warnings.push(...pluginBundle.warnings);
+      discovered += pluginBundle.stats.discovered;
+      skipped += pluginBundle.stats.skipped;
+    }
+  }
   if (pages.length === 0) throw new Error("No importable Markdown or MDX pages were found in the repository.");
   return {
     sourceUrl: options.sourceUrl,
@@ -768,7 +1469,7 @@ function migrateRepository(options) {
     assets,
     docsConfig,
     warnings,
-    stats: { discovered: files.length, imported: pages.length, skipped }
+    stats: { discovered, imported: pages.length, skipped }
   };
 }
 
@@ -861,7 +1562,7 @@ function renderMigrationFiles(bundle, options = {}) {
 // src/url.ts
 import { load } from "cheerio";
 import TurndownService from "turndown";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml2, stringify as stringifyYaml } from "yaml";
 var DEFAULT_MAX_PAGES = 1e3;
 var DEFAULT_MAX_TOTAL_BYTES = 1e8;
 var MAX_DISCOVERED_URLS = 5e3;
@@ -1336,7 +2037,7 @@ function extractEmbeddedOpenApi(content) {
   const match = fencePattern.exec(content);
   if (!match) return { content };
   try {
-    const parsed = parseYaml(match[5], { maxAliasCount: 50 });
+    const parsed = parseYaml2(match[5], { maxAliasCount: 50 });
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { content };
     const document = parsed;
     if (typeof document.openapi !== "string" && typeof document.swagger !== "string") return { content };
@@ -1452,6 +2153,7 @@ function htmlPage(document, id) {
   const content = $('main article, article, main, [role="main"]').first();
   const root = content.length ? content : $("body");
   root.find("script,style,noscript,nav,header,footer,aside,form,button,svg,iframe,object,embed,link,meta").remove();
+  root.find(".theme-doc-version-badge,.theme-doc-breadcrumbs,.theme-doc-toc-mobile,.table-of-contents,.hash-link").remove();
   root.find("a[href]").each((_index, element) => {
     const href = $(element).attr("href");
     if (!href) return;
@@ -1482,12 +2184,78 @@ function htmlPage(document, id) {
   });
   const turndown = new TurndownService({ codeBlockStyle: "fenced", emDelimiter: "_", headingStyle: "atx" });
   turndown.remove(["script", "style", "noscript"]);
+  turndown.addRule("docusaurus-admonition", {
+    filter: (node) => node.nodeName === "DIV" && node.classList.contains("theme-admonition"),
+    replacement: (_content, node) => {
+      const element = node;
+      const className = element.className;
+      const tag = /admonition-(?:danger)/.test(className) ? "Error" : /admonition-(?:caution|warning)/.test(className) ? "Warning" : /admonition-info/.test(className) ? "Info" : "Note";
+      const fragment = load(element.outerHTML);
+      const clone = fragment(".theme-admonition").first();
+      const title2 = clone.find('[class*="admonitionHeading"],.admonition-heading').first();
+      const titleText = title2.text().trim();
+      title2.remove();
+      const markdown = turndown.turndown(clone.html() ?? "").trim();
+      return `
+
+<${tag}>
+${titleText ? `**${titleText}**
+
+` : ""}${markdown}
+</${tag}>
+
+`;
+    }
+  });
+  turndown.addRule("docusaurus-tabs", {
+    filter: (node) => node.nodeName === "DIV" && node.classList.contains("tabs-container"),
+    replacement: (_content, node) => {
+      const element = node;
+      const fragment = load(element.outerHTML);
+      const container = fragment(".tabs-container").first();
+      const labels = container.children("ul.tabs").children("li").toArray().map((item) => fragment(item).text().trim() || "Tab");
+      const panels = container.children('div[role="tabpanel"]').toArray();
+      if (panels.length === 0) return _content;
+      const tabs = panels.map((panel, index) => {
+        const title2 = (labels[index] ?? `Tab ${index + 1}`).replace(/"/g, "&quot;");
+        return `<Tab title="${title2}">
+${turndown.turndown(fragment(panel).html() ?? "").trim()}
+</Tab>`;
+      });
+      return `
+
+<Tabs>
+${tabs.join("\n\n")}
+</Tabs>
+
+`;
+    }
+  });
+  turndown.addRule("gfm-table", {
+    filter: "table",
+    replacement: (_content, node) => {
+      const fragment = load(node.outerHTML);
+      const rows = fragment("tr").toArray().map((row) => fragment(row).children("th,td").toArray().map((cell) => fragment(cell).text().replace(/\s+/g, " ").replace(/\|/g, "\\|").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\{/g, "&#123;").replace(/\}/g, "&#125;").trim())).filter((row) => row.length > 0);
+      if (rows.length === 0) return "";
+      const width = Math.max(...rows.map((row) => row.length));
+      const normalized = rows.map((row) => [...row, ...Array(width - row.length).fill("")]);
+      return `
+
+| ${normalized[0].join(" | ")} |
+| ${Array(width).fill("---").join(" | ")} |
+${normalized.slice(1).map((row) => `| ${row.join(" | ")} |`).join("\n")}
+
+`;
+    }
+  });
   turndown.addRule("migration-safe-fenced-code", {
     filter: (node) => node.nodeName === "PRE",
     replacement: (_content, node) => {
       const element = node;
-      const code = element.textContent?.replace(/\n$/, "") ?? "";
-      const language = element.querySelector("code")?.className.match(/(?:language-|lang-)([A-Za-z0-9_+-]+)/)?.[1] ?? "";
+      const fragment = load(element.outerHTML);
+      const tokenLines = fragment(".token-line").toArray();
+      const code = (tokenLines.length > 0 ? tokenLines.map((line) => fragment(line).text()).join("\n") : fragment("pre").text()).replace(/\n$/, "");
+      const language = fragment("code").attr("class")?.match(/(?:language-|lang-)([A-Za-z0-9_+-]+)/)?.[1] ?? "";
       const longestFence = Math.max(0, ...[...code.matchAll(/`+/g)].map((match) => match[0].length));
       const fence = "`".repeat(Math.max(3, longestFence + 1));
       return `
@@ -1502,7 +2270,7 @@ ${fence}
   const escape = turndown.escape.bind(turndown);
   turndown.escape = (text) => escape(text).replace(/[<{]/g, (match) => `\\${match}`);
   const body = turndown.turndown(root.html() ?? "").trim();
-  if (!title || body.length < 40) return { page: null, links };
+  if (!title || body.length < 40 && $("article").length === 0) return { page: null, links };
   return {
     page: {
       id,
@@ -1520,6 +2288,176 @@ function htmlNavigationLinks(document) {
   const $ = load(document.body);
   return $('.nav-tabs a[href], nav a[href], aside a[href], [role="navigation"] a[href]').map((_index, element) => $(element).attr("href") ?? "").get().filter(Boolean);
 }
+function normalizedLinkLabel(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function readDocusaurusSidebar(document) {
+  if (!/html/i.test(document.contentType)) return null;
+  const $ = load(document.body);
+  const sidebar = $("ul.theme-doc-sidebar-menu").first();
+  if (sidebar.length === 0) return null;
+  function readList(list) {
+    return $(list).children("li").toArray().flatMap((item) => {
+      const directLink = $(item).children("a.menu__link").first();
+      const collapsibleLink = $(item).children(".menu__list-item-collapsible").children("a.menu__link").first();
+      const link = directLink.length > 0 ? directLink : collapsibleLink;
+      const label = normalizedLinkLabel(link.text());
+      const href = link.attr("href");
+      const nested = $(item).children("ul.menu__list").first();
+      const children = nested.length > 0 ? readList(nested.get(0)) : [];
+      const isCategory = $(item).hasClass("theme-doc-sidebar-item-category") || link.hasClass("menu__link--sublist");
+      if (!label && children.length === 0) return [];
+      return [{
+        label: label || "Documentation",
+        ...href ? { href: new URL(href, document.finalUrl).toString() } : {},
+        ...children.length > 0 ? { items: children } : {},
+        ...isCategory ? { isCategory: true } : {}
+      }];
+    });
+  }
+  return { items: readList(sidebar.get(0)) };
+}
+function docusaurusSidebarHrefs(snapshot) {
+  const hrefs = [];
+  const visit = (items) => {
+    for (const item of items) {
+      if (item.href) hrefs.push(item.href);
+      if (item.items) visit(item.items);
+    }
+  };
+  if (snapshot) visit(snapshot.items);
+  return hrefs;
+}
+function deriveDocusaurusScope(source, document, submittedScopePath) {
+  const $ = load(document.body);
+  const sidebar = readDocusaurusSidebar(document);
+  const internalPaths = docusaurusSidebarHrefs(sidebar).flatMap((href) => {
+    try {
+      const url = new URL(href);
+      return url.origin === source.origin ? [url.pathname.replace(/\/+$/, "") || "/"] : [];
+    } catch {
+      return [];
+    }
+  });
+  const counts = /* @__PURE__ */ new Map();
+  for (const path of internalPaths) {
+    const segments = path.split("/").filter(Boolean);
+    for (let length = 1; length < segments.length; length++) {
+      const prefix = `/${segments.slice(0, length).join("/")}`;
+      counts.set(prefix, (counts.get(prefix) ?? 0) + 1);
+    }
+  }
+  const threshold = Math.max(2, Math.ceil(internalPaths.length * 0.6));
+  const scopePath = [...counts].filter(([, count]) => count >= threshold).sort((left, right) => right[0].split("/").length - left[0].split("/").length || right[1] - left[1])[0]?.[0] ?? submittedScopePath;
+  const excludedVersionPrefixes = $(".dropdown__menu a[href]").toArray().flatMap((element) => {
+    const href = $(element).attr("href");
+    if (!href) return [];
+    try {
+      const target = new URL(href, document.finalUrl);
+      if (target.origin !== source.origin || !isInScope(target, source, scopePath)) return [];
+      const relativePath = target.pathname.slice(scopePath.length).replace(/^\/+/, "");
+      const version = relativePath.split("/", 1)[0];
+      if (!/^(?:legacy|next|v\d[\w.-]*)$/i.test(version)) return [];
+      return [`${scopePath}/${version}`];
+    } catch {
+      return [];
+    }
+  });
+  return {
+    scopePath,
+    excludedVersionPrefixes: [...new Set(excludedVersionPrefixes)],
+    sidebar
+  };
+}
+function docusaurusRouteIdForUrl(url, scopePath) {
+  let path = url.pathname.replace(/\/+$/, "");
+  if (scopePath === "/") path = path.replace(/^\/+/, "");
+  else if (path === scopePath) path = "";
+  else if (path.startsWith(`${scopePath}/`)) path = path.slice(scopePath.length + 1);
+  else return null;
+  const segments = path.split("/").filter(Boolean).map((segment) => {
+    let decoded = segment;
+    try {
+      decoded = decodeURIComponent(segment);
+    } catch {
+    }
+    return decoded.replace(/\.(?:html?|mdx?)$/i, "").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/(^-|-$)/g, "");
+  }).filter(Boolean);
+  return segments.join("/") || "introduction";
+}
+function storageIdForDocusaurusRoute(routeId) {
+  return /(?:^|\/)(?:index|readme)$/i.test(routeId) ? `${routeId}/index` : routeId;
+}
+function docusaurusNavigationFromSnapshots(snapshots, pages, scopePath) {
+  const imported = new Set(pages.map((page) => page.navigationId));
+  const claimed = /* @__PURE__ */ new Set();
+  const uniqueSnapshots = [...new Map(snapshots.map((snapshot) => [
+    JSON.stringify(snapshot.items),
+    snapshot
+  ])).values()];
+  const mergedSnapshots = [];
+  function mergeItems(target, incoming) {
+    for (const item of incoming) {
+      const existing = target.find((candidate) => candidate.label === item.label && (candidate.items || item.items)) ?? target.find((candidate) => candidate.label === item.label && candidate.href === item.href);
+      if (!existing) {
+        target.push(structuredClone(item));
+        continue;
+      }
+      if (!existing.href && item.href) existing.href = item.href;
+      if (item.items) {
+        existing.items ??= [];
+        mergeItems(existing.items, item.items);
+      }
+    }
+  }
+  for (const snapshot of uniqueSnapshots) {
+    const incomingLabels = new Set(snapshot.items.map((item) => item.label));
+    const cluster = mergedSnapshots.find((candidate) => {
+      const candidateLabels = new Set(candidate.items.map((item) => item.label));
+      const overlap = [...incomingLabels].filter((label) => candidateLabels.has(label)).length;
+      return overlap >= Math.max(2, Math.ceil(Math.min(incomingLabels.size, candidateLabels.size) * 0.5));
+    });
+    if (cluster) mergeItems(cluster.items, snapshot.items);
+    else mergedSnapshots.push(structuredClone(snapshot));
+  }
+  const pageIdsFor = (snapshot) => docusaurusSidebarHrefs(snapshot).flatMap((href) => {
+    const id = docusaurusRouteIdForUrl(new URL(href), scopePath);
+    return id && imported.has(id) ? [id] : [];
+  });
+  mergedSnapshots.sort((left, right) => pageIdsFor(right).length - pageIdsFor(left).length);
+  const tabs = mergedSnapshots.flatMap((snapshot, snapshotIndex) => {
+    function convert(items) {
+      const converted2 = [];
+      for (const item of items) {
+        const routeId = item.href ? docusaurusRouteIdForUrl(new URL(item.href), scopePath) : null;
+        const page = routeId && imported.has(routeId) && !claimed.has(routeId) ? routeId : null;
+        if (page) claimed.add(page);
+        const children = item.items ? convert(item.items) : [];
+        if (children.length > 0 || item.isCategory) {
+          converted2.push({ group: item.label, pages: page ? [page, ...children] : children });
+          continue;
+        }
+        if (page) converted2.push(page);
+      }
+      return converted2;
+    }
+    const converted = convert(snapshot.items);
+    const loosePages = converted.filter((item) => typeof item === "string");
+    const groups = converted.filter((item) => typeof item !== "string");
+    if (loosePages.length > 0) groups.unshift({ group: "Overview", pages: loosePages });
+    if (groups.length === 0) return [];
+    const snapshotPageIds = pageIdsFor(snapshot);
+    const firstSegments = new Set(snapshotPageIds.map((id) => id.split("/", 1)[0]));
+    const tab = snapshotIndex > 0 && firstSegments.size === 1 ? normalizedLinkLabel([...firstSegments][0].replace(/[-_]/g, " ")).replace(/\b\w/g, (letter) => letter.toUpperCase()) : "Documentation";
+    return [{ tab, groups }];
+  });
+  const additional = pages.map((page) => page.navigationId).filter((id) => !claimed.has(id));
+  if (additional.length > 0) {
+    if (tabs.length === 0) return buildNavigationFromPages(pages);
+    tabs[0].groups?.push({ group: "Additional", pages: additional });
+  }
+  return { tabs };
+}
 function htmlTopLevelNavigation(document, source, scopePath) {
   const $ = load(document.body);
   const collectCandidates = (selector) => {
@@ -1598,24 +2536,54 @@ async function migrateUrl(options) {
   }
   const htmlProbe = /html/i.test(initial.contentType) ? initial : await safeFetch(fetcher, source, "text/html,application/xhtml+xml");
   const scopedHtmlProbe = htmlProbe && isInScope(htmlProbe.finalUrl, source, submittedScopePath) ? htmlProbe : null;
-  const platform = detectUrlPlatform(scopedHtmlProbe ?? initial);
-  const scopePath = platform === "mintlify" ? machineIndexScopePath(source, [initial, scopedHtmlProbe]) ?? submittedScopePath : submittedScopePath;
+  const platform = options.platform ?? detectUrlPlatform(scopedHtmlProbe ?? initial);
+  let docusaurusHtmlProbe = platform === "docusaurus" ? scopedHtmlProbe : null;
+  if (docusaurusHtmlProbe && !readDocusaurusSidebar(docusaurusHtmlProbe)) {
+    const $ = load(docusaurusHtmlProbe.body);
+    const docsHref = $("nav a[href]").toArray().map((element) => ({
+      href: $(element).attr("href"),
+      label: normalizedLinkLabel($(element).text())
+    })).find((link) => /^docs(?:umentation)?$/i.test(link.label))?.href;
+    if (docsHref) {
+      try {
+        const docsUrl = new URL(docsHref, docusaurusHtmlProbe.finalUrl);
+        if (docsUrl.origin === source.origin && isInScope(docsUrl, source, submittedScopePath)) {
+          const probe = await safeFetch(fetcher, docsUrl, "text/html,application/xhtml+xml");
+          if (probe && probe.finalUrl.origin === source.origin && /html/i.test(probe.contentType)) {
+            docusaurusHtmlProbe = probe;
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  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 cache = /* @__PURE__ */ new Map([[source.toString(), initial]]);
+  if (docusaurusHtmlProbe) cache.set(docusaurusHtmlProbe.finalUrl.toString(), docusaurusHtmlProbe);
   const queue = [source];
   const queued = /* @__PURE__ */ new Set([candidateIdentity(source)]);
   const warnings = [];
   const fetchedSitemaps = /* @__PURE__ */ new Set();
+  const docusaurusSidebars = docusaurusDiscovery?.sidebar ? [docusaurusDiscovery.sidebar] : [];
+  const docusaurusRedirects = [];
   function enqueue(value, base) {
     if (queued.size >= MAX_DISCOVERED_URLS) return;
     const url = normalizeCandidate(value, base, source, scopePath);
     if (!url || queued.has(candidateIdentity(url))) return;
+    if (platform === "docusaurus" && url.pathname.replace(/\/+$/, "") === `${scopePath}/search`) return;
+    if (docusaurusDiscovery?.excludedVersionPrefixes.some((prefix) => {
+      const path = url.pathname.replace(/\/+$/, "");
+      return path === prefix || path.startsWith(`${prefix}/`);
+    })) return;
     queued.add(candidateIdentity(url));
     queue.push(url);
   }
-  if (scopedHtmlProbe && /html/i.test(scopedHtmlProbe.contentType)) {
-    for (const link of htmlNavigationLinks(scopedHtmlProbe)) enqueue(link, scopedHtmlProbe.finalUrl);
+  const navigationProbe = docusaurusHtmlProbe ?? scopedHtmlProbe;
+  if (navigationProbe && /html/i.test(navigationProbe.contentType)) {
+    for (const link of htmlNavigationLinks(navigationProbe)) enqueue(link, navigationProbe.finalUrl);
   }
   async function discoverDocumentLinks(document, depth = 0) {
     const links = sitemapLinks(document.body);
@@ -1734,11 +2702,13 @@ async function migrateUrl(options) {
         return { candidate, page: null, links: [], failure: false, budgetExceeded: true };
       }
       importedBytes += responseBytes;
-      const discoveredId = pageIdForUrl(document.finalUrl, scopePath) ?? pageIdForUrl(candidate, scopePath);
-      const id = discoveredId && canonicalLocalizedPageId(discoveredId) === sourceHomePageId ? "introduction" : discoveredId;
-      if (!id) return { candidate, page: null, links: [], failure: false };
+      const discoveredNavigationId = platform === "docusaurus" ? docusaurusRouteIdForUrl(document.finalUrl, scopePath) ?? docusaurusRouteIdForUrl(candidate, scopePath) : pageIdForUrl(document.finalUrl, scopePath) ?? pageIdForUrl(candidate, scopePath);
+      const navigationId = discoveredNavigationId && canonicalLocalizedPageId(discoveredNavigationId) === sourceHomePageId ? "introduction" : discoveredNavigationId;
+      if (!navigationId) return { candidate, page: null, links: [], failure: false };
+      const id = platform === "docusaurus" ? storageIdForDocusaurusRoute(navigationId) : navigationId;
       if (/(?:markdown|text\/plain)/i.test(document.contentType) || /\.mdx?$/i.test(document.finalUrl.pathname)) {
         const markdown = markdownPage(document, id);
+        if (markdown.page) markdown.page.navigationId = navigationId;
         return {
           candidate,
           page: markdown.page,
@@ -1749,7 +2719,9 @@ async function migrateUrl(options) {
         };
       }
       const extracted = htmlPage(document, id);
-      return { candidate, page: extracted.page, links: extracted.links, base: document.finalUrl, failure: false };
+      if (extracted.page) extracted.page.navigationId = navigationId;
+      const sidebar = platform === "docusaurus" ? readDocusaurusSidebar(document) : null;
+      return { candidate, page: extracted.page, links: extracted.links, base: document.finalUrl, sidebar, failure: false };
     }));
     for (const result of results) {
       if (result.failure) {
@@ -1757,7 +2729,10 @@ async function migrateUrl(options) {
         continue;
       }
       if (result.budgetExceeded) continue;
-      if (result.page) result.page.id = canonicalLocalizedPageId(result.page.id);
+      if (result.page && platform !== "docusaurus") {
+        result.page.id = canonicalLocalizedPageId(result.page.id);
+        result.page.navigationId = canonicalLocalizedPageId(result.page.navigationId);
+      }
       const sourceIdentity = result.page ? candidateIdentity(new URL(result.page.source)) : null;
       if (result.page && sourceIdentity && !seenSources.has(sourceIdentity) && !seenIds.has(result.page.id) && pages.length < maxPages) {
         pages.push(result.page);
@@ -1767,6 +2742,16 @@ async function migrateUrl(options) {
         seenIds.add(result.page.id);
         seenSources.add(sourceIdentity);
       }
+      if (platform === "docusaurus" && result.page) {
+        const candidateRoute = docusaurusRouteIdForUrl(result.candidate, scopePath);
+        if (candidateRoute && candidateRoute !== result.page.navigationId) {
+          docusaurusRedirects.push({
+            source: candidateRoute === "introduction" ? "/" : `/${candidateRoute}`,
+            destination: result.page.navigationId === "introduction" ? "/" : `/${result.page.navigationId}`
+          });
+        }
+      }
+      if ("sidebar" in result && result.sidebar) docusaurusSidebars.push(result.sidebar);
       for (const link of result.links) enqueue(link, result.base ?? result.candidate);
     }
   }
@@ -1779,7 +2764,7 @@ async function migrateUrl(options) {
       page.navigationId = navigationSegments.join("/") || "introduction";
     }
   }
-  const importedIds = new Set(pages.map((page) => page.id));
+  const importedIds = new Set(pages.map((page) => page.navigationId));
   for (const page of pages) {
     page.body = rewriteInternalLinks(
       page.body,
@@ -1799,10 +2784,16 @@ async function migrateUrl(options) {
     ...entry,
     pageId: entry.pageId === sourceHomePageId ? "introduction" : entry.pageId
   }));
-  const docsConfig = buildNavigationFromPages(pages, {
+  const docsConfig = platform === "docusaurus" ? docusaurusNavigationFromSnapshots(docusaurusSidebars, pages, scopePath) : buildNavigationFromPages(pages, {
     topLevelTabs: platform === "mintlify",
     topLevelNavigation
   });
+  if (docusaurusRedirects.length > 0) {
+    docsConfig.redirects = [...new Map(docusaurusRedirects.map((redirect) => [
+      `${redirect.source}:${redirect.destination}`,
+      redirect
+    ])).values()];
+  }
   const openApiAsset = mergeEmbeddedOpenApi(openApiFragments);
   if (openApiAsset) {
     const operationPageIds = new Set(pages.filter((page) => page.openapi).map((page) => page.navigationId));