@mintlify/previewing 4.0.1159 → 4.0.1161

package/dist/__tests__/docs-config-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/docs-config-cache.test.js

@@ -0,0 +1,83 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { clearDocsConfigCaches, getDocsConfigApiHash, getDocsConfigNavigationHash, getVariablesHash, hasDocsConfigApiChanged, hasDocsConfigNavigationChanged, hasNavigationApiReference, hasDocsConfigVariablesChanged, updateDocsConfigHashCache, } from '../local-preview/listener/docs-config-cache.js';
+const createDocsConfig = (page) => ({
+    $schema: 'https://mintlify.com/docs.json',
+    name: 'Mintlify',
+    theme: 'mint',
+    colors: {
+        primary: '#16A34A',
+    },
+    navigation: {
+        pages: [page],
+    },
+});
+describe('docsConfigCache', () => {
+    beforeEach(() => {
+        clearDocsConfigCaches();
+    });
+    it('tracks api, navigation, and variables hash changes independently', () => {
+        const docsConfig = {
+            ...createDocsConfig('raw-page'),
+            api: {
+                openapi: 'openapi.json',
+            },
+            variables: {
+                product: 'Mintlify',
+            },
+        };
+        updateDocsConfigHashCache(docsConfig);
+        expect(hasDocsConfigApiChanged(getDocsConfigApiHash(docsConfig))).toBe(false);
+        expect(hasDocsConfigNavigationChanged(getDocsConfigNavigationHash(docsConfig))).toBe(false);
+        expect(hasDocsConfigVariablesChanged(getVariablesHash(docsConfig.variables))).toBe(false);
+        expect(hasDocsConfigApiChanged(getDocsConfigApiHash(createDocsConfig('raw-page')))).toBe(true);
+        expect(hasDocsConfigNavigationChanged(getDocsConfigNavigationHash(createDocsConfig('new-page')))).toBe(true);
+        expect(hasDocsConfigVariablesChanged(getVariablesHash({ product: 'Mint' }))).toBe(true);
+    });
+    it('detects openapi and asyncapi references anywhere in navigation', () => {
+        expect(hasNavigationApiReference({
+            groups: [
+                {
+                    group: 'API',
+                    openapi: 'openapi.json',
+                },
+            ],
+        })).toBe(true);
+        expect(hasNavigationApiReference({
+            tabs: [
+                {
+                    tab: 'Realtime',
+                    groups: [
+                        {
+                            group: 'Events',
+                            asyncapi: 'asyncapi.json',
+                        },
+                    ],
+                },
+            ],
+        })).toBe(true);
+        expect(hasNavigationApiReference({
+            tabs: [
+                {
+                    tab: 'Realtime',
+                    asyncapi: 'asyncapi.json',
+                    groups: [
+                        {
+                            group: 'Events',
+                            asyncapi: 'asyncapi.json',
+                        },
+                    ],
+                },
+            ],
+        })).toBe(true);
+    });
+    it('allows plain MDX navigation through the navigation fast path', () => {
+        expect(hasNavigationApiReference({
+            groups: [
+                {
+                    group: 'Guides',
+                    pages: ['quickstart', 'install'],
+                },
+            ],
+        })).toBe(false);
+    });
+});

