@blaaiz/docs-core 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -1363,6 +1363,22 @@ function validateFeatures(value) {
   }
   optionalBoolean(features["copyPage"], "features.copyPage");
 }
+function validateNavbarAction(value, field) {
+  const action = optionalObject(value, field);
+  if (action === void 0) {
+    return;
+  }
+  requireString(action["text"], `${field}.text`, "Example: 'Dashboard'.");
+  requireString(action["href"], `${field}.href`, "Example: 'https://app.example.com'.");
+}
+function validateNavbar(value) {
+  const navbar = optionalObject(value, "navbar");
+  if (navbar === void 0) {
+    return;
+  }
+  validateNavbarAction(navbar["primary"], "navbar.primary");
+  validateNavbarAction(navbar["secondary"], "navbar.secondary");
+}
 function validateSeo(value) {
   const seo = optionalObject(value, "seo");
   if (seo === void 0) {
@@ -1413,6 +1429,7 @@ function validateDocsConfig(config) {
   validateTheme(config["theme"]);
   validateAuth(config["auth"]);
   validateProxy(config["proxy"]);
+  validateNavbar(config["navbar"]);
   validateFeatures(config["features"]);
   validateSeo(config["seo"]);
   if (config["ai"] !== void 0) {
@@ -1460,6 +1477,90 @@ function buildThemeCss(theme) {
   return blocks.join("\n");
 }
 
+// src/core/redirects.ts
+function redirectTarget(url, redirects) {
+  const { pathname } = url;
+  const markdown = pathname.endsWith(".md");
+  const page = markdown ? pathname.slice(0, -3) : pathname;
+  const destination = redirects[page];
+  if (destination === void 0) {
+    return null;
+  }
+  const target = new URL(url);
+  target.pathname = markdown ? `${destination}.md` : destination;
+  return target;
+}
+
+// src/core/llms-txt.ts
+function buildLlmsTxt(pages, options) {
+  const origin = options.origin?.replace(/\/$/, "") ?? "";
+  const lines = [`# ${options.name}`];
+  if (options.description !== void 0 && options.description !== "") {
+    lines.push("", `> ${options.description}`);
+  }
+  lines.push("", "## Docs", "");
+  for (const page of pages) {
+    const link = `[${page.title}](${origin}${page.url}.md)`;
+    lines.push(
+      page.description === void 0 || page.description === "" ? `- ${link}` : `- ${link}: ${page.description}`
+    );
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/core/code-samples.ts
+function singleQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function bodyToString(body, mediaType) {
+  if (typeof body === "string") {
+    return body;
+  }
+  if (mediaType === "application/x-www-form-urlencoded" && isRecord(body)) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(body)) {
+      if (value === void 0 || value === null) {
+        continue;
+      }
+      const encoded = typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : JSON.stringify(value);
+      params.set(key, encoded);
+    }
+    return params.toString();
+  }
+  if (mediaType === "application/x-ndjson" && Array.isArray(body)) {
+    return body.map((entry) => JSON.stringify(entry)).join("\n");
+  }
+  return JSON.stringify(body, null, 2);
+}
+var curlCodeUsage = {
+  label: "cURL",
+  lang: "bash",
+  generate(data) {
+    const lines = [`curl --request ${data.method.toUpperCase()}`, `--url ${singleQuote(data.url)}`];
+    for (const [name, param] of Object.entries(data.header ?? {})) {
+      lines.push(`--header ${singleQuote(`${name}: ${param.value}`)}`);
+    }
+    for (const [name, param] of Object.entries(data.cookie ?? {})) {
+      lines.push(`--cookie ${singleQuote(`${name}=${param.value}`)}`);
+    }
+    if (isRecord(data.body) && data.bodyMediaType === "multipart/form-data") {
+      for (const [key, value] of Object.entries(data.body)) {
+        lines.push(
+          `--form ${singleQuote(`${key}=${typeof value === "string" ? value : JSON.stringify(value)}`)}`
+        );
+      }
+    } else if (data.body !== void 0 && data.body !== null && data.bodyMediaType !== void 0) {
+      lines.push(`--header ${singleQuote(`Content-Type: ${data.bodyMediaType}`)}`);
+      lines.push(`--data ${singleQuote(bodyToString(data.body, data.bodyMediaType))}`);
+    }
+    return lines.map((line, i) => i === 0 ? line : `  ${line}`).join(" \\\n");
+  }
+};
+
 // src/core/seo.ts
 function trimTrailingSlash(value) {
   return value.replace(/\/+$/, "");
@@ -1562,12 +1663,13 @@ function firstDocFile(items) {
 }
 function planDocsTree(navigation, options = {}) {
   const apiDir = options.apiDir ?? "api";
+  const headings = (options.sidebar ?? "collapsible") === "headings";
   const specs = [];
   const apiPages = [];
   const apiGroups = [];
   const metas = [];
   const rootPages = [];
-  const apiTabDocPages = [];
+  const apiDocLinks = [];
   const apiTabs = navigation.filter((tab) => hasOpenApi(tab.items));
   const soleApiTab = apiTabs.length === 1;
   for (const tab of navigation) {
@@ -1578,7 +1680,7 @@ function planDocsTree(navigation, options = {}) {
     planDocTab(tab);
   }
   metas.unshift({ path: "meta.json", content: { pages: rootPages } });
-  return { specs, apiPages, apiGroups, metas, apiTabDocPages };
+  return { specs, apiPages, apiGroups, metas, apiDocLinks };
   function planApiTab(tab) {
     const tabDir = soleApiTab ? apiDir : slugify(tab.title);
     rootPages.push(tabDir);
@@ -1609,7 +1711,7 @@ function planDocsTree(navigation, options = {}) {
         const at = apiGroups.length;
         const sub = planApiItems(item.items, childDir);
         apiGroups.splice(at, 0, { dir: childDir, title: item.title, children: sub });
-        children.push({ order, folder });
+        children.push({ order, folder, title: item.title });
         order += 1;
         continue;
       }
@@ -1621,7 +1723,8 @@ function planDocsTree(navigation, options = {}) {
         order += 1;
         continue;
       }
-      apiTabDocPages.push(item.file);
+      apiDocLinks.push({ file: item.file, dir, order });
+      order += 1;
     }
     return children;
   }
@@ -1646,11 +1749,11 @@ function planDocsTree(navigation, options = {}) {
         title: tab.title,
         root: true,
         ...tab.icon ? { icon: tab.icon } : {},
-        pages: planDocItems(tab.items, tabDir)
+        pages: planDocItems(tab.items, tabDir, true)
       }
     });
   }
-  function planDocItems(items, dir) {
+  function planDocItems(items, dir, tabLevel) {
     const entries = [];
     for (const item of items) {
       if (item.kind === "doc") {
@@ -1665,10 +1768,18 @@ function planDocsTree(navigation, options = {}) {
         continue;
       }
       if (groupDir === dir) {
-        entries.push(...planDocItems(item.items, dir));
+        if (headings) {
+          entries.push(`---${item.title}---`);
+        }
+        entries.push(...planDocItems(item.items, dir, false));
+        continue;
+      }
+      const folder = groupDir.slice(dir.length + 1);
+      if (headings && tabLevel) {
+        entries.push(`---${item.title}---`, `...${folder}`);
         continue;
       }
-      entries.push(groupDir.slice(dir.length + 1));
+      entries.push(folder);
     }
     return entries;
   }
@@ -1683,7 +1794,14 @@ function planDocsTree(navigation, options = {}) {
     }
     metas.push({
       path: `${groupDir}/meta.json`,
-      content: { title: group.title, pages: planDocItems(group.items, groupDir) }
+      content: {
+        title: group.title,
+        // A nested group starts closed in the headings style, whatever the
+        // site's defaultOpenLevel. On a tab-level group the flag is inert:
+        // that folder is extracted, so no folder node renders it.
+        ...headings ? { defaultOpen: false } : {},
+        pages: planDocItems(group.items, groupDir, false)
+      }
     });
     return groupDir;
   }
@@ -2116,10 +2234,67 @@ ${description ? `${description}
 ` : ""}${cleanBody(trimmedBody)}
 `;
 }
+function operationHead(operation) {
+  let title;
+  let description;
+  try {
+    const parsed = JSON.parse(operation.source);
+    const exact = parsed.paths?.[operation.route]?.[operation.method.toLowerCase()];
+    const first = Object.values(parsed.paths ?? {}).flatMap((item) => Object.values(item))[0];
+    const named = exact ?? first;
+    title = named?.summary ?? parsed.info?.title;
+    description = named?.description ?? parsed.info?.description;
+  } catch {
+  }
+  const head = [`# ${title ?? "API operation"}`];
+  if (description !== void 0 && description !== "") {
+    head.push("", `> ${description.replace(/\n/g, "\n> ")}`);
+  }
+  return head.join("\n");
+}
+function fenceFor(source) {
+  const longest = source.match(/`+/g)?.reduce((max, run) => Math.max(max, run.length), 0) ?? 0;
+  return "`".repeat(Math.max(4, longest + 1));
+}
 function createMarkdownRoute(options) {
+  const requestOrigin = (request) => {
+    const url = new URL(request.url);
+    const proto = request.headers.get("x-forwarded-proto") ?? url.protocol.replace(/:$/, "");
+    const host = request.headers.get("x-forwarded-host") ?? request.headers.get("host") ?? url.host;
+    return `${proto}://${host}`;
+  };
+  const respond = (request, markdown) => {
+    const preamble = options.llmsTxtPath === void 0 ? "" : [
+      "> ## Documentation Index",
+      `> Fetch the complete documentation index at: ${requestOrigin(request)}${options.llmsTxtPath}`,
+      "> Use this file to discover all available pages before exploring further.",
+      "",
+      ""
+    ].join("\n");
+    return new Response(`${preamble}${markdown}`, {
+      headers: { "content-type": "text/plain; charset=utf-8" }
+    });
+  };
   return {
-    async GET(_request, context) {
+    async GET(request, context) {
       const { slug } = await context.params;
+      const operation = await options.loadOperationSource?.(slug);
+      if (operation) {
+        const fence = fenceFor(operation.source);
+        return respond(
+          request,
+          [
+            operationHead(operation),
+            "",
+            "## OpenAPI",
+            "",
+            `${fence}json ${operation.file} ${operation.method.toLowerCase()} ${operation.route}`,
+            operation.source.trimEnd(),
+            fence,
+            ""
+          ].join("\n")
+        );
+      }
       const raw = await options.read(slug);
       if (raw === null) {
         return new Response("Not found", { status: 404 });
@@ -2133,12 +2308,32 @@ function createMarkdownRoute(options) {
       if (markdown === null) {
         return new Response("Not found", { status: 404 });
       }
-      return new Response(markdown, {
-        headers: { "content-type": "text/plain; charset=utf-8" }
-      });
+      return respond(request, markdown);
     }
   };
 }
+function markdownRewriteTarget(url, options = {}) {
+  const baseUrl = (options.baseUrl ?? "/docs").replace(/\/+$/, "");
+  const markdownBase = (options.markdownBase ?? "/md").replace(/\/+$/, "");
+  const { pathname } = url;
+  if (!pathname.endsWith(".md") || pathname.includes("%")) {
+    return null;
+  }
+  const page = pathname.slice(0, -3);
+  if (page !== baseUrl && !page.startsWith(`${baseUrl}/`)) {
+    return null;
+  }
+  if (page.endsWith("/") || page.includes("//")) {
+    return null;
+  }
+  const target = new URL(url);
+  target.pathname = `${markdownBase}${page.slice(baseUrl.length)}`;
+  return target;
+}
+function isMarkdownRouteRequest(url, options = {}) {
+  const markdownBase = options.markdownBase ?? "/md";
+  return url.pathname === markdownBase || url.pathname.startsWith(`${markdownBase}/`);
+}
 
 // src/core/auth/domains.ts
 function isAllowedEmail(email, allowedDomains) {
@@ -2922,7 +3117,7 @@ var InvalidNavigationError = class extends Error {
     this.name = "InvalidNavigationError";
   }
 };
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function parsePageString(entry) {
@@ -2945,7 +3140,7 @@ function parseItem(entry, path) {
   if (typeof entry === "string") {
     return parsePageString(entry);
   }
-  if (isRecord(entry) && typeof entry["group"] === "string") {
+  if (isRecord2(entry) && typeof entry["group"] === "string") {
     return parseGroup(entry, path);
   }
   throw new InvalidNavigationError(
@@ -2970,7 +3165,7 @@ function parseGroup(group, path) {
   };
 }
 function parseTab(tab, path) {
-  if (!isRecord(tab) || typeof tab["tab"] !== "string") {
+  if (!isRecord2(tab) || typeof tab["tab"] !== "string") {
     throw new InvalidNavigationError(`Tab at ${path} is missing a string "tab" title.`);
   }
   const items = tab["groups"] !== void 0 ? parseGroups(tab["groups"], `${path}.groups`) : parseItems(tab["pages"], `${path}.pages`);
@@ -2988,18 +3183,18 @@ function parseGroups(groups, path) {
   }
   return groups.map((group, index) => {
     const groupPath = `${path}[${String(index)}]`;
-    if (!isRecord(group)) {
+    if (!isRecord2(group)) {
       throw new InvalidNavigationError(`Group at ${groupPath} must be an object.`);
     }
     return parseGroup(group, groupPath);
   });
 }
 function parseNavigation(docsJson) {
-  if (!isRecord(docsJson)) {
+  if (!isRecord2(docsJson)) {
     throw new InvalidNavigationError("docs.json must be an object.");
   }
   const navigation = docsJson["navigation"];
-  if (!isRecord(navigation)) {
+  if (!isRecord2(navigation)) {
     throw new InvalidNavigationError('docs.json must have a "navigation" object.');
   }
   const tabs = navigation["tabs"];
@@ -3016,7 +3211,7 @@ var OpenApiMergeError = class extends Error {
     this.name = "OpenApiMergeError";
   }
 };
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function collectServers(inputs, override) {
@@ -3030,7 +3225,7 @@ function collectServers(inputs, override) {
       continue;
     }
     for (const server of servers) {
-      if (isRecord2(server) && typeof server["url"] === "string" && !byUrl.has(server["url"])) {
+      if (isRecord3(server) && typeof server["url"] === "string" && !byUrl.has(server["url"])) {
         byUrl.set(server["url"], server);
       }
     }
@@ -3045,7 +3240,7 @@ function collectTags(inputs) {
       continue;
     }
     for (const tag of tags) {
-      if (isRecord2(tag) && typeof tag["name"] === "string" && !byName.has(tag["name"])) {
+      if (isRecord3(tag) && typeof tag["name"] === "string" && !byName.has(tag["name"])) {
         byName.set(tag["name"], tag);
       }
     }
@@ -3056,11 +3251,11 @@ function mergeComponents(inputs) {
   const merged = {};
   for (const doc of inputs) {
     const components = doc["components"];
-    if (!isRecord2(components)) {
+    if (!isRecord3(components)) {
       continue;
     }
     for (const [section, value] of Object.entries(components)) {
-      if (!isRecord2(value)) {
+      if (!isRecord3(value)) {
         continue;
       }
       const target = merged[section] ?? (merged[section] = {});
@@ -3078,12 +3273,12 @@ function assemblePaths(inputs) {
   const paths = {};
   for (const doc of inputs) {
     const docPaths = doc["paths"];
-    if (!isRecord2(docPaths)) {
+    if (!isRecord3(docPaths)) {
       throw new OpenApiMergeError('Each OpenAPI input must have a "paths" object.');
     }
     const docSecurity = doc["security"];
     for (const [route, pathItem] of Object.entries(docPaths)) {
-      if (!isRecord2(pathItem)) {
+      if (!isRecord3(pathItem)) {
         throw new OpenApiMergeError(`Path item for "${route}" must be an object.`);
       }
       const target = paths[route] ?? (paths[route] = {});
@@ -3094,7 +3289,7 @@ function assemblePaths(inputs) {
           );
         }
         let resolved = operation;
-        if (HTTP_METHODS2.has(method.toLowerCase()) && isRecord2(operation) && !("security" in operation) && Array.isArray(docSecurity)) {
+        if (HTTP_METHODS2.has(method.toLowerCase()) && isRecord3(operation) && !("security" in operation) && Array.isArray(docSecurity)) {
           resolved = { ...operation, security: docSecurity };
         }
         target[method] = resolved;
@@ -3105,7 +3300,7 @@ function assemblePaths(inputs) {
 }
 function mergeOpenApiDocuments(inputs, options) {
   const records = inputs.map((input, index) => {
-    if (!isRecord2(input)) {
+    if (!isRecord3(input)) {
       throw new OpenApiMergeError(`OpenAPI input at index ${String(index)} must be an object.`);
     }
     return input;
@@ -3129,6 +3324,7 @@ exports.OpenApiMergeError = OpenApiMergeError;
 exports.ProxyTargetError = ProxyTargetError;
 exports.SESSION_COOKIE = SESSION_COOKIE;
 exports.assertAllowedTarget = assertAllowedTarget;
+exports.buildLlmsTxt = buildLlmsTxt;
 exports.buildMetadata = buildMetadata;
 exports.buildRobots = buildRobots;
 exports.buildSearchIndex = buildSearchIndex;
@@ -3146,14 +3342,18 @@ exports.createSignOut = createSignOut;
 exports.createSiteAuth = createSiteAuth;
 exports.createTryItProxy = createTryItProxy;
 exports.createTryItProxyRoute = createTryItProxyRoute;
+exports.curlCodeUsage = curlCodeUsage;
 exports.defineDocsConfig = defineDocsConfig;
 exports.isAllowedEmail = isAllowedEmail;
+exports.isMarkdownRouteRequest = isMarkdownRouteRequest;
+exports.markdownRewriteTarget = markdownRewriteTarget;
 exports.mdxToMarkdown = mdxToMarkdown;
 exports.mergeOpenApiDocuments = mergeOpenApiDocuments;
 exports.openApiOperationToMarkdown = openApiOperationToMarkdown;
 exports.parseNavigation = parseNavigation;
 exports.planDocsTree = planDocsTree;
 exports.readCookie = readCookie;
+exports.redirectTarget = redirectTarget;
 exports.resolveAiConfig = resolveAiConfig;
 exports.searchIndex = searchIndex;
 exports.signSession = signSession;