@mintlify/previewing 4.0.1227 → 4.0.1229

package/dist/__tests__/page-metadata-cache.test.js

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it } from 'vitest';
-import { clearPageMetadataCache, generateDocsNavFromPageMetadataCache, upsertPageMetadataCacheEntryForFile, } from '../local-preview/listener/page-metadata-cache.js';
+import { clearPageMetadataCache, ensurePageMetadataCacheForDocsConfig, generateDocsNavFromPageMetadataCache, hydratePageMetadataCacheFromGeneratedNav, upsertPageMetadataCacheEntryForFile, } from '../local-preview/listener/page-metadata-cache.js';
 const createDocsConfig = (pages) => ({
     $schema: 'https://mintlify.com/docs.json',
     name: 'Mintlify',
@@ -48,4 +48,51 @@ describe('pageMetadataCache', () => {
             ],
         });
     });
+    it('reuses generated metadata for API pages during navigation updates', async () => {
+        hydratePageMetadataCacheFromGeneratedNav({
+            pages: [
+                {
+                    href: '/endpoint',
+                    title: 'List pets',
+                    openapi: 'GET /pets',
+                },
+            ],
+        });
+        const docsConfig = createDocsConfig(['endpoint']);
+        expect(await ensurePageMetadataCacheForDocsConfig(docsConfig)).toBe(false);
+        expect(generateDocsNavFromPageMetadataCache(docsConfig)).toMatchObject({
+            pages: [
+                {
+                    href: '/endpoint',
+                    title: 'List pets',
+                },
+            ],
+        });
+    });
+    it('invalidates generated metadata when API frontmatter changes', async () => {
+        hydratePageMetadataCacheFromGeneratedNav({
+            pages: [
+                {
+                    href: '/endpoint',
+                    title: 'List pets',
+                    openapi: 'GET /pets',
+                },
+            ],
+        });
+        upsertPageMetadataCacheEntryForFile('endpoint.mdx', '---\nopenapi: GET /animals\n---');
+        expect(await ensurePageMetadataCacheForDocsConfig(createDocsConfig(['endpoint']))).toBe(true);
+    });
+    it('removes generated metadata missing from the latest navigation', async () => {
+        hydratePageMetadataCacheFromGeneratedNav({
+            pages: [
+                {
+                    href: '/removed',
+                    title: 'Removed title',
+                    openapi: 'GET /removed',
+                },
+            ],
+        });
+        hydratePageMetadataCacheFromGeneratedNav({ pages: [] });
+        expect(await ensurePageMetadataCacheForDocsConfig(createDocsConfig(['removed']))).toBe(false);
+    });
 });

package/dist/local-preview/listener/generate.js

@@ -4,20 +4,19 @@ import { join } from 'path';
 import { CMD_EXEC_PATH } from '../../constants.js';
 import { handleParseError } from './utils.js';
 const { readFile } = _promises;
