blodemd 0.0.13 → 0.0.15

package/packages/@repo/previewing/src/markdown/agent-markdown.ts

@@ -0,0 +1,254 @@
+import { NEWLINE_REGEX } from "../constants.js";
+import { absolutiseInternalLinks, sanitizePlaceholderUrls } from "./links.js";
+
+const FENCED_CODE_BLOCK_REGEX =
+  /(^|\n)(`{3,}|~{3,})[^\n]*\n[\s\S]*?\n\2(?=\n|$)/g;
+const TYPE_TABLE_REGEX = /<TypeTable\s+type=\{\{([\s\S]*?)\}\}\s*\/>/g;
+const TYPE_TABLE_ROW_HEADER_REGEX =
+  /^\s*(["']?[\w$./<>|{}\-\s]+["']?)\s*:\s*\{\s*$/;
+const STRING_FIELD_REGEX = (field: string) =>
+  new RegExp(`${field}:\\s*(?:"([^"]*)"|'([^']*)'|\`([^\`]*)\`)`, "s");
+const BOOLEAN_FIELD_REGEX = (field: string) =>
+  new RegExp(`${field}:\\s*(true|false)`, "s");
+
+const getStringProp = (attributes: string, name: string) => {
+  const match = new RegExp(
+    `${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|\\{\\s*"([^"]*)"\\s*\\}|\\{\\s*'([^']*)'\\s*\\})`
+  ).exec(attributes);
+  return match?.slice(1).find((value) => typeof value === "string");
+};
+
+const protectFencedCodeBlocks = (source: string) => {
+  const blocks: string[] = [];
+  const text = source.replace(FENCED_CODE_BLOCK_REGEX, (match) => {
+    const placeholder = `\n@@BLODEMD_CODE_BLOCK_${blocks.length}@@\n`;
+    blocks.push(match.trim());
+    return placeholder;
+  });
+  return { blocks, text };
+};
+
+const restoreFencedCodeBlocks = (source: string, blocks: string[]) => {
+  let restored = source;
+  for (const [index, block] of blocks.entries()) {
+    // Function replacer: code may contain `$&`, `$1`, `` $` `` etc. which a
+    // string replacement would interpret as substitution patterns.
+    restored = restored.replace(`@@BLODEMD_CODE_BLOCK_${index}@@`, () => block);
+  }
+  return restored;
+};
+
+const INLINE_CODE_REGEX = /(?<![\\`])`([^`\n]+)`(?!`)/g;
+
+const protectInlineCode = (source: string) => {
+  const spans: string[] = [];
+  const text = source.replace(INLINE_CODE_REGEX, (match) => {
+    const placeholder = `@@BLODEMD_INLINE_CODE_${spans.length}@@`;
+    spans.push(match);
+    return placeholder;
+  });
+  return { spans, text };
+};
+
+const restoreInlineCode = (source: string, spans: string[]) => {
+  let restored = source;
+  for (const [index, span] of spans.entries()) {
+    restored = restored.replace(`@@BLODEMD_INLINE_CODE_${index}@@`, () => span);
+  }
+  return restored;
+};
+
+const compactMarkdown = (source: string) =>
+  source
+    .replaceAll(/[ \t]+\n/g, "\n")
+    .replaceAll(/\n{3,}/g, "\n\n")
+    .trim();
+
+const getFieldStringValue = (block: string, field: string) => {
+  const match = STRING_FIELD_REGEX(field).exec(block);
+  return match?.slice(1).find((value) => typeof value === "string");
+};
+
+const getFieldBooleanValue = (block: string, field: string) => {
+  const match = BOOLEAN_FIELD_REGEX(field).exec(block);
+  return match?.[1];
+};
+
+const renderTypeTable = (_match: string, body: string) => {
+  const rows: string[] = [];
+  const lines = body.split(NEWLINE_REGEX);
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const header = TYPE_TABLE_ROW_HEADER_REGEX.exec(lines[index] ?? "");
+    if (!header) {
+      continue;
+    }
+
+    const name = (header[1] ?? "").replaceAll(/^["']|["']$/g, "").trim();
+    const blockLines: string[] = [];
+    index += 1;
+    while (index < lines.length) {
+      const line = lines[index] ?? "";
+      if (/^\s*\},?\s*$/.test(line)) {
+        break;
+      }
+      blockLines.push(line);
+      index += 1;
+    }
+
+    const block = blockLines.join("\n");
+    const type = getFieldStringValue(block, "type") ?? "";
+    const description = getFieldStringValue(block, "description") ?? "";
+    const required = getFieldBooleanValue(block, "required") ?? "";
+    const defaultValue = getFieldStringValue(block, "default") ?? "";
+    const meta = [
+      type ? `type: ${type}` : null,
+      required ? `required: ${required}` : null,
+      defaultValue ? `default: ${defaultValue}` : null,
+    ]
+      .filter(Boolean)
+      .join(", ");
+    rows.push(`- \`${name}\`${meta ? ` (${meta})` : ""}: ${description}`);
+  }
+
+  return rows.length ? rows.join("\n") : "";
+};
+
+const transformMdxComponents = (source: string) => {
+  let output = source;
+
+  output = output.replaceAll(TYPE_TABLE_REGEX, renderTypeTable);
+  output = output.replaceAll(
+    /<Installer\s+([^>]*)\/>/g,
+    (_match, attributes: string) => {
+      const command = getStringProp(attributes, "command");
+      return command ? `\`\`\`bash\n${command}\n\`\`\`` : "";
+    }
+  );
+  output = output.replaceAll(
+    /<Tree\.Folder\s+([^>]*)>/g,
+    (_match, attributes: string) => {
+      const name = getStringProp(attributes, "name") ?? "folder";
+      return `- ${name}/`;
+    }
+  );
+  output = output.replaceAll(
+    /<Tree\.File\s+([^>]*)\/>/g,
+    (_match, attributes: string) => {
+      const name = getStringProp(attributes, "name") ?? "file";
+      return `- ${name}`;
+    }
+  );
+  output = output.replaceAll("</Tree.Folder>", "");
+  output = output.replaceAll(/<\/?Tree[^>]*>/g, "");
+  output = output.replaceAll(
+    /<Frame(?=[\s>])\s*([^>]*)>([\s\S]*?)<\/Frame>/g,
+    (_match, attributes: string, children: string) => {
+      const caption = getStringProp(attributes, "caption");
+      const hint = getStringProp(attributes, "hint");
+      return compactMarkdown(
+        [hint, children.trim(), caption ? `Caption: ${caption}` : null]
+          .filter(Boolean)
+          .join("\n\n")
+      );
+    }
+  );
+  output = output.replaceAll(
+    /<Callout(?=[\s>])\s*([^>]*)>([\s\S]*?)<\/Callout>/g,
+    (_match, attributes: string, children: string) => {
+      const type = (getStringProp(attributes, "type") ?? "note").toUpperCase();
+      return `> [!${type}]\n${children
+        .trim()
+        .split(NEWLINE_REGEX)
+        .map((line) => `> ${line}`)
+        .join("\n")}`;
+    }
+  );
+  for (const [tag, type] of [
+    ["Note", "NOTE"],
+    ["Warning", "WARNING"],
+    ["Info", "INFO"],
+    ["Tip", "TIP"],
+    ["Check", "CHECK"],
+    ["Danger", "DANGER"],
+  ] as const) {
+    output = output.replaceAll(
+      new RegExp(`<${tag}(?=[\\s>])\\s*[^>]*>([\\s\\S]*?)</${tag}>`, "g"),
+      (_match, children: string) =>
+        `> [!${type}]\n${children
+          .trim()
+          .split(NEWLINE_REGEX)
+          .map((line) => `> ${line}`)
+          .join("\n")}`
+    );
+  }
+  output = output.replaceAll(
+    /<Accordion(?=[\s>])\s*([^>]*)>([\s\S]*?)<\/Accordion>/g,
+    (_match, attributes: string, children: string) => {
+      const title = getStringProp(attributes, "title") ?? "Details";
+      return `### ${title}\n\n${children.trim()}`;
+    }
+  );
+  output = output.replaceAll(
+    /<Tab\s+([^>]*)>([\s\S]*?)<\/Tab>/g,
+    (_match, attributes: string, children: string) => {
+      const title =
+        getStringProp(attributes, "title") ??
+        getStringProp(attributes, "label") ??
+        "Tab";
+      return `### ${title}\n\n${children.trim()}`;
+    }
+  );
+  output = output.replaceAll(
+    /<Step\s+([^>]*)>([\s\S]*?)<\/Step>/g,
+    (_match, attributes: string, children: string) => {
+      const title = getStringProp(attributes, "title") ?? "Step";
+      return `1. **${title}**\n\n${children.trim()}`;
+    }
+  );
+  output = output.replaceAll(
+    /<Expandable(?=[\s>])\s*([^>]*)>([\s\S]*?)<\/Expandable>/g,
+    (_match, attributes: string, children: string) => {
+      const title = getStringProp(attributes, "title") ?? "Details";
+      return `### ${title}\n\n${children.trim()}`;
+    }
+  );
+  output = output.replaceAll(
+    /<Card(?=[\s>])\s*([^>]*)>([\s\S]*?)<\/Card>/g,
+    (_match, attributes: string, children: string) => {
+      const title = getStringProp(attributes, "title");
+      const href = getStringProp(attributes, "href");
+      const heading = title
+        ? `### ${href ? `[${title}](${href})` : title}`
+        : "";
+      return compactMarkdown(
+        [heading, children.trim()].filter(Boolean).join("\n\n")
+      );
+    }
+  );
+  output = output.replaceAll(
+    /<\/?(?:Columns|Column|CodeGroup|Tabs|Steps|AccordionGroup|CardGroup)[^>]*>/g,
+    ""
+  );
+
+  return compactMarkdown(output);
+};
+
+export const toAgentMarkdown = (source: string): string => {
+  const { blocks, text: codeProtected } = protectFencedCodeBlocks(source);
+  const { spans, text: inlineProtected } = protectInlineCode(codeProtected);
+  const transformed = transformMdxComponents(inlineProtected);
+  const inlineRestored = restoreInlineCode(transformed, spans);
+  return compactMarkdown(restoreFencedCodeBlocks(inlineRestored, blocks));
+};
+
+export const prepareLlmsFullContent = (
+  source: string,
+  origin: string,
+  basePath: string
+) =>
+  absolutiseInternalLinks(
+    sanitizePlaceholderUrls(toAgentMarkdown(source)),
+    origin,
+    basePath
+  );

package/packages/@repo/previewing/src/markdown/format.ts

@@ -0,0 +1,63 @@
+import { slugify } from "@repo/common";
+import YAML from "yaml";
+
+const FRONTMATTER_REGEX = /^---\s*\n([\s\S]*?)\n---\s*\n?/;
+const LEADING_H1_REGEX = /^#\s+([^\r\n]+)(?:\r?\n(?:\r?\n)?)?/;
+
+export const parseFrontmatter = (source: string) => {
+  const match = FRONTMATTER_REGEX.exec(source);
+  if (!match) {
+    return { body: source, frontmatter: {} };
+  }
+  const raw = match[1] ?? "";
+  const data = YAML.parse(raw) ?? {};
+  const body = source.slice(match[0].length);
+  return { body, frontmatter: data };
+};
+
+export const stripFrontmatter = (source: string) =>
+  parseFrontmatter(source).body.trim();
+
+const stripMatchingLeadingH1 = (source: string, title: string) => {
+  const trimmed = source.trimStart();
+  const match = LEADING_H1_REGEX.exec(trimmed);
+  if (!match) {
+    return trimmed.trim();
+  }
+
+  const [headingLine = "", headingTitle = ""] = match;
+  if (slugify(headingTitle) !== slugify(title)) {
+    return trimmed.trim();
+  }
+
+  return trimmed.slice(headingLine.length).trim();
+};
+
+export const formatMarkdownPage = (
+  title: string,
+  source: string,
+  description?: string
+) => {
+  const content = stripMatchingLeadingH1(source, title);
+  const descriptionBlock = description ? `\n\n${description}` : "";
+  if (!content) {
+    return `# ${title}${descriptionBlock}`;
+  }
+
+  return `# ${title}${descriptionBlock}\n\n${content}`;
+};
+
+export const formatMarkdownPageSection = (
+  title: string,
+  url: string,
+  source: string,
+  description?: string
+) => {
+  const content = stripMatchingLeadingH1(source, title);
+  const descriptionBlock = description ? `\n\n${description}` : "";
+  if (!content) {
+    return `# ${title} (${url})${descriptionBlock}`;
+  }
+
+  return `# ${title} (${url})${descriptionBlock}\n\n${content}`;
+};

package/packages/@repo/previewing/src/markdown/links.ts

@@ -0,0 +1,46 @@
+const PLACEHOLDER_URL_PATTERN = [
+  "https?://(?:[a-z0-9-]+\\.)*example\\.(?:com|org|net)\\b[^\\s)\\]\"'<>]*",
+  "https?://discord\\.gg/example\\b[^\\s)\\]\"'<>]*",
+  "https?://(?:[a-z0-9-]+\\.)+(?:test|invalid)(?:[/?#:][^\\s)\\]\"'<>]*)?",
+  "https?://localhost(?::\\d+)?[^\\s)\\]\"'<>]*",
+  "https?://(?:[a-z0-9-]+\\.)*your[-_]?domain\\.[a-z]+\\b[^\\s)\\]\"'<>]*",
+  "https?://acme\\.blode\\.md\\b[^\\s)\\]\"'<>]*",
+  "https?://github\\.com/example/[^\\s)\\]\"'<>]*",
+  "https?://(?:us|eu)\\.i\\.posthog\\.com\\b[^\\s)\\]\"'<>]*",
+].join("|");
+const PLACEHOLDER_URL_RE = new RegExp(PLACEHOLDER_URL_PATTERN, "gi");
+const PLACEHOLDER_MARKDOWN_LINK_RE = new RegExp(
+  `\\[([^\\]]+)\\]\\((?:${PLACEHOLDER_URL_PATTERN})\\)`,
+  "gi"
+);
+const INTERNAL_MARKDOWN_LINK_RE = /(!?\[[^\]]+\])\((\/[^)\s]*)\)/g;
+
+const defangUrl = (value: string) => value.replace(/^https?:\/\//i, "");
+
+export const sanitizePlaceholderUrls = (text: string): string =>
+  text
+    .replace(PLACEHOLDER_MARKDOWN_LINK_RE, "$1")
+    .replace(PLACEHOLDER_URL_RE, (match) => `\`${defangUrl(match)}\``);
+
+export const absolutiseInternalLinks = (
+  source: string,
+  origin: string,
+  basePath: string
+): string => {
+  const normalizedBase = basePath
+    ? `/${basePath}`.replaceAll(/\/+/g, "/").replace(/\/$/, "")
+    : "";
+  return source.replaceAll(
+    INTERNAL_MARKDOWN_LINK_RE,
+    (_match, label, linkPath) => {
+      const alreadyPrefixed =
+        normalizedBase &&
+        (linkPath === normalizedBase ||
+          linkPath.startsWith(`${normalizedBase}/`));
+      const absolutePath = alreadyPrefixed
+        ? linkPath
+        : `${normalizedBase}${linkPath}`.replaceAll(/\/+/g, "/");
+      return `${label}(${origin}${absolutePath})`;
+    }
+  );
+};

package/packages/@repo/previewing/src/openapi-pages.ts

@@ -0,0 +1,319 @@
+import { ensureArray, normalizePath } from "@repo/common";
+import type {
+  CollectionConfig,
+  DocsOpenApiSource,
+  SiteConfig,
+} from "@repo/models";
+import {
+  extractOpenApiOperations,
+  openApiIdentifier,
+  openApiSlug,
+  parseOpenApiSpec,
+} from "@repo/prebuild";
+import type { OpenApiOperation } from "@repo/prebuild";
+
+import { getDocsNavigation } from "./config-loader.js";
+import type { ContentSource } from "./content-source.js";
+import type { UtilityPage } from "./types.js";
+
+interface UtilityOpenApiPage extends UtilityPage {
+  identifier: string;
+  sourceKey: string;
+}
+
+const getOpenApiSourceKey = (source: DocsOpenApiSource): string =>
+  `${source.source}::${source.directory ?? ""}::${(source.include ?? []).join(
+    "|"
+  )}`;
+
+const toOpenApiSourceObject = (
+  value: string | DocsOpenApiSource
+): DocsOpenApiSource => {
+  if (typeof value === "string") {
+    return { source: value };
+  }
+  return value;
+};
+
+const collectOpenApiSources = (collection?: CollectionConfig) => {
+  const sources: DocsOpenApiSource[] = [];
+
+  for (const item of ensureArray(collection?.openapi)) {
+    if (!item) {
+      continue;
+    }
+    sources.push(toOpenApiSourceObject(item));
+  }
+
+  const groups = collection?.navigation?.groups ?? [];
+  for (const group of groups) {
+    if (!group.openapi) {
+      continue;
+    }
+    sources.push(toOpenApiSourceObject(group.openapi));
+  }
+
+  const seen = new Set<string>();
+  return sources.filter((source) => {
+    const key = getOpenApiSourceKey(source);
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+};
+
+const getSchemaTypeLabel = (schema: unknown): string => {
+  if (!schema || typeof schema !== "object") {
+    return "any";
+  }
+  const record = schema as Record<string, unknown>;
+  if (typeof record.$ref === "string") {
+    const last = record.$ref.split("/").pop();
+    return last ?? "object";
+  }
+  if (typeof record.type === "string") {
+    if (record.type === "array" && record.items) {
+      return `${getSchemaTypeLabel(record.items)}[]`;
+    }
+    return record.type;
+  }
+  if (Array.isArray(record.oneOf) || Array.isArray(record.anyOf)) {
+    const variants = (record.oneOf ?? record.anyOf) as unknown[];
+    return variants.map(getSchemaTypeLabel).join(" | ");
+  }
+  return "object";
+};
+
+const formatParameterLine = (parameter: Record<string, unknown>): string => {
+  const name = String(parameter.name ?? "");
+  const location = parameter.in ? ` (${parameter.in})` : "";
+  const required = parameter.required ? "required" : "optional";
+  const type = getSchemaTypeLabel(parameter.schema);
+  const description =
+    typeof parameter.description === "string" && parameter.description
+      ? ` - ${parameter.description.split("\n")[0]}`
+      : "";
+  return `- \`${name}\`${location}: ${type}, ${required}${description}`;
+};
+
+const formatRequestBody = (body: Record<string, unknown>): string => {
+  const required = body.required ? "required" : "optional";
+  const content = (body.content as Record<string, unknown> | undefined) ?? {};
+  const mediaTypes = Object.keys(content);
+  if (mediaTypes.length === 0) {
+    return `${required} body`;
+  }
+  return mediaTypes
+    .map((mediaType) => {
+      const mediaEntry = content[mediaType] as
+        | Record<string, unknown>
+        | undefined;
+      const schemaLabel = getSchemaTypeLabel(mediaEntry?.schema);
+      return `- ${mediaType} (${required}): ${schemaLabel}`;
+    })
+    .join("\n");
+};
+
+const formatResponses = (responses: Record<string, unknown>): string =>
+  Object.entries(responses)
+    .map(([status, value]) => {
+      const response = (value as Record<string, unknown>) ?? {};
+      const description =
+        typeof response.description === "string" && response.description
+          ? response.description.split("\n")[0]
+          : "";
+      const content =
+        (response.content as Record<string, unknown> | undefined) ?? {};
+      const mediaTypes = Object.keys(content);
+      const mediaSuffix = mediaTypes.length
+        ? ` [${mediaTypes.join(", ")}]`
+        : "";
+      return `- ${status}${mediaSuffix}${description ? ` - ${description}` : ""}`;
+    })
+    .join("\n");
+
+export const formatOpenApiPageContent = (
+  operation: OpenApiOperation
+): string => {
+  const parts = [`Method: ${operation.method}`, `Path: ${operation.path}`];
+
+  if (operation.description) {
+    parts.push(operation.description);
+  }
+  if (operation.tags.length) {
+    parts.push(`Tags: ${operation.tags.join(", ")}`);
+  }
+  if (operation.parameters.length) {
+    parts.push(
+      `## Parameters\n\n${operation.parameters
+        .map(formatParameterLine)
+        .join("\n")}`
+    );
+  }
+  if (operation.requestBody) {
+    parts.push(
+      `## Request body\n\n${formatRequestBody(operation.requestBody)}`
+    );
+  }
+  if (operation.responses) {
+    parts.push(`## Responses\n\n${formatResponses(operation.responses)}`);
+  }
+
+  return parts.join("\n\n");
+};
+
+const getGroupedOpenApiSourceKey = (
+  source: string | DocsOpenApiSource
+): string => getOpenApiSourceKey(toOpenApiSourceObject(source));
+
+const collectUtilityOpenApiPages = (
+  pagesByIdentifier: Map<string, UtilityOpenApiPage>,
+  pagesBySource: Map<string, UtilityOpenApiPage[]>,
+  operations: OpenApiOperation[],
+  directory: string,
+  openApiSource: DocsOpenApiSource,
+  slugPrefix: string
+) => {
+  const sourceKey = getOpenApiSourceKey(openApiSource);
+  const includeIdentifiers = openApiSource.include?.length
+    ? new Set(openApiSource.include)
+    : null;
+
+  for (const operation of operations) {
+    const identifier = openApiIdentifier(operation.method, operation.path);
+    if (includeIdentifiers && !includeIdentifiers.has(identifier)) {
+      continue;
+    }
+
+    const baseSlug = normalizePath(
+      openApiSlug(operation.method, operation.path, directory)
+    );
+    const slug = slugPrefix
+      ? normalizePath(`${slugPrefix}/${baseSlug}`)
+      : baseSlug;
+    const page = {
+      content: formatOpenApiPageContent(operation),
+      description: operation.description,
+      identifier,
+      slug,
+      sourceKey,
+      title: operation.summary ?? identifier,
+    } satisfies UtilityOpenApiPage;
+
+    pagesByIdentifier.set(identifier, page);
+    if (!pagesBySource.has(sourceKey)) {
+      pagesBySource.set(sourceKey, []);
+    }
+    pagesBySource.get(sourceKey)?.push(page);
+  }
+};
+
+const addUtilityPagesFromSourceKey = (
+  pages: Map<string, UtilityPage>,
+  pagesBySource: Map<string, UtilityOpenApiPage[]>,
+  sourceKey: string
+) => {
+  for (const page of pagesBySource.get(sourceKey) ?? []) {
+    pages.set(page.slug, page);
+  }
+};
+
+const addReferencedUtilityPages = (
+  pages: Map<string, UtilityPage>,
+  pagesByIdentifier: Map<string, UtilityOpenApiPage>,
+  pageReferences: string[] | undefined,
+  hiddenPages: Set<string>,
+  groupHidden = false
+) => {
+  for (const pageReference of pageReferences ?? []) {
+    if (groupHidden || hiddenPages.has(pageReference)) {
+      continue;
+    }
+
+    const page = pagesByIdentifier.get(pageReference);
+    if (page) {
+      pages.set(page.slug, page);
+    }
+  }
+};
+
+export const buildUtilityOpenApiPages = async (
+  config: SiteConfig,
+  collection: CollectionConfig | undefined,
+  source: ContentSource
+) => {
+  if (!collection || collection.type !== "docs") {
+    return [] satisfies UtilityPage[];
+  }
+
+  const docsNavigation = getDocsNavigation(config);
+  const hiddenPages = new Set(docsNavigation?.hidden);
+  const slugPrefix = normalizePath(collection.slugPrefix ?? "");
+  const byIdentifier = new Map<string, UtilityOpenApiPage>();
+  const bySource = new Map<string, UtilityOpenApiPage[]>();
+  const pages = new Map<string, UtilityPage>();
+  const sources = collectOpenApiSources(collection);
+
+  const resolved = await Promise.all(
+    sources.map(async (item) => {
+      const rawSpec = await source.readFile(item.source);
+      const spec = parseOpenApiSpec(rawSpec, item.source);
+      const directory = item.directory ?? "api";
+      const { operations } = extractOpenApiOperations(spec, directory);
+      return { directory, operations, source: item };
+    })
+  );
+
+  for (const { directory, operations, source: openApiSource } of resolved) {
+    collectUtilityOpenApiPages(
+      byIdentifier,
+      bySource,
+      operations,
+      directory,
+      openApiSource,
+      slugPrefix
+    );
+  }
+
+  for (const openApiSource of ensureArray(collection.openapi)) {
+    if (!openApiSource) {
+      continue;
+    }
+    addUtilityPagesFromSourceKey(
+      pages,
+      bySource,
+      getGroupedOpenApiSourceKey(openApiSource)
+    );
+  }
+
+  for (const group of docsNavigation?.groups ?? []) {
+    const groupHidden = group.hidden === true;
+    addReferencedUtilityPages(
+      pages,
+      byIdentifier,
+      group.pages,
+      hiddenPages,
+      groupHidden
+    );
+
+    if (groupHidden || !group.openapi) {
+      continue;
+    }
+    addUtilityPagesFromSourceKey(
+      pages,
+      bySource,
+      getGroupedOpenApiSourceKey(group.openapi)
+    );
+  }
+
+  addReferencedUtilityPages(
+    pages,
+    byIdentifier,
+    docsNavigation?.pages,
+    hiddenPages
+  );
+
+  return [...pages.values()];
+};