package/dist/__tests__/page-metadata-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,51 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { clearPageMetadataCache, generateDocsNavFromPageMetadataCache, upsertPageMetadataCacheEntryForFile, } from '../local-preview/listener/page-metadata-cache.js';
+const createDocsConfig = (pages) => ({
+    $schema: 'https://mintlify.com/docs.json',
+    name: 'Mintlify',
+    theme: 'mint',
+    colors: {
+        primary: '#16A34A',
+    },
+    navigation: {
+        pages,
+    },
+});
+describe('pageMetadataCache', () => {
+    beforeEach(() => {
+        clearPageMetadataCache();
+    });
+    it('regenerates docs nav with updated frontmatter metadata from the cache', () => {
+        upsertPageMetadataCacheEntryForFile('intro.mdx', '---\ntitle: Updated Intro\ndescription: Updated description\n---\n# Intro');
+        const generatedNav = generateDocsNavFromPageMetadataCache(createDocsConfig(['intro']));
+        expect(generatedNav).toMatchObject({
+            pages: [
+                {
+                    href: '/intro',
+                    title: 'Updated Intro',
+                    description: 'Updated description',
+                },
+            ],
+        });
+    });
+    it('reports when a page references an OpenAPI spec via frontmatter', () => {
+        expect(upsertPageMetadataCacheEntryForFile('plain.mdx', '---\ntitle: Plain\n---\n# Plain')).toBe(false);
+        expect(upsertPageMetadataCacheEntryForFile('endpoint.mdx', '---\nopenapi: GET /pets\n---')).toBe(true);
+    });
+    it('reports when a page references an AsyncAPI spec via frontmatter', () => {
+        expect(upsertPageMetadataCacheEntryForFile('channel.mdx', '---\nasyncapi: subscribe /events\n---')).toBe(true);
+    });
+    it('regenerates docs nav without pages removed from docs config navigation', () => {
+        upsertPageMetadataCacheEntryForFile('intro.mdx', '---\ntitle: Intro\n---\n# Intro');
+        upsertPageMetadataCacheEntryForFile('removed.mdx', '---\ntitle: Removed\n---\n# Removed');
+        const generatedNav = generateDocsNavFromPageMetadataCache(createDocsConfig(['intro']));
+        expect(generatedNav).toMatchObject({
+            pages: [
+                {
+                    href: '/intro',
+                    title: 'Intro',
+                },
+            ],
+        });
+    });
+});

package/dist/local-preview/listener/docs-config-cache.d.ts

@@ -0,0 +1,10 @@
+import type { DocsConfig } from '@mintlify/validation';
+export declare const getVariablesHash: (variables: Record<string, string> | undefined) => string;
+export declare const getDocsConfigApiHash: (docsConfig: DocsConfig) => string;
+export declare const getDocsConfigNavigationHash: (docsConfig: DocsConfig) => string;
+export declare const updateDocsConfigHashCache: (docsConfig: DocsConfig) => void;
+export declare const hasNavigationApiReference: (value: unknown) => boolean;
+export declare const hasDocsConfigApiChanged: (newApiHash: string) => boolean;
+export declare const hasDocsConfigNavigationChanged: (newNavigationHash: string) => boolean;
+export declare const hasDocsConfigVariablesChanged: (newVariablesHash: string) => boolean;
+export declare const clearDocsConfigCaches: () => void;

package/dist/local-preview/listener/docs-config-cache.js

@@ -0,0 +1,44 @@
+let docsConfigVariablesHash;
+let docsConfigApiHash;
+let docsConfigNavigationHash;
+const getJsonHash = (value) => {
+    return JSON.stringify(value ?? {});
+};
+export const getVariablesHash = (variables) => {
+    return getJsonHash(variables);
+};
+export const getDocsConfigApiHash = (docsConfig) => {
+    return getJsonHash(docsConfig.api);
+};
+export const getDocsConfigNavigationHash = (docsConfig) => {
+    return getJsonHash(docsConfig.navigation);
+};
+export const updateDocsConfigHashCache = (docsConfig) => {
+    docsConfigVariablesHash = getVariablesHash(docsConfig.variables);
+    docsConfigApiHash = getDocsConfigApiHash(docsConfig);
+    docsConfigNavigationHash = getDocsConfigNavigationHash(docsConfig);
+};
+export const hasNavigationApiReference = (value) => {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    if (Object.prototype.hasOwnProperty.call(value, 'openapi') ||
+        Object.prototype.hasOwnProperty.call(value, 'asyncapi')) {
+        return true;
+    }
+    return Object.values(value).some(hasNavigationApiReference);
+};
+export const hasDocsConfigApiChanged = (newApiHash) => {
+    return docsConfigApiHash == null || docsConfigApiHash !== newApiHash;
+};
+export const hasDocsConfigNavigationChanged = (newNavigationHash) => {
+    return docsConfigNavigationHash == null || docsConfigNavigationHash !== newNavigationHash;
+};
+export const hasDocsConfigVariablesChanged = (newVariablesHash) => {
+    return docsConfigVariablesHash == null || docsConfigVariablesHash !== newVariablesHash;
+};
+export const clearDocsConfigCaches = () => {
+    docsConfigVariablesHash = undefined;
+    docsConfigApiHash = undefined;
+    docsConfigNavigationHash = undefined;
+};

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

@@ -4,5 +4,6 @@ declare const listener: (triggerRefresh: () => void, options?: {
     groups?: string[];
 }) => void;
 declare const initializeFrontmatterHashCache: () => Promise<void>;
