radiant-docs 0.1.59 → 0.1.61

package/template/src/lib/ai-artifacts.ts

@@ -0,0 +1,792 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getCollection } from "astro:content";
+import { prependBasePath } from "./base-path";
+import {
+  getAllRoutes,
+  resolveMdxPageTitle,
+  type Route,
+  type MdxRoute,
+  type OpenApiRoute,
+} from "./routes";
+import {
+  getOpenApiOperationDoc,
+  OPENAPI_REQUEST_SECTION_LABELS,
+  type OpenApiField,
+  type OpenApiOperationDoc,
+  type OpenApiRequestSectionKey,
+  type OpenApiRequestSectionVariantData,
+} from "./openapi/operation-doc";
+import { resolvePageDescription } from "./page-description";
+import { getConfig } from "./validation";
+
+const DOCS_ROOT = path.join(process.cwd(), "src/content/docs");
+const MAX_DESCRIPTION_LENGTH = 300;
+
+const OPENAPI_SPEC_EXTENSIONS = new Set([".json", ".yaml", ".yml"]);
+
+export const MARKDOWN_CONTENT_TYPE = "text/markdown; charset=utf-8";
+export const PLAIN_TEXT_CONTENT_TYPE = "text/plain; charset=utf-8";
+
+export type AiMarkdownPage = {
+  filePath: string;
+  routeSlug?: string;
+  title: string;
+  description?: string;
+  markdownPath: string;
+  canonicalPath: string;
+  markdownUrl: string;
+  canonicalUrl: string;
+  sourcePath?: string;
+  source: string;
+};
+
+export type OpenApiSpecArtifact = {
+  source: string;
+  label: string;
+  url: string;
+  extension: string;
+  isRemote: boolean;
+  routeParam?: string;
+  sourcePath?: string;
+  contentType?: string;
+};
+
+function normalizeDocsRootRelativePath(value: string): string {
+  return value.replace(/\\/g, "/").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+function isRemoteUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function toPublicPath(pathname: string): string {
+  const normalized = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  return prependBasePath(normalized);
+}
+
+function getConfiguredSiteOrigin(): string | undefined {
+  const rawSiteUrl = process.env.DOCS_SITE_URL?.trim();
+  if (!rawSiteUrl) return undefined;
+
+  try {
+    return new URL(rawSiteUrl).origin;
+  } catch {
+    return undefined;
+  }
+}
+
+function buildPublicUrl(pathname: string): string {
+  const publicPath = toPublicPath(pathname);
+  const siteOrigin = getConfiguredSiteOrigin();
+
+  if (!siteOrigin) return publicPath;
+
+  return new URL(publicPath, siteOrigin).toString();
+}
+
+function getMarkdownPathForSlug(routeSlug: string): string {
+  const normalizedSlug = routeSlug.replace(/^\/+/, "").replace(/\/+$/, "");
+  return normalizedSlug ? `/${normalizedSlug}.md` : "/index.md";
+}
+
+function getCanonicalPathForSlug(routeSlug: string): string {
+  const normalizedSlug = routeSlug.replace(/^\/+/, "").replace(/\/+$/, "");
+  return normalizedSlug ? `/${normalizedSlug}` : "/";
+}
+
+function getEntryFilePath(entry: { id: string }): string {
+  return entry.id.replace(/\.(md|mdx)$/i, "");
+}
+
+async function findExistingMdxSourcePath(filePath: string): Promise<string> {
+  const normalizedFilePath = normalizeDocsRootRelativePath(filePath);
+  const candidates = [
+    path.join(DOCS_ROOT, `${normalizedFilePath}.mdx`),
+    path.join(DOCS_ROOT, `${normalizedFilePath}.md`),
+  ];
+
+  for (const candidate of candidates) {
+    try {
+      const stat = await fs.stat(candidate);
+      if (stat.isFile()) return candidate;
+    } catch {
+      // Try the next source extension.
+    }
+  }
+
+  throw new Error(`Could not find MDX source for docs page "${filePath}".`);
+}
+
+async function readMdxSource(filePath: string): Promise<{
+  sourcePath: string;
+  source: string;
+}> {
+  const sourcePath = await findExistingMdxSourcePath(filePath);
+  const source = await fs.readFile(sourcePath, "utf8");
+  return { sourcePath, source };
+}
+
+async function getMdxEntryByFilePath(filePath: string) {
+  const docs = await getCollection("docs");
+  const normalizedFilePath = normalizeDocsRootRelativePath(filePath);
+
+  return docs.find((entry) => getEntryFilePath(entry) === normalizedFilePath);
+}
+
+async function createMarkdownPage(args: {
+  filePath: string;
+  routeSlug?: string;
+  title?: string;
+  markdownPath?: string;
+  canonicalPath?: string;
+}): Promise<AiMarkdownPage> {
+  const entry = await getMdxEntryByFilePath(args.filePath);
+  if (!entry) {
+    throw new Error(`Could not find content collection entry for "${args.filePath}".`);
+  }
+
+  const { sourcePath, source } = await readMdxSource(args.filePath);
+  const routeSlug = args.routeSlug ?? "";
+  const markdownPath = args.markdownPath ?? getMarkdownPathForSlug(routeSlug);
+  const canonicalPath = args.canonicalPath ?? getCanonicalPathForSlug(routeSlug);
+  const title =
+    args.title ??
+    resolveMdxPageTitle({
+      entry,
+      filePath: args.filePath,
+    });
+  const config = await getConfig();
+
+  return {
+    filePath: normalizeDocsRootRelativePath(args.filePath),
+    routeSlug,
+    title,
+    description: resolvePageDescription({
+      pageTitle: title,
+      pageDescription: entry.data?.description,
+      docsTitle: config.title,
+    }),
+    markdownPath,
+    canonicalPath,
+    markdownUrl: buildPublicUrl(markdownPath),
+    canonicalUrl: buildPublicUrl(canonicalPath),
+    sourcePath,
+    source,
+  };
+}
+
+export async function getMarkdownRoutePages(): Promise<AiMarkdownPage[]> {
+  const routes = await getAllRoutes();
+
+  return Promise.all(routes.map((route) => createRouteMarkdownPage(route)));
+}
+
+export async function getLlmsListedMarkdownPages(): Promise<AiMarkdownPage[]> {
+  const config = await getConfig();
+  const routes = await getAllRoutes();
+  const visibleRoutes = routes.filter((route) => !route.hidden);
+  const homeRoute = config.home
+    ? routes.find(
+        (route): route is MdxRoute =>
+          route.type === "mdx" && route.filePath === config.home,
+      )
+    : visibleRoutes[0];
+  const skipRouteIdentity = homeRoute?.routeIdentity;
+  const pages: AiMarkdownPage[] = [];
+
+  if (config.home) {
+    pages.push(
+      await createMarkdownPage({
+        filePath: config.home,
+        routeSlug: "",
+        title: homeRoute?.title,
+        markdownPath: "/index.md",
+        canonicalPath: "/",
+      }),
+    );
+  } else if (homeRoute) {
+    pages.push(
+      await createRouteMarkdownPage(homeRoute, {
+        markdownPath: "/index.md",
+        canonicalPath: "/",
+      }),
+    );
+  }
+
+  for (const route of routes) {
+    if (route.routeIdentity === skipRouteIdentity) continue;
+    pages.push(await createRouteMarkdownPage(route));
+  }
+
+  return pages;
+}
+
+export async function getHomeMarkdownPage(): Promise<AiMarkdownPage | null> {
+  const config = await getConfig();
+  const routes = await getAllRoutes();
+  const visibleRoutes = routes.filter((route) => !route.hidden);
+
+  if (!config.home) {
+    const fallbackRoute = visibleRoutes[0] ?? routes[0];
+
+    if (!fallbackRoute) return null;
+
+    return createRouteMarkdownPage(fallbackRoute, {
+      markdownPath: "/index.md",
+      canonicalPath: "/",
+    });
+  }
+
+  const homeRoute = routes.find(
+    (route): route is MdxRoute =>
+      route.type === "mdx" && route.filePath === config.home,
+  );
+
+  return createMarkdownPage({
+    filePath: config.home,
+    routeSlug: "",
+    title: homeRoute?.title,
+    markdownPath: "/index.md",
+    canonicalPath: "/",
+  });
+}
+
+function truncateDescription(description: string): string {
+  const firstLine = description
+    .replace(/\r\n/g, "\n")
+    .split("\n")[0]
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (firstLine.length <= MAX_DESCRIPTION_LENGTH) return firstLine;
+
+  return `${firstLine.slice(0, MAX_DESCRIPTION_LENGTH - 3).trimEnd()}...`;
+}
+
+function formatDocsListItem(page: AiMarkdownPage): string {
+  const description = page.description
+    ? `: ${truncateDescription(page.description)}`
+    : "";
+
+  return `- [${page.title}](${page.markdownUrl})${description}`;
+}
+
+function normalizeLocalOpenApiSource(source: string): string {
+  return normalizeDocsRootRelativePath(source);
+}
+
+function getOpenApiSpecContentType(extension: string): string {
+  switch (extension) {
+    case ".json":
+      return "application/json; charset=utf-8";
+    case ".yaml":
+    case ".yml":
+      return "application/yaml; charset=utf-8";
+    default:
+      return "application/octet-stream";
+  }
+}
+
+function getOpenApiSpecLabel(source: string): string {
+  if (isRemoteUrl(source)) {
+    try {
+      const url = new URL(source);
+      return path.posix.basename(url.pathname).replace(/\.[^.]+$/, "") || source;
+    } catch {
+      return source;
+    }
+  }
+
+  const normalized = normalizeLocalOpenApiSource(source);
+  return normalized.replace(/\.[^.]+$/, "") || normalized;
+}
+
+function createOpenApiSpecArtifact(source: string): OpenApiSpecArtifact | null {
+  if (isRemoteUrl(source)) {
+    let extension = "";
+    try {
+      extension = path.posix.extname(new URL(source).pathname).toLowerCase();
+    } catch {
+      extension = "";
+    }
+
+    return {
+      source,
+      label: getOpenApiSpecLabel(source),
+      url: source,
+      extension,
+      isRemote: true,
+    };
+  }
+
+  const normalizedSource = normalizeLocalOpenApiSource(source);
+  const extension = path.posix.extname(normalizedSource).toLowerCase();
+  if (!OPENAPI_SPEC_EXTENSIONS.has(extension)) return null;
+
+  const sourcePath = path.join(DOCS_ROOT, normalizedSource);
+  const routeParam = normalizedSource.slice(0, -extension.length);
+
+  return {
+    source: normalizedSource,
+    label: getOpenApiSpecLabel(normalizedSource),
+    url: buildPublicUrl(`/${normalizedSource}`),
+    extension,
+    isRemote: false,
+    routeParam,
+    sourcePath,
+    contentType: getOpenApiSpecContentType(extension),
+  };
+}
+
+export async function getOpenApiSpecArtifacts(): Promise<OpenApiSpecArtifact[]> {
+  const routes = await getAllRoutes();
+  const sources = new Set(
+    routes
+      .filter((route): route is OpenApiRoute => route.type === "openapi")
+      .map((route) => route.filePath),
+  );
+  const artifacts: OpenApiSpecArtifact[] = [];
+
+  for (const source of sources) {
+    const artifact = createOpenApiSpecArtifact(source);
+    if (artifact) artifacts.push(artifact);
+  }
+
+  return artifacts.sort((a, b) => a.source.localeCompare(b.source));
+}
+
+export async function getOpenApiSpecArtifactsByExtension(
+  extension: string,
+): Promise<OpenApiSpecArtifact[]> {
+  const normalizedExtension = extension.toLowerCase();
+  const artifacts = await getOpenApiSpecArtifacts();
+  return artifacts.filter(
+    (artifact) =>
+      !artifact.isRemote && artifact.extension === normalizedExtension,
+  );
+}
+
+export async function readOpenApiSpecArtifact(
+  artifact: OpenApiSpecArtifact,
+): Promise<string> {
+  if (!artifact.sourcePath) {
+    throw new Error(`OpenAPI spec "${artifact.source}" is not a local file.`);
+  }
+
+  return fs.readFile(artifact.sourcePath, "utf8");
+}
+
+function escapeMarkdownTableCell(value: unknown): string {
+  return String(value ?? "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/\n/g, "<br>")
+    .replace(/\|/g, "\\|")
+    .trim();
+}
+
+function formatInlineCode(value: unknown): string {
+  return `\`${String(value ?? "").replace(/`/g, "\\`")}\``;
+}
+
+function formatFieldValue(value: unknown): string {
+  if (value === undefined) return "";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value);
+}
+
+function formatFieldDescription(field: OpenApiField): string {
+  const details: string[] = [];
+
+  if (field.description.trim()) details.push(field.description.trim());
+  if (field.enum && field.enum.length > 0) {
+    details.push(
+      `Allowed values: ${field.enum.map(formatFieldValue).join(", ")}`,
+    );
+  }
+  if (field.hasDefault) {
+    details.push(`Default: ${formatFieldValue(field.defaultValue)}`);
+  }
+  if (field.minLength !== undefined) {
+    details.push(`Min length: ${field.minLength}`);
+  }
+  if (field.maxLength !== undefined) {
+    details.push(`Max length: ${field.maxLength}`);
+  }
+  if (field.minimum !== undefined) {
+    details.push(`Minimum: ${field.minimum}`);
+  }
+  if (field.maximum !== undefined) {
+    details.push(`Maximum: ${field.maximum}`);
+  }
+  if (field.exclusiveMinimum !== undefined) {
+    details.push(`Exclusive minimum: ${field.exclusiveMinimum}`);
+  }
+  if (field.exclusiveMaximum !== undefined) {
+    details.push(`Exclusive maximum: ${field.exclusiveMaximum}`);
+  }
+  if (field.style) details.push(`Style: ${field.style}`);
+  if (field.explode !== undefined) details.push(`Explode: ${field.explode}`);
+
+  return details.join(" ");
+}
+
+function getNestedFieldName(parentName: string, childName: string): string {
+  if (!parentName) return childName;
+  if (childName.startsWith("[")) return `${parentName}${childName}`;
+  return `${parentName}.${childName}`;
+}
+
+function flattenFields(
+  fields: OpenApiField[],
+  parentName = "",
+): Array<{ name: string; field: OpenApiField }> {
+  const rows: Array<{ name: string; field: OpenApiField }> = [];
+
+  fields.forEach((field) => {
+    const name = getNestedFieldName(parentName, field.name);
+    rows.push({ name, field });
+
+    if (field.nested && field.nested.length > 0) {
+      rows.push(...flattenFields(field.nested, name));
+    }
+  });
+
+  return rows;
+}
+
+function appendFieldTable(lines: string[], fields: OpenApiField[]) {
+  const rows = flattenFields(fields);
+  if (rows.length === 0) return;
+
+  lines.push(
+    "",
+    "| Name | Required | Type | Description |",
+    "| --- | --- | --- | --- |",
+    ...rows.map(({ name, field }) => {
+      const cells = [
+        escapeMarkdownTableCell(formatInlineCode(name)),
+        field.required ? "Yes" : "No",
+        escapeMarkdownTableCell(formatInlineCode(field.type)),
+        escapeMarkdownTableCell(formatFieldDescription(field)),
+      ];
+
+      return `| ${cells.join(" | ")} |`;
+    }),
+  );
+}
+
+function appendVariantFieldTables(args: {
+  lines: string[];
+  variants?: OpenApiRequestSectionVariantData;
+}) {
+  const { variants } = args;
+  if (!variants || variants.variants.length === 0) return;
+
+  args.lines.push(
+    "",
+    variants.variantType === "anyOf"
+      ? "One or more variants may apply."
+      : "One of these variants applies.",
+  );
+
+  variants.variants.forEach((variant) => {
+    args.lines.push("", `### ${variant.label}`);
+    appendFieldTable(args.lines, variant.fields);
+  });
+}
+
+function appendRequestSection(args: {
+  lines: string[];
+  title: string;
+  fields: OpenApiField[];
+  variants?: OpenApiRequestSectionVariantData;
+}) {
+  const hasFields = args.fields.length > 0;
+  const hasVariants = Boolean(args.variants?.variants.length);
+
+  if (!hasFields && !hasVariants) return;
+
+  args.lines.push("", `## ${args.title}`);
+  appendFieldTable(args.lines, args.fields);
+  appendVariantFieldTables({
+    lines: args.lines,
+    variants: args.variants,
+  });
+}
+
+function appendOpenApiRequestMarkdown(
+  lines: string[],
+  operationDoc: OpenApiOperationDoc,
+) {
+  const parameterSections: Array<{
+    key: Exclude<OpenApiRequestSectionKey, "body">;
+    title: string;
+  }> = [
+    { key: "path", title: OPENAPI_REQUEST_SECTION_LABELS.path },
+    { key: "query", title: OPENAPI_REQUEST_SECTION_LABELS.query },
+    { key: "header", title: OPENAPI_REQUEST_SECTION_LABELS.header },
+    { key: "cookie", title: OPENAPI_REQUEST_SECTION_LABELS.cookie },
+  ];
+
+  parameterSections.forEach((section) => {
+    appendRequestSection({
+      lines,
+      title: section.title,
+      fields: operationDoc.requestFields[section.key],
+      variants: operationDoc.requestSectionVariants[section.key],
+    });
+  });
+
+  if (
+    operationDoc.bodyDescription ||
+    operationDoc.requestFields.body.length > 0 ||
+    operationDoc.requestSectionVariants.body?.variants.length
+  ) {
+    lines.push("", "## Request body");
+    if (operationDoc.bodyDescription) {
+      lines.push("", operationDoc.bodyDescription.trim());
+    }
+    appendFieldTable(lines, operationDoc.requestFields.body);
+    appendVariantFieldTables({
+      lines,
+      variants: operationDoc.requestSectionVariants.body,
+    });
+  }
+}
+
+function getResponseContentTypes(response: any): string[] {
+  const content = response?.content;
+  if (!content || typeof content !== "object") return [];
+  return Object.keys(content);
+}
+
+function appendOpenApiResponsesMarkdown(
+  lines: string[],
+  responses: unknown,
+) {
+  if (!responses || typeof responses !== "object") return;
+
+  const responseEntries = Object.entries(responses).filter(
+    ([status]) => !status.startsWith("x-"),
+  );
+  if (responseEntries.length === 0) return;
+
+  lines.push("", "## Responses");
+
+  responseEntries.forEach(([status, response]) => {
+    lines.push("", `### ${status}`);
+
+    if (
+      response &&
+      typeof response === "object" &&
+      typeof (response as any).description === "string" &&
+      (response as any).description.trim()
+    ) {
+      lines.push("", (response as any).description.trim());
+    }
+
+    const contentTypes = getResponseContentTypes(response);
+    if (contentTypes.length > 0) {
+      lines.push(
+        "",
+        `Content types: ${contentTypes.map(formatInlineCode).join(", ")}`,
+      );
+    }
+  });
+}
+
+function buildOpenApiMarkdown(args: {
+  route: OpenApiRoute;
+  operationDoc: OpenApiOperationDoc;
+  specUrl: string;
+}): string {
+  const summary = args.operationDoc.description?.trim();
+  const lines = [
+    "---",
+    `title: ${JSON.stringify(args.route.title)}`,
+    `openapi: ${JSON.stringify(args.route.filePath)}`,
+    `method: ${JSON.stringify(args.route.openApiMethod.toUpperCase())}`,
+    `path: ${JSON.stringify(args.route.openApiPath)}`,
+    "---",
+    "",
+    `# ${args.route.title}`,
+    "",
+    `${args.route.openApiMethod.toUpperCase()} \`${args.route.openApiPath}\``,
+  ];
+
+  if (summary) {
+    lines.push("", summary);
+  }
+
+  if (args.specUrl) {
+    lines.push("", `OpenAPI spec: ${args.specUrl}`);
+  }
+
+  appendOpenApiRequestMarkdown(lines, args.operationDoc);
+  appendOpenApiResponsesMarkdown(lines, args.operationDoc.responses);
+
+  lines.push(
+    "",
+    "## OpenAPI operation",
+    "",
+    "```json",
+    JSON.stringify(args.operationDoc.operationSpecSlice, null, 2),
+    "```",
+  );
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+async function createOpenApiMarkdownPage(args: {
+  route: OpenApiRoute;
+  markdownPath?: string;
+  canonicalPath?: string;
+}): Promise<AiMarkdownPage> {
+  const artifact = createOpenApiSpecArtifact(args.route.filePath);
+  const operationDoc = await getOpenApiOperationDoc(args.route);
+  const config = await getConfig();
+  const description = resolvePageDescription({
+    pageTitle: args.route.title,
+    pageDescription: operationDoc.description,
+    docsTitle: config.title,
+  });
+  const routeSlug = args.route.slug;
+  const markdownPath = args.markdownPath ?? getMarkdownPathForSlug(routeSlug);
+  const canonicalPath =
+    args.canonicalPath ?? getCanonicalPathForSlug(routeSlug);
+
+  return {
+    filePath: normalizeDocsRootRelativePath(args.route.filePath),
+    routeSlug,
+    title: args.route.title,
+    description,
+    markdownPath,
+    canonicalPath,
+    markdownUrl: buildPublicUrl(markdownPath),
+    canonicalUrl: buildPublicUrl(canonicalPath),
+    sourcePath: artifact?.sourcePath,
+    source: buildOpenApiMarkdown({
+      route: args.route,
+      operationDoc,
+      specUrl: artifact?.url ?? "",
+    }),
+  };
+}
+
+async function createRouteMarkdownPage(
+  route: Route,
+  overrides: {
+    markdownPath?: string;
+    canonicalPath?: string;
+  } = {},
+): Promise<AiMarkdownPage> {
+  if (route.type === "mdx") {
+    return createMarkdownPage({
+      filePath: route.filePath,
+      routeSlug: route.slug,
+      title: route.title,
+      ...overrides,
+    });
+  }
+
+  return createOpenApiMarkdownPage({
+    route,
+    ...overrides,
+  });
+}
+
+function formatOpenApiSpecsSection(specs: OpenApiSpecArtifact[]): string[] {
+  if (specs.length === 0) return [];
+
+  return [
+    "## OpenAPI Specs",
+    "",
+    ...specs.map((spec) => `- [${spec.label}](${spec.url})`),
+  ];
+}
+
+async function readCustomArtifact(filename: string): Promise<string | null> {
+  const artifactPath = path.join(DOCS_ROOT, filename);
+
+  try {
+    const stat = await fs.stat(artifactPath);
+    if (!stat.isFile()) return null;
+    return fs.readFile(artifactPath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export async function getLlmsTxt(): Promise<string> {
+  const custom = await readCustomArtifact("llms.txt");
+  if (custom !== null) return custom;
+
+  const config = await getConfig();
+  const pages = await getLlmsListedMarkdownPages();
+  const specs = await getOpenApiSpecArtifacts();
+  const lines = [`# ${config.title}`, "", "## Docs", ""];
+
+  lines.push(...pages.map(formatDocsListItem));
+
+  const specsSection = formatOpenApiSpecsSection(specs);
+  if (specsSection.length > 0) {
+    lines.push("", ...specsSection);
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}
+
+function formatLlmsFullPage(page: AiMarkdownPage): string {
+  return [
+    `# ${page.title}`,
+    "",
+    `Source: ${page.markdownUrl}`,
+    `Canonical: ${page.canonicalUrl}`,
+    "",
+    page.source.trimEnd(),
+  ].join("\n");
+}
+
+function formatLlmsFullSpec(spec: OpenApiSpecArtifact, source: string): string {
+  const fenceLanguage = spec.extension === ".json" ? "json" : "yaml";
+  return [
+    `# ${spec.label}`,
+    "",
+    `Source: ${spec.url}`,
+    "",
+    `\`\`\`${fenceLanguage}`,
+    source.trimEnd(),
+    "```",
+  ].join("\n");
+}
+
+export async function getLlmsFullTxt(): Promise<string> {
+  const custom = await readCustomArtifact("llms-full.txt");
+  if (custom !== null) return custom;
+
+  const config = await getConfig();
+  const pages = await getLlmsListedMarkdownPages();
+  const specs = await getOpenApiSpecArtifacts();
+  const sections = [`# ${config.title}`];
+
+  for (const page of pages) {
+    sections.push(formatLlmsFullPage(page));
+  }
+
+  for (const spec of specs) {
+    if (spec.isRemote) {
+      sections.push([`# ${spec.label}`, "", `Source: ${spec.url}`].join("\n"));
+      continue;
+    }
+
+    sections.push(formatLlmsFullSpec(spec, await readOpenApiSpecArtifact(spec)));
+  }
+
+  return `${sections.join("\n\n---\n\n").trimEnd()}\n`;
+}