+const PAGE_METADATA_CONCURRENCY = 8;
 const createFilenamePageMetadataMap = async ({ contentDirectoryPath, contentFilenames, openApiFiles, asyncApiFiles, pagesAcc = {}, }) => {
-    const contentPromises = [];
-    contentFilenames.forEach((filename) => {
-        contentPromises.push((async () => {
+    const filenames = contentFilenames.values();
+    const processNext = async () => {
+        for (const filename of filenames) {
             const sourcePath = join(contentDirectoryPath, filename);
             const contentStr = (await readFile(sourcePath)).toString();
             const { slug, pageMetadata } = await createPage(filename, contentStr, contentDirectoryPath, openApiFiles, asyncApiFiles, handleParseError);
-            pagesAcc = {
-                ...pagesAcc,
-                [slug]: pageMetadata,
-            };
-        })());
-    });
-    await Promise.all(contentPromises);
+            pagesAcc[slug] = pageMetadata;
+        }
+    };
+    const workerCount = Math.min(PAGE_METADATA_CONCURRENCY, contentFilenames.length);
+    await Promise.all(Array.from({ length: workerCount }, processNext));
     return pagesAcc;
 };
 export const generateNav = async (pagesAcc, docsConfig) => {

package/dist/local-preview/listener/generatePagesWithImports.js

@@ -8,6 +8,7 @@ import { getFilesImportingPathFromCache, getImportedFilesFromCache } from './imp
 import { resolvePageImports } from './resolve-page-imports.js';
 import { handleParseError } from './utils.js';
 const { readFile } = _promises;
+const PAGE_REGENERATION_CONCURRENCY = 8;
 const getAffectedPageFilenames = (updatedSnippets) => {
     const importedFiles = getImportedFilesFromCache();
     const pageFilenames = new Set();
@@ -23,25 +24,30 @@ const getAffectedPageFilenames = (updatedSnippets) => {
 };
 export const generatePagesWithImports = async (updatedSnippets) => {
     const pageFilenames = getAffectedPageFilenames(updatedSnippets);
-    await Promise.all(Array.from(pageFilenames).map(async (pageFilename) => {
-        const sourcePath = join(CMD_EXEC_PATH, pageFilename);
-        const contentStr = (await readFile(sourcePath)).toString();
-        try {
-            const tree = await preparseMdxTree(contentStr, CMD_EXEC_PATH, sourcePath, handleParseError);
-            const importsResponse = await findAndRemoveImports(tree);
-            const content = await resolvePageImports({
-                ...importsResponse,
-                filename: pageFilename,
-            });
-            const targetPath = join(NEXT_PROPS_PATH, pageFilename);
-            await outputFile(targetPath, stringifyTree(content), {
-                flag: 'w',
-            });
-        }
-        catch (err) {
-            console.log('Error generating pages with imports');
-            console.log(pageFilename);
-            console.log(err);
+    const filenames = pageFilenames.values();
+    const processNext = async () => {
+        for (const pageFilename of filenames) {
+            const sourcePath = join(CMD_EXEC_PATH, pageFilename);
+            const contentStr = (await readFile(sourcePath)).toString();
+            try {
+                const tree = await preparseMdxTree(contentStr, CMD_EXEC_PATH, sourcePath, handleParseError);
+                const importsResponse = await findAndRemoveImports(tree);
+                const content = await resolvePageImports({
+                    ...importsResponse,
+                    filename: pageFilename,
+                });
+                const targetPath = join(NEXT_PROPS_PATH, pageFilename);
+                await outputFile(targetPath, stringifyTree(content), {
+                    flag: 'w',
+                });
+            }
+            catch (err) {
+                console.log('Error generating pages with imports');
+                console.log(pageFilename);
+                console.log(err);
+            }
         }
-    }));
+    };
+    const workerCount = Math.min(PAGE_REGENERATION_CONCURRENCY, pageFilenames.size);
+    await Promise.all(Array.from({ length: workerCount }, processNext));
 };

package/dist/local-preview/listener/index.js

@@ -63,9 +63,9 @@ const getCurrentRawDocsConfig = async () => {
         return undefined;
     }
 };
-const hasDocsConfigApiRoutes = (docsConfig) => {
-    return docsConfig.api != null || hasNavigationApiReference(docsConfig.navigation);
-};
+const hasDocsConfigApiRoutes = (docsConfig) => docsConfig.api?.openapi != null ||
+    docsConfig.api?.asyncapi != null ||
+    hasNavigationApiReference(docsConfig.navigation);
 const getElapsedMs = (startTime) => {
     return Number((process.hrtime.bigint() - startTime) / 1000000n);
 };
@@ -321,6 +321,9 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
     const importedFiles = getImportedFilesFromCache();
     const potentialCategory = getFileCategory(filename, { importedFiles });
     if (hasTrackedReferencedFile(filename)) {
+        if (await fse.pathExists(pathUtil.join(CMD_EXEC_PATH, 'docs.json'))) {
+            return onUpdateEvent('docs.json', triggerRefresh, options);
+        }
         try {
             const { mintConfig, openApiFiles, docsConfig, pagesAcc } = await getDocsState(handleParseError);
             await refreshTrackedReferencedFiles();
@@ -339,12 +342,6 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
         }
         const updatedSnippets = await regenerateAllSnippets();
         await generatePagesWithImports(new Set(updatedSnippets));
-        // A tracked $ref change rebuilds config-derived artifacts; keep every docs
-        // config hash in sync with the same raw docs.json source used by save checks.
-        const rawDocsConfig = await getCurrentRawDocsConfig();
-        if (rawDocsConfig) {
-            updateDocsConfigHashCache(rawDocsConfig);
-        }
         triggerRefresh();
         return null;
     }
@@ -443,7 +440,7 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
                         // spec via frontmatter, this falls back to the full rebuild and
                         // returns the API-expanded config, which we then persist.
                         await updateCustomLanguages(docsConfig, suppressParseError);
-                        const generatedDocsConfig = await updateGeneratedNavFromPageMetadataCache(docsConfig, suppressParseError);
+                        const generatedDocsConfig = await updateGeneratedNavFromPageMetadataCache(docsConfig, suppressParseError, { reuseGeneratedMetadata: true });
                         await DocsConfigUpdater.writeConfigFile(generatedDocsConfig, CLIENT_PATH);
                     }
                     else if (shouldRegenerateGeneratedData) {

package/dist/local-preview/listener/page-metadata-cache.d.ts

@@ -1,5 +1,6 @@
 import type { DecoratedNavigationPage } from '@mintlify/models';
-import type { DecoratedNavigationConfig, DocsConfig } from '@mintlify/validation';
+import { type DecoratedNavigationConfig, type DocsConfig } from '@mintlify/validation';
+export declare const hydratePageMetadataCacheFromGeneratedNav: (generatedDocsNav: DecoratedNavigationConfig) => void;
 export declare const clearPageMetadataCache: () => void;
 export declare const upsertPageMetadataCacheEntry: (slug: string, pageMetadata: DecoratedNavigationPage) => void;
 export declare const removePageMetadataCacheEntry: (slug: string) => void;

package/dist/local-preview/listener/page-metadata-cache.js

@@ -1,9 +1,47 @@
-import { getAllPathsInDocsNav, getDecoratedNavPageAndSlug } from '@mintlify/common';
+import { getAllPathsInDocsNav, getDecoratedNavPageAndSlug, optionallyRemoveLeadingSlash, optionallyRemoveTrailingSlash, } from '@mintlify/common';
 import { generateDecoratedDocsNavigationFromPages } from '@mintlify/prebuild';
+import { divisions } from '@mintlify/validation';
 import fse from 'fs-extra';
 import pathUtil from 'path';
 import { CMD_EXEC_PATH } from '../../constants.js';
 const pageMetadataBySlug = {};
+const generatedPageMetadataSlugs = new Set();
+const navigationChildKeys = new Set(['root', 'pages', 'groups', ...divisions]);
+const isDecoratedNavigationPage = (value) => {
+    return (value != null &&
+        typeof value === 'object' &&
+        'href' in value &&
+        typeof value.href === 'string' &&
+        'title' in value &&
+        typeof value.title === 'string');
+};
+export const hydratePageMetadataCacheFromGeneratedNav = (generatedDocsNav) => {
+    for (const slug of generatedPageMetadataSlugs) {
+        delete pageMetadataBySlug[slug];
+    }
+    generatedPageMetadataSlugs.clear();
+    const hydrate = (value) => {
+        if (Array.isArray(value)) {
+            value.forEach(hydrate);
+            return;
+        }
+        if (value == null || typeof value !== 'object') {
+            return;
+        }
+        if (isDecoratedNavigationPage(value)) {
+            const slug = optionallyRemoveTrailingSlash(optionallyRemoveLeadingSlash(value.href));
+            pageMetadataBySlug[slug] = value;
+            generatedPageMetadataSlugs.add(slug);
+            return;
+        }
+        for (const [key, child] of Object.entries(value)) {
+            if (navigationChildKeys.has(key)) {
+                hydrate(child);
+            }
+        }
+    };
+    hydrate(generatedDocsNav);
+};
 const getPossiblePageFilenames = (pagePath) => {
     const normalizedPath = pagePath.startsWith('/') ? pagePath.slice(1) : pagePath;
     if (normalizedPath.endsWith('.mdx') || normalizedPath.endsWith('.md')) {
@@ -15,12 +53,15 @@ export const clearPageMetadataCache = () => {
     for (const slug of Object.keys(pageMetadataBySlug)) {
         delete pageMetadataBySlug[slug];
     }
+    generatedPageMetadataSlugs.clear();
 };
 export const upsertPageMetadataCacheEntry = (slug, pageMetadata) => {
     pageMetadataBySlug[slug] = pageMetadata;
+    generatedPageMetadataSlugs.delete(slug);
 };
 export const removePageMetadataCacheEntry = (slug) => {
     delete pageMetadataBySlug[slug];
+    generatedPageMetadataSlugs.delete(slug);
 };
 export const removePageMetadataCacheEntryForFile = (filename) => {
     removePageMetadataCacheEntry(filename.replace(/\.mdx?$/, ''));
@@ -37,18 +78,31 @@ export const upsertPageMetadataCacheEntryForFile = (filename, contentStr) => {
 // spec via frontmatter.
 export const ensurePageMetadataCacheForDocsConfig = async (docsConfig) => {
     const navPaths = getAllPathsInDocsNav(docsConfig.navigation);
-    const results = await Promise.all(navPaths.map(async (navPath) => {
+    for (const navPath of navPaths) {
+        const normalizedPath = optionallyRemoveTrailingSlash(optionallyRemoveLeadingSlash(navPath));
+        if (generatedPageMetadataSlugs.has(normalizedPath)) {
+            continue;
+        }
+        const cachedPageMetadata = pageMetadataBySlug[normalizedPath];
+        if (cachedPageMetadata) {
+            if (cachedPageMetadata.openapi != null || cachedPageMetadata.asyncapi != null) {
+                return true;
+            }
+            continue;
+        }
         for (const filename of getPossiblePageFilenames(navPath)) {
             const filePath = pathUtil.join(CMD_EXEC_PATH, filename);
             if (!(await fse.pathExists(filePath))) {
                 continue;
             }
             const contentStr = (await fse.readFile(filePath)).toString();
-            return upsertPageMetadataCacheEntryForFile(filename, contentStr);
+            if (upsertPageMetadataCacheEntryForFile(filename, contentStr)) {
+                return true;
+            }
+            break;
         }
-        return false;
-    }));
-    return results.some((hasApiSpecPage) => hasApiSpecPage);
+    }
+    return false;
 };
 export const generateDocsNavFromPageMetadataCache = (docsConfig) => {
     return generateDecoratedDocsNavigationFromPages(pageMetadataBySlug, docsConfig.navigation);

package/dist/local-preview/listener/update.d.ts

@@ -1,11 +1,13 @@
 import { OpenApiFile } from '@mintlify/models';
 import type { DecoratedNavigationPage } from '@mintlify/models';
-import { DocsConfig } from '@mintlify/validation';
+import type { DocsConfig } from '@mintlify/validation';
 export declare const updateGeneratedNav: (onError?: (message: string) => void, providedState?: {
     pagesAcc: Record<string, DecoratedNavigationPage>;
     docsConfig: DocsConfig;
 }) => Promise<DocsConfig>;
-export declare const updateGeneratedNavFromPageMetadataCache: (docsConfig: DocsConfig, onError?: (message: string) => void) => Promise<DocsConfig>;
+export declare const updateGeneratedNavFromPageMetadataCache: (docsConfig: DocsConfig, onError?: (message: string) => void, options?: {
+    reuseGeneratedMetadata?: boolean;
+}) => Promise<DocsConfig>;
 export declare const updateOpenApiFiles: (providedOpenApiFiles?: OpenApiFile[], onError?: (message: string) => void) => Promise<void>;
 export declare const upsertOpenApiFile: (openApiFile: OpenApiFile) => Promise<void>;
 export declare const updateCustomLanguages: (docsConfig?: DocsConfig, onError?: (message: string) => void) => Promise<void>;

package/dist/local-preview/listener/update.js

@@ -4,7 +4,7 @@ import { join } from 'path';
 import { CMD_EXEC_PATH, NEXT_PROPS_PATH } from '../../constants.js';
 import { generateNav } from './generate.js';
 import { getDocsState } from './getDocsState.js';
-import { ensurePageMetadataCacheForDocsConfig, generateDocsNavFromPageMetadataCache, } from './page-metadata-cache.js';
+import { ensurePageMetadataCacheForDocsConfig, generateDocsNavFromPageMetadataCache, hydratePageMetadataCacheFromGeneratedNav, } from './page-metadata-cache.js';
 import { readJsonFile } from './utils.js';
 const writeGeneratedDocsNav = async (generatedDocsNav) => {
     const targetDocsPath = join(NEXT_PROPS_PATH, 'generatedDocsNav.json');
@@ -18,7 +18,19 @@ export const updateGeneratedNav = async (onError, providedState) => {
     await writeGeneratedDocsNav(generatedDocsNav);
     return docsConfig;
 };
-export const updateGeneratedNavFromPageMetadataCache = async (docsConfig, onError) => {
+export const updateGeneratedNavFromPageMetadataCache = async (docsConfig, onError, options = {}) => {
+    if (options.reuseGeneratedMetadata) {
+        try {
+            const existingGeneratedDocsNav = await readJsonFile(join(NEXT_PROPS_PATH, 'generatedDocsNav.json'));
+            hydratePageMetadataCacheFromGeneratedNav(existingGeneratedDocsNav);
+        }
+        catch (error) {
+            const isMissingFile = error instanceof Error && 'code' in error && error.code === 'ENOENT';
+            if (!isMissingFile) {
+                console.warn(`Failed to reuse generated navigation metadata: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
     const hasApiSpecPage = await ensurePageMetadataCacheForDocsConfig(docsConfig);
     if (hasApiSpecPage) {
         // A navigation page references an OpenAPI/AsyncAPI spec via frontmatter, so