-export { initializeFrontmatterHashCache, initializeImportCache };
+declare const initializeDocsConfigHashCache: () => Promise<void>;
+export { initializeDocsConfigHashCache, initializeFrontmatterHashCache, initializeImportCache };
 export default listener;

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

@@ -11,19 +11,56 @@ import pathUtil from 'path';
 import { CMD_EXEC_PATH, NEXT_PROPS_PATH, NEXT_PUBLIC_PATH, CLIENT_PATH } from '../../constants.js';
 import { addChangeLog, addErrorLog, clearErrorLogs, getCurrentErrorLogs, } from '../../logging-state.js';
 import { AddedLog, DeletedLog, EditedLog, WarningLog, InfoLog, ErrorLog } from '../../logs.js';
+import { clearDocsConfigCaches, getDocsConfigApiHash, getDocsConfigNavigationHash, getVariablesHash, hasDocsConfigApiChanged, hasDocsConfigNavigationChanged, hasNavigationApiReference, hasDocsConfigVariablesChanged, updateDocsConfigHashCache, } from './docs-config-cache.js';
 import { generateDependentSnippets } from './generateDependentSnippets.js';
 import { generatePagesWithImports } from './generatePagesWithImports.js';
 import { getDocsState } from './getDocsState.js';
 import { initializeImportCache, updateImportCacheForFile, removeFromImportCache, getImportedFilesFromCache, syncImportedFileLocations, } from './importCache.js';
+import { clearPageMetadataCache, removePageMetadataCacheEntryForFile, upsertPageMetadataCacheEntry, upsertPageMetadataCacheEntryForFile, } from './page-metadata-cache.js';
 import { hasTrackedReferencedFile, refreshTrackedReferencedFiles } from './referencedFiles.js';
 import { regenerateAllSnippets } from './regenerateAllSnippets.js';
 import { resolveImportsFromImportClosure } from './resolve-imports-from-import-closure.js';
 import { resolvePageImports } from './resolve-page-imports.js';
-import { updateCustomLanguages, updateGeneratedNav, updateOpenApiFiles, upsertOpenApiFile, } from './update.js';
-import { getCurrentVariables, getMintIgnoreGlobs, handleParseError, isFileSizeValid, isJsonValid, seedFrontmatterHashForPage, shouldRegenerateNavForPage, suppressParseError, } from './utils.js';
+import { updateCustomLanguages, updateGeneratedNav, updateGeneratedNavFromPageMetadataCache, updateOpenApiFiles, upsertOpenApiFile, } from './update.js';
+import { getCurrentVariables, getMintIgnoreGlobs, handleParseError, isFileSizeValid, isJsonValid, readJsonFile, seedFrontmatterHashForPage, shouldRegenerateNavForPage, suppressParseError, } from './utils.js';
 const { readFile } = _promises;
 const frontmatterHashes = new Map();
 const SLOW_UPDATE_LOG_THRESHOLD_MS = 1000;
+const getCurrentDocsConfig = async () => {
+    const propsDocsJsonPath = pathUtil.join(NEXT_PROPS_PATH, 'docs.json');
+    try {
+        const propsDocsConfig = await readJsonFile(propsDocsJsonPath);
+        return propsDocsConfig;
+    }
+    catch { }
+    const docsJsonPath = pathUtil.join(CMD_EXEC_PATH, 'docs.json');
+    return await DocsConfigUpdater.getConfig(docsJsonPath, false, CMD_EXEC_PATH, suppressParseError);
+};
+const writeDocsConfigWithCurrentNavigation = async (docsConfig) => {
+    const propsDocsJsonPath = pathUtil.join(NEXT_PROPS_PATH, 'docs.json');
+    try {
+        const currentDocsConfig = await readJsonFile(propsDocsJsonPath);
+        await DocsConfigUpdater.writeConfigFile({ ...docsConfig, navigation: currentDocsConfig.navigation }, CLIENT_PATH);
+        return;
+    }
+    catch { }
+    await DocsConfigUpdater.writeConfigFile(docsConfig, CLIENT_PATH);
+};
+const getCurrentRawDocsConfig = async () => {
+    const docsJsonPath = pathUtil.join(CMD_EXEC_PATH, 'docs.json');
+    if (!(await fse.pathExists(docsJsonPath))) {
+        return undefined;
+    }
+    try {
+        return await DocsConfigUpdater.getConfig(docsJsonPath, false, CMD_EXEC_PATH, suppressParseError);
+    }
+    catch {
+        return undefined;
+    }
+};
+const hasDocsConfigApiRoutes = (docsConfig) => {
+    return docsConfig.api != null || hasNavigationApiReference(docsConfig.navigation);
+};
 const getElapsedMs = (startTime) => {
     return Number((process.hrtime.bigint() - startTime) / 1000000n);
 };
