@mintlify/prebuild 1.0.1237 → 1.0.1239

package/dist/prebuild/update/docsConfig/generateSdkDivisions.js

@@ -1,6 +1,9 @@
-import { generateSdkReference } from '@mintlify/scraping';
+import { parseFrontmatter, parseSdkTargetFromMetadata, potentiallyParseSdkString, } from '@mintlify/common';
+import { SDK_FORMATS, SDK_SYMBOL_KINDS, } from '@mintlify/models';
+import { generateSdkReference, renderSdkTarget, } from '@mintlify/scraping';
 import { Unzip, UnzipInflate } from 'fflate';
 import fse from 'fs-extra';
+import yaml from 'js-yaml';
 import os from 'node:os';
 import path from 'node:path';
 import { getGeneratedRouteKey } from './generatedRouteCollisions.js';
@@ -10,9 +13,108 @@ const REMOTE_ARTIFACT_LABEL = 'SDK artifact';
 const MAX_REMOTE_SDK_ARTIFACT_BYTES = 50 * 1024 * 1024;
 const MAX_EXTRACTED_SDK_ARTIFACT_BYTES = 200 * 1024 * 1024;
 const REMOTE_SDK_ARTIFACT_TIMEOUT_MS = 30_000;
-export async function generateSdkDivisionsFromDocsConfig(docsConfig, loadReference) {
+function isSdkConfig(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    return typeof record.format === 'string' && typeof record.source === 'string';
+}
+function collectPageSlugs(value, slugs = [], atRoot = false) {
+    if (typeof value === 'string') {
+        slugs.push(value.replace(/^\//, '').replace(/\.mdx?$/, ''));
+        return slugs;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collectPageSlugs(entry, slugs);
+        return slugs;
+    }
+    if (typeof value !== 'object' || value === null)
+        return slugs;
+    const node = value;
+    // Pages under a nested sdk owner belong to that owner's skip-bulk decision.
+    if (!atRoot && 'sdk' in node && isSdkConfig(node.sdk))
+        return slugs;
+    if ('root' in node)
+        collectPageSlugs(node.root, slugs);
+    if ('pages' in node)
+        collectPageSlugs(node.pages, slugs);
+    if ('groups' in node)
+        collectPageSlugs(node.groups, slugs);
+    for (const key of ['tabs', 'anchors', 'dropdowns', 'versions', 'languages', 'products', 'menu']) {
+        if (key in node)
+            collectPageSlugs(node[key], slugs);
+    }
+    return slugs;
+}
+function hasExplicitSdkPages(node, pageMetadataBySlug, inherited) {
+    if (!pageMetadataBySlug)
+        return false;
+    return collectPageSlugs(node, [], true).some((slug) => {
+        const metadata = pageMetadataBySlug[slug] ?? pageMetadataBySlug[`/${slug}`];
+        return parseSdkTargetFromMetadata({ sdk: metadata?.sdk }, inherited) !== undefined;
+    });
+}
+export function navigationHasSdkConfig(value) {
+    if (Array.isArray(value))
+        return value.some(navigationHasSdkConfig);
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (('tab' in value || 'group' in value) &&
+        'sdk' in value &&
+        typeof value.sdk === 'object' &&
+        value.sdk !== null) {
+        return true;
+    }
+    return Object.values(value).some(navigationHasSdkConfig);
+}
+function toGeneratedPage(page, config, directory, referenceSlugs, autogeneratedBySdk) {
+    assertSafeSlug(page.slug, config);
+    const slug = path.posix.join(directory, page.slug);
+    const sdk = page.target
+        ? {
+            format: config.format,
+            source: config.source,
+            kind: page.target.kind,
+            name: page.target.name,
+            ...(page.target.parent ? { parent: page.target.parent } : {}),
+        }
+        : undefined;
+    return {
+        slug,
+        title: page.title,
+        ...(page.description ? { description: page.description } : {}),
+        ...(page.tag ? { tag: page.tag } : {}),
+        content: prefixInternalLinks(stripLeadingDescription(page.content, page.description), directory, referenceSlugs),
+        format: config.format,
+        source: config.source,
+        ...(sdk ? { sdk } : {}),
+        ...(autogeneratedBySdk ? { autogeneratedBySdk: true } : {}),
+    };
+}
+function expandSdkGroups(reference, directory) {
+    const pageBySlug = new Map(reference.pages.map((page) => [page.slug, page]));
+    const groups = reference.groups.map((group) => ({
+        group: group.group,
+        pages: group.pages.map((slug) => path.posix.join(directory, slug)),
+    }));
+    const orphanedSlugs = reference.pages
+        .filter((page) => !page.target?.parent)
+        .map((page) => page.slug)
+        .filter((slug) => !reference.groups.some((group) => group.pages.includes(slug)));
+    if (orphanedSlugs.length > 0 && pageBySlug.size > 0) {
+        groups.push({
+            group: 'Reference',
+            pages: orphanedSlugs.map((slug) => path.posix.join(directory, slug)),
+        });
+    }
+    return groups;
+}
+export async function generateSdkDivisionsFromDocsConfig(docsConfig, loadReference, options = {}) {
     const references = new Map();
     const pagesByRouteKey = new Map();
+    const inheritedSdkBySlug = {};
+    const { pageMetadataBySlug } = options;
     function load(config) {
         const key = `${config.format}:${config.source}`;
         let pending = references.get(key);
@@ -22,57 +124,104 @@ export async function generateSdkDivisionsFromDocsConfig(docsConfig, loadReferen
         }
         return pending;
     }
-    async function processNode(value) {
-        if (Array.isArray(value))
-            return Promise.all(value.map(processNode));
+    function rememberGenerated(generatedPage) {
+        const routeKey = getGeneratedRouteKey(generatedPage.slug);
+        const existingPage = pagesByRouteKey.get(routeKey);
+        if (existingPage &&
+            (existingPage.slug !== generatedPage.slug ||
+                existingPage.format !== generatedPage.format ||
+                existingPage.source !== generatedPage.source)) {
+            throw new Error(`Multiple SDK references generate colliding routes "${existingPage.slug}" and "${generatedPage.slug}"`);
+        }
+        pagesByRouteKey.set(routeKey, generatedPage);
+    }
+    async function materializeBulk(config) {
+        const directory = config.directory ?? DEFAULT_OUTPUT_DIR;
+        const reference = await load(config);
+        const topLevelPages = reference.pages.filter((page) => !page.target?.parent);
+        const referenceSlugs = new Set(topLevelPages.map((page) => page.slug));
+        for (const page of topLevelPages) {
+            rememberGenerated(toGeneratedPage(page, config, directory, referenceSlugs, true));
+        }
+        return { groups: expandSdkGroups({ ...reference, pages: topLevelPages }, directory) };
+    }
+    async function processPages(pages, inherited) {
+        if (!Array.isArray(pages))
+            return processNode(pages, inherited);
+        return Promise.all(pages.map((entry) => {
+            if (typeof entry === 'string') {
+                const slug = entry.replace(/^\//, '').replace(/\.mdx?$/, '');
+                if (inherited)
+                    inheritedSdkBySlug[slug] = inherited;
+                return entry;
+            }
+            return processNode(entry, inherited);
+        }));
+    }
+    async function processNode(value, inherited) {
+        if (Array.isArray(value)) {
+            return Promise.all(value.map((entry) => processNode(entry, inherited)));
+        }
+        if (typeof value === 'string') {
+            return value;
+        }
         if (typeof value !== 'object' || value === null)
             return value;
         const node = value;
-        if ('tab' in node && 'sdk' in node) {
-            const { sdk, ...tab } = node;
-            const config = sdk;
-            const directory = config.directory ?? DEFAULT_OUTPUT_DIR;
-            const reference = await load(config);
-            const pageBySlug = new Map(reference.pages.map((page) => [page.slug, page]));
-            const referenceSlugs = new Set(reference.pages.map((page) => page.slug));
-            const groups = reference.groups.map((group) => ({
-                group: group.group,
-                pages: group.pages.map((slug) => path.posix.join(directory, slug)),
-            }));
-            for (const page of reference.pages) {
-                assertSafeSlug(page.slug, config);
-                const slug = path.posix.join(directory, page.slug);
-                const generatedPage = {
-                    slug,
-                    title: page.title,
-                    ...(page.description ? { description: page.description } : {}),
-                    ...(page.tag ? { tag: page.tag } : {}),
-                    content: prefixInternalLinks(stripLeadingDescription(page.content, page.description), directory, referenceSlugs),
-                    format: config.format,
-                    source: config.source,
-                };
-                const routeKey = getGeneratedRouteKey(slug);
-                const existingPage = pagesByRouteKey.get(routeKey);
-                if (existingPage &&
-                    (existingPage.slug !== slug ||
-                        existingPage.format !== generatedPage.format ||
-                        existingPage.source !== generatedPage.source)) {
-                    throw new Error(`Multiple SDK references generate colliding routes "${existingPage.slug}" and "${slug}"`);
+        const ownSdk = 'sdk' in node && isSdkConfig(node.sdk) ? node.sdk : undefined;
+        const nextInherited = ownSdk ?? inherited;
+        const isTab = 'tab' in node && typeof node.tab === 'string';
+        const isGroup = 'group' in node && typeof node.group === 'string';
+        if (isGroup && typeof node.root === 'string' && nextInherited) {
+            const slug = node.root.replace(/^\//, '').replace(/\.mdx?$/, '');
+            inheritedSdkBySlug[slug] = nextInherited;
+        }
+        if (ownSdk && (isTab || isGroup)) {
+            const skipBulk = hasExplicitSdkPages(node, pageMetadataBySlug, ownSdk);
+            if (!skipBulk) {
+                const { groups } = await materializeBulk(ownSdk);
+                if (isTab) {
+                    const { sdk: _sdk, ...tab } = node;
+                    const existingGroups = Array.isArray(tab.groups)
+                        ? (await processNode(tab.groups, ownSdk))
+                        : [];
+                    const existingPages = Array.isArray(tab.pages)
+                        ? (await processPages(tab.pages, ownSdk))
+                        : [];
+                    const restEntries = await Promise.all(Object.entries(tab)
+                        .filter(([key]) => key !== 'groups' && key !== 'pages')
+                        .map(async ([key, entry]) => [key, await processNode(entry, ownSdk)]));
+                    return {
+                        ...Object.fromEntries(restEntries),
+                        groups: [
+                            ...existingGroups,
+                            ...(existingPages.length > 0 ? [{ group: 'Overview', pages: existingPages }] : []),
+                            ...groups,
+                        ],
+                    };
                 }
-                pagesByRouteKey.set(routeKey, generatedPage);
+                const { sdk: _sdk, ...group } = node;
+                const processedPages = Array.isArray(group.pages)
+                    ? (await processPages(group.pages, ownSdk))
+                    : [];
+                return {
+                    ...group,
+                    pages: [...processedPages, ...groups],
+                };
             }
-            const orphanedSlugs = reference.pages
-                .map((page) => page.slug)
-                .filter((slug) => !reference.groups.some((group) => group.pages.includes(slug)));
-            if (orphanedSlugs.length > 0 && pageBySlug.size > 0) {
-                groups.push({
-                    group: 'Reference',
-                    pages: orphanedSlugs.map((slug) => path.posix.join(directory, slug)),
-                });
+            if (isTab) {
+                const { sdk: _sdk, ...tab } = node;
+                return processNode(tab, ownSdk);
             }
-            return { ...tab, groups: [...(tab.groups ?? []), ...groups] };
+            const { sdk: _sdk, ...group } = node;
+            return processNode(group, ownSdk);
         }
-        return Object.fromEntries(await Promise.all(Object.entries(node).map(async ([key, entry]) => [key, await processNode(entry)])));
+        return Object.fromEntries(await Promise.all(Object.entries(node).map(async ([key, entry]) => [
+            key,
+            key === 'pages'
+                ? await processPages(entry, nextInherited)
+                : await processNode(entry, nextInherited),
+        ])));
     }
     const navigation = (await processNode(docsConfig.navigation));
     const generatedPages = [...pagesByRouteKey.values()].sort((left, right) => left.slug.localeCompare(right.slug));
@@ -83,6 +232,7 @@ export async function generateSdkDivisionsFromDocsConfig(docsConfig, loadReferen
             title: page.title,
             ...(page.description ? { description: page.description } : {}),
             ...(page.tag ? { tag: page.tag } : {}),
+            ...(page.sdk ? { sdk: page.sdk } : {}),
         },
     ]));
     return {
@@ -90,8 +240,121 @@ export async function generateSdkDivisionsFromDocsConfig(docsConfig, loadReferen
         pagesAcc,
         generatedPages,
         generatedRoutes: generatedPages.map(({ slug }) => slug),
+        inheritedSdkBySlug,
+    };
+}
+export async function composeSdkFrontmatterPage(args) {
+    const target = parseSdkTargetFromMetadata(args.metadata, args.inherited);
+    if (!target)
+        return undefined;
+    const reference = await args.loadReference({
+        format: target.format,
+        source: target.source,
+    });
+    let page;
+    try {
+        page = renderSdkTarget(reference, target);
+    }
+    catch (error) {
+        console.error(`unable to resolve sdk target for "${args.slug}":`, error);
+        return undefined;
+    }
+    const slug = args.slug.replace(/^\//, '').replace(/\.mdx?$/, '');
+    const slugDirectory = path.posix.dirname(slug);
+    const directory = args.inherited === undefined
+        ? slugDirectory === '.'
+            ? DEFAULT_OUTPUT_DIR
+            : slugDirectory
+        : (args.inherited.directory ?? DEFAULT_OUTPUT_DIR);
+    const referenceSlugs = new Set(reference.pages.map((entry) => entry.slug));
+    const generatedBody = prefixInternalLinks(stripLeadingDescription(page.content, page.description), directory, referenceSlugs);
+    const authorBody = stripFrontmatter(args.authorContent).trim();
+    const content = [authorBody, generatedBody].filter(Boolean).join('\n\n');
+    return {
+        slug,
+        title: typeof args.metadata.title === 'string' && args.metadata.title.length > 0
+            ? args.metadata.title
+            : page.title,
+        description: typeof args.metadata.description === 'string' && args.metadata.description.length > 0
+            ? args.metadata.description
+            : page.description,
+        tag: typeof args.metadata.tag === 'string' && args.metadata.tag.length > 0
+            ? args.metadata.tag
+            : page.tag,
+        content,
+        generatedBody,
+        format: target.format,
+        source: target.source,
+        sdk: target,
     };
 }
+function stripFrontmatter(content) {
+    if (!content.startsWith('---'))
+        return content;
+    const end = content.indexOf('\n---', 3);
+    if (end === -1)
+        return content;
+    return content.slice(end + 4).replace(/^\n+/, '');
+}
+function isSdkSymbolKind(value) {
+    for (const kind of SDK_SYMBOL_KINDS) {
+        if (kind === value)
+            return true;
+    }
+    return false;
+}
+function isSdkFormatName(value) {
+    for (const format of SDK_FORMATS) {
+        if (format === value)
+            return true;
+    }
+    return false;
+}
+export function isSdkFrontmatterValue(value) {
+    if (typeof value === 'string')
+        return potentiallyParseSdkString(value) !== undefined;
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    if (!('kind' in value) || !('name' in value))
+        return false;
+    if (typeof value.kind !== 'string' || !isSdkSymbolKind(value.kind))
+        return false;
+    if (typeof value.name !== 'string' || value.name.length === 0)
+        return false;
+    if ('format' in value &&
+        value.format !== undefined &&
+        (typeof value.format !== 'string' || !isSdkFormatName(value.format))) {
+        return false;
+    }
+    if ('source' in value &&
+        value.source !== undefined &&
+        (typeof value.source !== 'string' || value.source.length === 0)) {
+        return false;
+    }
+    return true;
+}
+export async function readContainedMarkdown(contentRoot, slug) {
+    for (const extension of ['.mdx', '.md']) {
+        const filePath = path.resolve(contentRoot, `${slug}${extension}`);
+        const relativePath = path.relative(contentRoot, filePath);
+        if (relativePath.startsWith(`..${path.sep}`) ||
+            relativePath === '..' ||
+            path.isAbsolute(relativePath)) {
+            continue;
+        }
+        if (!(await fse.pathExists(filePath)))
+            continue;
+        const realFilePath = await fse.realpath(filePath);
+        const realRelative = path.relative(contentRoot, realFilePath);
+        if (realRelative.startsWith(`..${path.sep}`) ||
+            realRelative === '..' ||
+            path.isAbsolute(realRelative)) {
+            continue;
+        }
+        return { content: await fse.readFile(realFilePath, 'utf8'), extension };
+    }
+    return undefined;
+}
 export const isRemoteSdkSource = (source) => {
     try {
         return new URL(source).protocol === 'https:';
@@ -252,12 +515,27 @@ function frontmatter(page) {
         `title: ${JSON.stringify(page.title)}`,
         ...(page.description ? [`description: ${JSON.stringify(page.description)}`] : []),
         ...(page.tag ? [`tag: ${JSON.stringify(page.tag)}`] : []),
+        ...(page.sdk ? [`sdk: ${JSON.stringify(page.sdk)}`] : []),
     ];
     return `---\n${fields.join('\n')}\n---\n\n`;
 }
-function getContainedSdkPagePath(targetDir, page) {
+/** Everything after this marker in a composed `_props` page is regenerated on each run. */
+const SDK_GENERATED_MARKER = '{/* mintlify:sdk-generated */}';
+function stripSdkGeneratedSection(body) {
+    const markerIndex = body.indexOf(SDK_GENERATED_MARKER);
+    return (markerIndex === -1 ? body : body.slice(0, markerIndex)).trim();
+}
+function stringifyMarkdownFrontmatter(attributes) {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        if (value !== undefined)
+            cleaned[key] = value;
+    }
+    return `---\n${yaml.dump(cleaned, { lineWidth: -1 }).trimEnd()}\n---\n\n`;
+}
+function getContainedSdkPagePath(targetDir, page, extension = '.mdx') {
     const propsDirectory = path.resolve(targetDir ?? '', 'src', '_props');
-    const pagePath = path.resolve(propsDirectory, `${page}.mdx`);
+    const pagePath = path.resolve(propsDirectory, `${page}${extension}`);
     const relativePath = path.relative(propsDirectory, pagePath);
     if (relativePath.startsWith(`..${path.sep}`) ||
         relativePath === '..' ||
@@ -266,6 +544,112 @@ function getContainedSdkPagePath(targetDir, page) {
     }
     return pagePath;
 }
+export async function writeSdkFrontmatterPages({ contentDirectoryPath, inheritedSdkBySlug, pageMetadataBySlug, loadReference, targetDir, }) {
+    const references = new Map();
+    const load = (config) => {
+        const key = `${config.format}:${config.source}`;
+        let pending = references.get(key);
+        if (!pending) {
+            pending = loadReference(config);
+            references.set(key, pending);
+        }
+        return pending;
+    };
+    const slugs = new Set([...Object.keys(pageMetadataBySlug), ...Object.keys(inheritedSdkBySlug)]);
+    const contentRoot = await fse.realpath(contentDirectoryPath);
+    await Promise.all([...slugs].map(async (rawSlug) => {
+        const slug = rawSlug.replace(/^\//, '').replace(/\.mdx?$/, '');
+        const metadata = pageMetadataBySlug[slug] ?? pageMetadataBySlug[`/${slug}`];
+        const inherited = inheritedSdkBySlug[slug] ?? inheritedSdkBySlug[`/${slug}`];
+        if (!metadata || parseSdkTargetFromMetadata({ sdk: metadata.sdk }, inherited) === undefined) {
+            return;
+        }
+        const authorFile = await readContainedMarkdown(contentRoot, slug);
+        if (!authorFile)
+            return;
+        const { content: authorContent, extension } = authorFile;
+        let title;
+        let description;
+        let tag;
+        try {
+            const attributes = parseFrontmatter(authorContent).attributes;
+            title = attributes.title;
+            description = attributes.description;
+            tag = attributes.tag;
+        }
+        catch {
+            // keep generated title/description/tag when author frontmatter cannot be parsed
+        }
+        const composed = await composeSdkFrontmatterPage({
+            slug,
+            authorContent,
+            metadata: {
+                sdk: metadata.sdk,
+                title,
+                description,
+                tag,
+            },
+            loadReference: load,
+            inherited,
+        });
+        if (!composed)
+            return;
+        const pagePath = getContainedSdkPagePath(targetDir, composed.slug, extension);
+        if (!pagePath)
+            return;
+        let attributes = {};
+        let processedBody = stripSdkGeneratedSection(stripFrontmatter(authorContent));
+        let usedProcessedOutput = false;
+        if (await fse.pathExists(pagePath)) {
+            try {
+                const existing = await fse.readFile(pagePath, 'utf8');
+                attributes = parseFrontmatter(existing).attributes;
+                processedBody = stripSdkGeneratedSection(stripFrontmatter(existing));
+                usedProcessedOutput = true;
+            }
+            catch {
+                try {
+                    attributes = parseFrontmatter(authorContent).attributes;
+                }
+                catch {
+                    // keep generated title/description/tag when author frontmatter cannot be parsed
+                }
+            }
+        }
+        else {
+            try {
+                attributes = parseFrontmatter(authorContent).attributes;
+            }
+            catch {
+                // keep generated title/description/tag when author frontmatter cannot be parsed
+            }
+        }
+        // Raw author content with unresolved imports must not shadow the lazy
+        // rendering path; those pages are composed once their processed output exists.
+        if (!usedProcessedOutput && /^import\s/m.test(processedBody)) {
+            return;
+        }
+        if (composed.sdk)
+            attributes.sdk = composed.sdk;
+        if (typeof attributes.title !== 'string' || attributes.title.length === 0) {
+            attributes.title = composed.title;
+        }
+        if ((typeof attributes.description !== 'string' || attributes.description.length === 0) &&
+            composed.description) {
+            attributes.description = composed.description;
+        }
+        if ((typeof attributes.tag !== 'string' || attributes.tag.length === 0) && composed.tag) {
+            attributes.tag = composed.tag;
+        }
+        const generatedBody = composed.generatedBody ?? composed.content;
+        const content = [processedBody, `${SDK_GENERATED_MARKER}\n\n${generatedBody}`]
+            .filter(Boolean)
+            .join('\n\n');
+        await fse.outputFile(pagePath, `${stringifyMarkdownFrontmatter(attributes)}${content}\n`, {
+            flag: 'w',
+        });
+    }));
+}
 export async function writeSdkArtifacts(result, targetDir) {
     const propsDirectory = path.resolve(targetDir ?? '', 'src', '_props');
     const manifestPath = path.join(propsDirectory, 'sdk-data.json');

package/dist/prebuild/update/docsConfig/index.d.ts

@@ -1,5 +1,6 @@
 import { AsyncAPIFile } from '@mintlify/common';
 import { OpenApiFile, DecoratedNavigationPage } from '@mintlify/models';
+import type { SdkFormat } from '@mintlify/scraping';
 import { DocsConfig } from '@mintlify/validation';
 import type { InvalidSpecFile } from '../../invalidSpecFiles.js';
 export declare function updateDocsConfigFile({ contentDirectoryPath, openApiFiles, asyncApiFiles, docsConfig, localSchema, disableOpenApi, strict, invalidSpecFiles, allowSourceRefs, }: {
@@ -21,11 +22,19 @@ export declare function updateDocsConfigFile({ contentDirectoryPath, openApiFile
         content: string;
         filePath: string;
     }[];
+    inheritedSdkBySlug: Record<string, {
+        format: SdkFormat;
+        source: string;
+        directory?: string;
+    }>;
+    pageMetadataBySlug: Record<string, {
+        sdk?: unknown;
+    }>;
 }>;
 export { generateOpenApiDivisions } from './generateOpenApiDivisions.js';
 export { generateOpenApiFromDocsConfig } from './generateOpenApiFromDocsConfig.js';
-export { generateSdkDivisionsFromDocsConfig, loadSdkReferenceSource, writeSdkArtifacts, } from './generateSdkDivisions.js';
-export type { GeneratedSdkPage, GenerateSdkDivisionsResult, SdkReferenceLoader, } from './generateSdkDivisions.js';
+export { generateSdkDivisionsFromDocsConfig, loadSdkReferenceSource, writeSdkArtifacts, writeSdkFrontmatterPages, composeSdkFrontmatterPage, isSdkFrontmatterValue, navigationHasSdkConfig, } from './generateSdkDivisions.js';
+export type { GeneratedSdkPage, GenerateSdkDivisionsResult, GenerateSdkDivisionsOptions, SdkReferenceLoader, } from './generateSdkDivisions.js';
 export { getOpenApiFilesFromConfig } from '../read/getOpenApiFilesFromConfig.js';
 export { generateAsyncApiDivisions } from './generateAsyncApiDivisions.js';
 export { generateAsyncApiFromDocsConfig } from './generateAsyncApiFromDocsConfig.js';

package/dist/prebuild/update/docsConfig/index.js

@@ -1,12 +1,59 @@
+import { parseFrontmatter } from '@mintlify/common';
+import fse from 'fs-extra';
 import { getConfigPath } from '../../../utils.js';
 import { DocsConfigUpdater } from '../ConfigUpdater.js';
 import { generateAsyncApiDivisions } from './generateAsyncApiDivisions.js';
 import { assertNoGeneratedRouteCollisions } from './generatedRouteCollisions.js';
 import { generateGraphqlDivisionsFromDocsConfig, loadGraphqlSdlSource, writeGraphqlArtifacts, } from './generateGraphqlDivisions.js';
 import { generateOpenApiDivisions } from './generateOpenApiDivisions.js';
-import { generateSdkDivisionsFromDocsConfig, loadSdkReferenceSource, writeSdkArtifacts, } from './generateSdkDivisions.js';
+import { generateSdkDivisionsFromDocsConfig, loadSdkReferenceSource, readContainedMarkdown, writeSdkArtifacts, } from './generateSdkDivisions.js';
 import { getCustomLanguages } from './getCustomLanguages.js';
 const NOT_CORRECT_PATH_ERROR = 'must be run in a directory where a docs.json file exists.';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function collectNavigationPageSlugs(value, slugs = new Set()) {
+    if (typeof value === 'string') {
+        slugs.add(value.replace(/^\//, '').replace(/\.mdx?$/, ''));
+        return slugs;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry) => collectNavigationPageSlugs(entry, slugs));
+        return slugs;
+    }
+    if (!isPlainObject(value))
+        return slugs;
+    if ('root' in value)
+        collectNavigationPageSlugs(value.root, slugs);
+    if ('pages' in value)
+        collectNavigationPageSlugs(value.pages, slugs);
+    if ('groups' in value)
+        collectNavigationPageSlugs(value.groups, slugs);
+    for (const key of ['tabs', 'anchors', 'dropdowns', 'versions', 'languages', 'products', 'menu']) {
+        if (key in value)
+            collectNavigationPageSlugs(value[key], slugs);
+    }
+    return slugs;
+}
+async function scanSdkFrontmatterMetadata(contentDirectoryPath, navigation) {
+    const contentRoot = await fse.realpath(contentDirectoryPath);
+    const metadataBySlug = {};
+    await Promise.all([...collectNavigationPageSlugs(navigation)].map(async (slug) => {
+        try {
+            const file = await readContainedMarkdown(contentRoot, slug);
+            if (file === undefined)
+                return;
+            const { attributes } = parseFrontmatter(file.content);
+            if (attributes.sdk !== undefined) {
+                metadataBySlug[slug] = { sdk: attributes.sdk };
+            }
+        }
+        catch {
+            // ignore unreadable/invalid frontmatter during scan
+        }
+    }));
+    return metadataBySlug;
+}
 export async function updateDocsConfigFile({ contentDirectoryPath, openApiFiles, asyncApiFiles, docsConfig, localSchema, disableOpenApi, strict, invalidSpecFiles, allowSourceRefs, }) {
     const configPath = await getConfigPath(contentDirectoryPath, 'docs');
     if (configPath == null && docsConfig == null) {
@@ -32,7 +79,8 @@ export async function updateDocsConfigFile({ contentDirectoryPath, openApiFiles,
             flushWrites: async () => { },
         };
     const { newDocsConfig: docsConfigWithAsyncApiPages, pagesAcc: pagesAccWithAsyncApiPages, asyncApiFiles: newAsyncApiFiles, flushWrites: flushAsyncApiWrites, } = await generateAsyncApiDivisions(docsConfigWithOpenApiPages, asyncApiFiles, undefined, localSchema, pagesAccWithGraphqlPages, true, true);
-    const sdkResult = await generateSdkDivisionsFromDocsConfig(docsConfigWithAsyncApiPages, (config) => loadSdkReferenceSource(config, contentDirectoryPath));
+    const pageMetadataBySlug = await scanSdkFrontmatterMetadata(contentDirectoryPath, docsConfigWithAsyncApiPages.navigation);
+    const sdkResult = await generateSdkDivisionsFromDocsConfig(docsConfigWithAsyncApiPages, (config) => loadSdkReferenceSource(config, contentDirectoryPath), { pageMetadataBySlug });
     const { newDocsConfig: docsConfigWithSdkPages, pagesAcc: pagesAccWithSdkPages } = sdkResult;
     const sdkRoutes = { label: 'SDK', pages: pagesAccWithSdkPages };
     assertNoGeneratedRouteCollisions({ label: 'GraphQL', pages: pagesAccWithGraphqlPages }, sdkRoutes);
@@ -54,11 +102,13 @@ export async function updateDocsConfigFile({ contentDirectoryPath, openApiFiles,
         newOpenApiFiles,
         newAsyncApiFiles,
         customLanguages,
+        inheritedSdkBySlug: sdkResult.inheritedSdkBySlug,
+        pageMetadataBySlug,
     };
 }
 export { generateOpenApiDivisions } from './generateOpenApiDivisions.js';
 export { generateOpenApiFromDocsConfig } from './generateOpenApiFromDocsConfig.js';
-export { generateSdkDivisionsFromDocsConfig, loadSdkReferenceSource, writeSdkArtifacts, } from './generateSdkDivisions.js';
+export { generateSdkDivisionsFromDocsConfig, loadSdkReferenceSource, writeSdkArtifacts, writeSdkFrontmatterPages, composeSdkFrontmatterPage, isSdkFrontmatterValue, navigationHasSdkConfig, } from './generateSdkDivisions.js';
 export { getOpenApiFilesFromConfig } from '../read/getOpenApiFilesFromConfig.js';
 export { generateAsyncApiDivisions } from './generateAsyncApiDivisions.js';
 export { generateAsyncApiFromDocsConfig } from './generateAsyncApiFromDocsConfig.js';