@@ -100,6 +137,7 @@ const onUnlinkEvent = async (filename, triggerRefresh, options) => {
         const importedFiles = getImportedFilesFromCache();
         const potentialCategory = getFileCategory(filename, { importedFiles });
         frontmatterHashes.delete(filename);
+        removePageMetadataCacheEntryForFile(filename);
         if (hasTrackedReferencedFile(filename)) {
             try {
                 const { mintConfig, openApiFiles, docsConfig } = await getDocsState(handleParseError);
@@ -219,6 +257,7 @@ const validateConfigFiles = async () => {
 };
 const initializeFrontmatterHashCache = async () => {
     frontmatterHashes.clear();
+    clearPageMetadataCache();
     const importedFiles = getImportedFilesFromCache();
     const pageFilenames = getFileListSync(CMD_EXEC_PATH).filter((file) => {
         return getFileCategory(file, { importedFiles }) === 'page';
@@ -228,10 +267,25 @@ const initializeFrontmatterHashCache = async () => {
             const filePath = pathUtil.join(CMD_EXEC_PATH, filename);
             const contentStr = (await readFile(filePath)).toString();
             seedFrontmatterHashForPage(filename, contentStr, frontmatterHashes, suppressParseError);
+            upsertPageMetadataCacheEntryForFile(filename, contentStr);
         }
         catch { }
     }));
 };
+const initializeDocsConfigHashCache = async () => {
+    clearDocsConfigCaches();
+    // Seed the cache from the raw config (no OpenAPI generation) so it stays
+    // consistent with the comparison done on each docs.json save.
+    const docsJsonPath = pathUtil.join(CMD_EXEC_PATH, 'docs.json');
+    try {
+        if (await fse.pathExists(docsJsonPath)) {
+            const docsConfig = await DocsConfigUpdater.getConfig(docsJsonPath, false, CMD_EXEC_PATH, suppressParseError);
+            updateDocsConfigHashCache(docsConfig);
+            return;
+        }
+    }
+    catch { }
+};
 /**
  * This function is called when a file is added or changed
  * @param filename
@@ -246,7 +300,7 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
     const potentialCategory = getFileCategory(filename, { importedFiles });
     if (hasTrackedReferencedFile(filename)) {
         try {
-            const { mintConfig, openApiFiles, docsConfig } = await getDocsState(handleParseError);
+            const { mintConfig, openApiFiles, docsConfig, pagesAcc } = await getDocsState(handleParseError);
             await refreshTrackedReferencedFiles();
             if (mintConfig) {
                 await MintConfigUpdater.writeConfigFile(mintConfig, CLIENT_PATH);
@@ -254,7 +308,7 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
             await DocsConfigUpdater.writeConfigFile(docsConfig, CLIENT_PATH);
             await updateOpenApiFiles(openApiFiles, suppressParseError);
             await updateCustomLanguages(docsConfig, suppressParseError);
-            await updateGeneratedNav(suppressParseError);
+            await updateGeneratedNav(suppressParseError, { pagesAcc, docsConfig });
         }
         catch (err) {
             if (getCurrentErrorLogs().length === 0) {
@@ -263,6 +317,12 @@ 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;
     }
@@ -271,6 +331,7 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
         return undefined;
     }
     let regenerateNav = false;
+    let regenerateNavFromPageMetadataCache = false;
     let category = potentialCategory === 'potentialYamlOpenApiSpec' ||
         potentialCategory === 'potentialJsonOpenApiSpec'
         ? 'staticFile'
@@ -279,16 +340,17 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
     switch (potentialCategory) {
         case 'page': {
             let contentStr = (await readFile(filePath)).toString();
-            regenerateNav = await shouldRegenerateNavForPage(filename, contentStr, frontmatterHashes, handleParseError);
+            regenerateNavFromPageMetadataCache = await shouldRegenerateNavForPage(filename, contentStr, frontmatterHashes, handleParseError);
             const tree = await preparseMdxTree(contentStr, CMD_EXEC_PATH, filePath, suppressParseError);
             const importsResponse = await findAndRemoveImports(tree);
             if (hasImports(importsResponse)) {
                 contentStr = stringifyTree(await resolvePageImports({ ...importsResponse, filename }));
             }
-            const { pageContent } = await createPage(filename, contentStr, CMD_EXEC_PATH, [], [], handleParseError);
+            const { pageContent, pageMetadata, slug } = await createPage(filename, contentStr, CMD_EXEC_PATH, [], [], handleParseError);
             await fse.outputFile(targetPath, pageContent, {
                 flag: 'w',
             });
+            upsertPageMetadataCacheEntry(slug, pageMetadata);
             break;
         }
         case 'snippet': {
@@ -317,6 +379,68 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
                 addErrorLog(_jsx(ErrorLog, { message: `Syntax error in ${filename}: ${error}` }));
                 return undefined;
             }
+            if (potentialCategory === 'docsConfig') {
+                try {
+                    // Parse the raw config only (cheap) so we can decide what actually
+                    // needs rebuilding before paying for the expensive OpenAPI/nav work.
+                    const docsConfig = await DocsConfigUpdater.getConfig(filePath, false, CMD_EXEC_PATH, handleParseError);
+                    const newApiHash = getDocsConfigApiHash(docsConfig);
+                    const apiChanged = hasDocsConfigApiChanged(newApiHash);
+                    const newNavigationHash = getDocsConfigNavigationHash(docsConfig);
+                    const navigationChanged = hasDocsConfigNavigationChanged(newNavigationHash);
+                    const newVariablesHash = getVariablesHash(docsConfig.variables);
+                    const variablesChanged = hasDocsConfigVariablesChanged(newVariablesHash);
+                    const shouldUseNavigationFastPath = navigationChanged && !apiChanged && !hasDocsConfigApiRoutes(docsConfig);
+                    const shouldRegenerateGeneratedData = apiChanged || (navigationChanged && hasDocsConfigApiRoutes(docsConfig));
+                    await refreshTrackedReferencedFiles();
+                    if (shouldUseNavigationFastPath) {
+                        // Plain MDX navigation changed without API changes: regenerate
+                        // generatedDocsNav from cached page metadata. If a page references a
+                        // 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);
+                        await DocsConfigUpdater.writeConfigFile(generatedDocsConfig, CLIENT_PATH);
+                    }
+                    else if (shouldRegenerateGeneratedData) {
+                        // Preserve the old full-rebuild route for top-level api, API-derived
+                        // navigation, and top-level api removals.
+                        const docsState = await getDocsState(handleParseError);
+                        await DocsConfigUpdater.writeConfigFile(docsState.docsConfig, CLIENT_PATH);
+                        await updateOpenApiFiles(docsState.openApiFiles, suppressParseError);
+                        await updateCustomLanguages(docsState.docsConfig, suppressParseError);
+                        await updateGeneratedNav(suppressParseError, {
+                            pagesAcc: docsState.pagesAcc,
+                            docsConfig: docsState.docsConfig,
+                        });
+                    }
+                    else {
+                        // Non-generated docs.json changes (theme, styling, metadata, etc.) do
+                        // not need OpenAPI/nav regeneration. Preserve the current generated
+                        // navigation so API-expanded docs config does not collapse to raw nav.
+                        await updateCustomLanguages(docsConfig, suppressParseError);
+                        await writeDocsConfigWithCurrentNavigation(docsConfig);
+                    }
+                    if (variablesChanged) {
+                        const updatedSnippets = await regenerateAllSnippets();
+                        await generatePagesWithImports(new Set(updatedSnippets));
+                    }
+                    // Update the cache only after every step above succeeded, so a failure
+                    // mid-update doesn't leave the cache claiming work that never happened.
+                    updateDocsConfigHashCache(docsConfig);
+                }
+                catch (err) {
+                    if (getCurrentErrorLogs().length > 0) {
+                        // no-op to suppress duplicate error logging
+                        return undefined;
+                    }
+                    else {
+                        console.error(err);
+                    }
+                }
+                break;
+            }
+            // mint.json: preserve the original full-rebuild behavior.
             regenerateNav = true;
             try {
                 const { mintConfig, openApiFiles, docsConfig } = await getDocsState(handleParseError);
@@ -337,10 +461,6 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
                     console.error(err);
                 }
             }
-            if (potentialCategory === 'docsConfig') {
-                const updatedSnippets = await regenerateAllSnippets();
-                await generatePagesWithImports(new Set(updatedSnippets));
-            }
             break;
         }
         case 'mintIgnore': {
@@ -410,12 +530,24 @@ const onUpdateEvent = async (filename, triggerRefresh, options = {}) => {
             break;
         }
     }
-    if (regenerateNav) {
+    if (regenerateNavFromPageMetadataCache) {
+        const rawDocsConfig = await getCurrentRawDocsConfig();
+        const docsConfig = rawDocsConfig ?? (await getCurrentDocsConfig());
+        if (hasDocsConfigApiRoutes(docsConfig)) {
+            const generatedDocsConfig = await updateGeneratedNav(suppressParseError);
+            await DocsConfigUpdater.writeConfigFile(generatedDocsConfig, CLIENT_PATH);
+        }
+        else {
+            await updateGeneratedNavFromPageMetadataCache(docsConfig, suppressParseError);
+        }
+    }
+    else if (regenerateNav) {
         // TODO: Instead of re-generating the entire nav, optimize by just updating the specific page that changed.
-        await updateGeneratedNav(suppressParseError);
+        const docsConfig = await updateGeneratedNav(suppressParseError);
+        await DocsConfigUpdater.writeConfigFile(docsConfig, CLIENT_PATH);
     }
     triggerRefresh();
     return category;
 };
-export { initializeFrontmatterHashCache, initializeImportCache };
+export { initializeDocsConfigHashCache, initializeFrontmatterHashCache, initializeImportCache };
 export default listener;

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

@@ -0,0 +1,9 @@
+import type { DecoratedNavigationPage } from '@mintlify/models';
+import type { DecoratedNavigationConfig, DocsConfig } from '@mintlify/validation';
+export declare const clearPageMetadataCache: () => void;
+export declare const upsertPageMetadataCacheEntry: (slug: string, pageMetadata: DecoratedNavigationPage) => void;
+export declare const removePageMetadataCacheEntry: (slug: string) => void;
+export declare const removePageMetadataCacheEntryForFile: (filename: string) => void;
+export declare const upsertPageMetadataCacheEntryForFile: (filename: string, contentStr: string) => boolean;
+export declare const ensurePageMetadataCacheForDocsConfig: (docsConfig: DocsConfig) => Promise<boolean>;
+export declare const generateDocsNavFromPageMetadataCache: (docsConfig: DocsConfig) => DecoratedNavigationConfig;

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

@@ -0,0 +1,55 @@
+import { getAllPathsInDocsNav, getDecoratedNavPageAndSlug } from '@mintlify/common';
+import { generateDecoratedDocsNavigationFromPages } from '@mintlify/prebuild';
+import fse from 'fs-extra';
+import pathUtil from 'path';
+import { CMD_EXEC_PATH } from '../../constants.js';
+const pageMetadataBySlug = {};
+const getPossiblePageFilenames = (pagePath) => {
+    const normalizedPath = pagePath.startsWith('/') ? pagePath.slice(1) : pagePath;
+    if (normalizedPath.endsWith('.mdx') || normalizedPath.endsWith('.md')) {
+        return [normalizedPath];
+    }
+    return [`${normalizedPath}.mdx`, `${normalizedPath}.md`];
+};
+export const clearPageMetadataCache = () => {
+    for (const slug of Object.keys(pageMetadataBySlug)) {
+        delete pageMetadataBySlug[slug];
+    }
+};
+export const upsertPageMetadataCacheEntry = (slug, pageMetadata) => {
+    pageMetadataBySlug[slug] = pageMetadata;
+};
+export const removePageMetadataCacheEntry = (slug) => {
+    delete pageMetadataBySlug[slug];
+};
+export const removePageMetadataCacheEntryForFile = (filename) => {
+    removePageMetadataCacheEntry(filename.replace(/\.mdx?$/, ''));
+};
+// Returns true when the page references an OpenAPI/AsyncAPI spec via frontmatter.
+// Those titles are derived from the schema, which the cache (built without spec
+// files) cannot reproduce, so callers route such pages through the full rebuild.
+export const upsertPageMetadataCacheEntryForFile = (filename, contentStr) => {
+    const { slug, pageMetadata } = getDecoratedNavPageAndSlug(filename, contentStr, [], []);
+    upsertPageMetadataCacheEntry(slug, pageMetadata);
+    return pageMetadata.openapi != null || pageMetadata.asyncapi != null;
+};
+// Returns true when any page in the navigation references an OpenAPI/AsyncAPI
+// spec via frontmatter.
+export const ensurePageMetadataCacheForDocsConfig = async (docsConfig) => {
+    const navPaths = getAllPathsInDocsNav(docsConfig.navigation);
+    const results = await Promise.all(navPaths.map(async (navPath) => {
+        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);
+        }
+        return false;
+    }));
+    return results.some((hasApiSpecPage) => hasApiSpecPage);
+};
+export const generateDocsNavFromPageMetadataCache = (docsConfig) => {
+    return generateDecoratedDocsNavigationFromPages(pageMetadataBySlug, docsConfig.navigation);
+};

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

@@ -1,6 +1,11 @@
 import { OpenApiFile } from '@mintlify/models';
+import type { DecoratedNavigationPage } from '@mintlify/models';
 import { DocsConfig } from '@mintlify/validation';
-export declare const updateGeneratedNav: (onError?: (message: string) => void) => Promise<void>;
+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 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,15 +4,32 @@ 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 { readJsonFile } from './utils.js';
-export const updateGeneratedNav = async (onError) => {
-    const { pagesAcc, docsConfig } = await getDocsState(onError);
-    const generatedDocsNav = await generateNav(pagesAcc, docsConfig);
+const writeGeneratedDocsNav = async (generatedDocsNav) => {
     const targetDocsPath = join(NEXT_PROPS_PATH, 'generatedDocsNav.json');
     await fse.outputFile(targetDocsPath, JSON.stringify(generatedDocsNav, null, 2), {
         flag: 'w',
     });
 };
+export const updateGeneratedNav = async (onError, providedState) => {
+    const { pagesAcc, docsConfig } = providedState ?? (await getDocsState(onError));
+    const generatedDocsNav = await generateNav(pagesAcc, docsConfig);
+    await writeGeneratedDocsNav(generatedDocsNav);
+    return docsConfig;
+};
+export const updateGeneratedNavFromPageMetadataCache = async (docsConfig, onError) => {
+    const hasApiSpecPage = await ensurePageMetadataCacheForDocsConfig(docsConfig);
+    if (hasApiSpecPage) {
+        // A navigation page references an OpenAPI/AsyncAPI spec via frontmatter, so
+        // its title is derived from the schema. The page metadata cache is built
+        // without spec files and can't reproduce those titles, so fall back to the
+        // full rebuild to match the non-fast-path (main branch) behavior.
+        return await updateGeneratedNav(onError);
+    }
+    await writeGeneratedDocsNav(generateDocsNavFromPageMetadataCache(docsConfig));
+    return docsConfig;
+};
 export const updateOpenApiFiles = async (providedOpenApiFiles, onError) => {
     if (providedOpenApiFiles == undefined) {
         const { openApiFiles } = await getDocsState(onError);

package/dist/local-preview/run.js

@@ -7,7 +7,7 @@ import { CMD_EXEC_PATH, NEXT_PUBLIC_PATH } from '../constants.js';
 import { addLog, removeLastLog } from '../logging-state.js';
 import { LaunchLog, UpdateLog } from '../logs.js';
 import { maybeFixMissingWindowsEnvVar } from '../util.js';
-import listener, { initializeFrontmatterHashCache, initializeImportCache } from './listener/index.js';
+import listener, { initializeDocsConfigHashCache, initializeFrontmatterHashCache, initializeImportCache, } from './listener/index.js';
 import { refreshTrackedReferencedFiles } from './listener/referencedFiles.js';
 import { getLocalNetworkIp } from './network.js';
 import { setupNext } from './setupNext.js';
@@ -146,6 +146,7 @@ export const run = async (argv) => {
     });
     await initializeImportCache(CMD_EXEC_PATH, argv.fileImportsMap);
     await initializeFrontmatterHashCache();
+    await initializeDocsConfigHashCache();
     await refreshTrackedReferencedFiles();
     listener(onChange);
 };