@mintlify/common 1.0.1023 → 1.0.1024

package/dist/navigation/getScopedNavForPath.test.js

@@ -0,0 +1,135 @@
+import { decoratedNavigationConfig } from './decoratedNavigationConfig.js';
+import { filterDivisions } from './filterDivisions.js';
+import { getAllPathsInDecoratedNav } from './getAllPathsInDecoratedNav.js';
+import { getScopedNavForPath } from './scopeNavToPath.js';
+const multiDivisionNav = {
+    versions: [
+        {
+            version: 'v2',
+            default: true,
+            languages: [
+                {
+                    language: 'en',
+                    groups: [
+                        {
+                            group: 'Guides',
+                            pages: [
+                                { title: 'Overview', href: '/en/guides/overview' },
+                                { title: 'New in v2', href: '/en/guides/new-in-v2' },
+                            ],
+                        },
+                        {
+                            group: 'Reference',
+                            pages: [{ title: 'API', href: '/en/reference/api' }],
+                        },
+                    ],
+                },
+                {
+                    language: 'es',
+                    groups: [
+                        {
+                            group: 'Guides',
+                            pages: [
+                                { title: 'Overview', href: '/es/guides/overview' },
+                                { title: 'New in v2', href: '/es/guides/new-in-v2' },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        },
+        {
+            version: 'v1',
+            languages: [
+                {
+                    language: 'en',
+                    groups: [
+                        {
+                            group: 'Guides',
+                            pages: [{ title: 'Overview', href: '/v1/en/guides/overview' }],
+                        },
+                    ],
+                },
+                {
+                    language: 'es',
+                    groups: [
+                        {
+                            group: 'Guides',
+                            pages: [{ title: 'Overview', href: '/v1/es/guides/overview' }],
+                        },
+                    ],
+                },
+            ],
+        },
+    ],
+};
+function filterWith(decoratedNav, currentPath, currentVersion, currentLanguage) {
+    return filterDivisions({
+        currentPath,
+        decoratedNav,
+        userGroups: new Set(),
+        currentVersion,
+        currentLanguage,
+        shouldUseDivisionMatch: true,
+        cache: { dropdownCache: new Map() },
+    });
+}
+function divisionSummary(result) {
+    return {
+        tabs: result.tabs.map(({ name, isActive }) => ({ name, isActive })),
+        anchors: result.anchors.map(({ name, isActive }) => ({ name, isActive })),
+        versions: result.versions.map(({ name, isActive }) => ({ name, isActive })),
+        languages: result.languages.map(({ name, isActive }) => ({ name, isActive })),
+        dropdowns: result.dropdowns.map(({ name, isActive }) => ({ name, isActive })),
+        products: result.products.map(({ name, isActive }) => ({ name, isActive })),
+    };
+}
+function mapHrefs(map) {
+    return new Map([...map.entries()].map(([key, value]) => [key, value.href]));
+}
+function assertInvariantForEveryPath(nav) {
+    const paths = getAllPathsInDecoratedNav(nav);
+    expect(paths.length).toBeGreaterThan(0);
+    for (const path of paths) {
+        const currentPath = `/${path.replace(/^\//, '')}`;
+        const scoped = getScopedNavForPath({ decoratedNav: nav, currentPath });
+        const full = filterWith(nav, currentPath, scoped.currentVersion, scoped.currentLanguage);
+        const rescoped = filterWith(scoped.scopedNav, currentPath, scoped.currentVersion, scoped.currentLanguage);
+        expect(rescoped.groupsOrPages, currentPath).toEqual(full.groupsOrPages);
+        expect(divisionSummary(rescoped), currentPath).toEqual(divisionSummary(full));
+        expect(mapHrefs(rescoped.firstHrefInVersion), currentPath).toEqual(mapHrefs(full.firstHrefInVersion));
+        expect(mapHrefs(rescoped.firstHrefInLanguage), currentPath).toEqual(mapHrefs(full.firstHrefInLanguage));
+        const derived = getScopedNavForPath({ decoratedNav: scoped.scopedNav, currentPath });
+        expect(derived.currentVersion, currentPath).toBe(scoped.currentVersion);
+        expect(derived.currentLanguage, currentPath).toBe(scoped.currentLanguage);
+    }
+}
+describe(getScopedNavForPath, () => {
+    it('filters identically to the full nav for every path in the versioned fixture', () => {
+        assertInvariantForEveryPath(decoratedNavigationConfig);
+    });
+    it('filters identically to the full nav for every path in a versioned multilang nav', () => {
+        assertInvariantForEveryPath(multiDivisionNav);
+    });
+    it('bakes the group-level fallback target into sibling version stubs', () => {
+        var _a, _b;
+        const scoped = getScopedNavForPath({
+            decoratedNav: multiDivisionNav,
+            currentPath: '/en/guides/new-in-v2',
+        });
+        expect(scoped.currentVersion).toBe('v2');
+        expect(scoped.currentLanguage).toBe('en');
+        expect((_a = scoped.firstHrefInVersion.get('v1')) === null || _a === void 0 ? void 0 : _a.href).toBe('/v1/en/guides/overview');
+        const rescoped = filterWith(scoped.scopedNav, '/en/guides/new-in-v2', 'v2', 'en');
+        expect((_b = rescoped.firstHrefInVersion.get('v1')) === null || _b === void 0 ? void 0 : _b.href).toBe('/v1/en/guides/overview');
+    });
+    it('drops sibling division page trees from the scoped nav', () => {
+        const scoped = getScopedNavForPath({
+            decoratedNav: multiDivisionNav,
+            currentPath: '/en/guides/overview',
+        });
+        const serialized = JSON.stringify(scoped.scopedNav);
+        expect(serialized).not.toContain('/v1/es/guides/overview');
+        expect(serialized).toContain('/en/guides/new-in-v2');
+    });
+});

package/dist/navigation/getVersionOrLanguageFromPath.d.ts

@@ -0,0 +1,12 @@
+import { LocaleType } from '@mintlify/models';
+import { DecoratedNavigationConfig } from '@mintlify/validation';
+/**
+ * Determine which division contains a given page.
+ *
+ * @param type The type of division to get
+ * @param decoratedNav The decorated navigation. Each page entry must have an `href` field that is prefixed with a `/`
+ * @param path The current path of the page, prefixed with a `/`
+ * @param defaultValue The default division value to use if the current page occurs multiple times in different divisions
+ * @param initialDivisionValue The initial division value to use if the current page is unversioned or unlocalized
+ */
+export declare function getVersionOrLanguageFromPath<T extends 'version' | 'language'>(type: T, entry: DecoratedNavigationConfig, path: string, defaultValue: T extends 'version' ? string | undefined : LocaleType | undefined, initialDivisionValue: T extends 'version' ? string | undefined : LocaleType | undefined): T extends 'version' ? string : LocaleType | undefined;

package/dist/navigation/getVersionOrLanguageFromPath.js

@@ -0,0 +1,71 @@
+import { divisions, } from '@mintlify/validation';
+import { readObjectArrayProperty } from '../divisions/iterateObjectArrayProperty.js';
+import { isEqualIgnoringLeadingSlash } from '../paths/isEqualIgnoringLeadingSlash.js';
+import { isCommonPage } from './isCommonPage.js';
+import { isPage } from './isPage.js';
+/**
+ * Determine which division contains a given page.
+ *
+ * @param type The type of division to get
+ * @param decoratedNav The decorated navigation. Each page entry must have an `href` field that is prefixed with a `/`
+ * @param path The current path of the page, prefixed with a `/`
+ * @param defaultValue The default division value to use if the current page occurs multiple times in different divisions
+ * @param initialDivisionValue The initial division value to use if the current page is unversioned or unlocalized
+ */
+export function getVersionOrLanguageFromPath(type, entry, path, defaultValue, initialDivisionValue) {
+    const result = getDivisionFromPathHelper(type, entry, entry, path, defaultValue, undefined);
+    const backupResult = defaultValue || initialDivisionValue;
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+    return (result || backupResult);
+}
+function getDivisionFromPathHelper(type, entry, parentEntry, path, defaultValue, nearestDivisionValue) {
+    var _a, _b;
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+    const undefinedResult = (type === 'version' ? '' : undefined);
+    if (typeof entry !== 'object')
+        return undefinedResult;
+    if (isPage(entry)) {
+        if (isEqualIgnoringLeadingSlash(entry.href, path)) {
+            const isCommon = isCommonPage(parentEntry, path);
+            // logic: if this pages was shared in multiple divisions, we should use the default one,
+            // if the page was not shared and only used in one division, we should use the nearest division
+            if (isCommon && defaultValue && defaultValue !== nearestDivisionValue)
+                return undefinedResult;
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+            return (type === 'version' ? ((_a = entry.version) !== null && _a !== void 0 ? _a : nearestDivisionValue) : nearestDivisionValue);
+        }
+        else {
+            return undefinedResult;
+        }
+    }
+    for (const key of [...divisions, 'groups', 'pages']) {
+        let subDivisions = (_b = readObjectArrayProperty(entry, key)) !== null && _b !== void 0 ? _b : [];
+        if (key === 'pages' && 'root' in entry && typeof entry.root === 'object') {
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- root is a DecoratedNavigationPage
+            subDivisions = [entry.root, ...subDivisions];
+        }
+        if (subDivisions.length > 0) {
+            for (const subDivision of subDivisions) {
+                let divisionValue;
+                if (type === 'version') {
+                    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+                    divisionValue = ('version' in subDivision
+                        ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+                            subDivision.version
+                        : undefined);
+                }
+                else {
+                    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+                    divisionValue = ('language' in subDivision
+                        ? // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Please fix this violation when you can!
+                            subDivision.language
+                        : undefined);
+                }
+                const divisionFromSubDivision = getDivisionFromPathHelper(type, subDivision, parentEntry, path, defaultValue, divisionValue !== null && divisionValue !== void 0 ? divisionValue : nearestDivisionValue);
+                if (divisionFromSubDivision && divisionFromSubDivision !== undefinedResult)
+                    return divisionFromSubDivision;
+            }
+        }
+    }
+    return undefinedResult;
+}

package/dist/navigation/getVersionOrLanguageFromPath.test.d.ts

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

package/dist/navigation/getVersionOrLanguageFromPath.test.js

@@ -0,0 +1,133 @@
+import { getVersionOrLanguageFromPath } from './getVersionOrLanguageFromPath.js';
+describe(getVersionOrLanguageFromPath, () => {
+    it('should return no version if user has not set versioning', () => {
+        expect(getVersionOrLanguageFromPath('version', {
+            groups: [
+                {
+                    group: 'Getting started',
+                    pages: [{ title: '', href: '/welcome' }],
+                },
+            ],
+        }, '/random-page', '', 'v1')).toEqual('v1');
+    });
+    it('should return default version if path has no match in navigation', () => {
+        expect(getVersionOrLanguageFromPath('version', {
+            groups: [
+                {
+                    group: 'Getting started',
+                    pages: [{ title: '', href: '/welcome' }],
+                },
+            ],
+        }, '/welcome', '', '')).toEqual('');
+    });
+    it('should return correct version if path points to a page with a specified version', () => {
+        expect(getVersionOrLanguageFromPath('version', {
+            versions: [
+                {
+                    version: 'v1',
+                    pages: [
+                        {
+                            title: 'API V1',
+                            href: '/v1/api/hello',
+                        },
+                        {
+                            title: 'API V1',
+                            href: '/v1/api/world',
+                        },
+                    ],
+                },
+                {
+                    version: 'v2',
+                    pages: [
+                        {
+                            title: 'API V2',
+                            href: '/v2/api/hello',
+                        },
+                        {
+                            title: 'API V2',
+                            href: '/v2/api/world',
+                        },
+                    ],
+                },
+            ],
+        }, '/v2/api/hello', '', 'v1')).toEqual('v2');
+    });
+    it('should return correct version if there are nested pages groups and the wanted page is inside the nested group', () => {
+        expect(getVersionOrLanguageFromPath('version', {
+            versions: [
+                {
+                    version: 'v1',
+                    pages: [
+                        {
+                            title: '',
+                            href: '/v1/api/hello-world',
+                        },
+                        {
+                            group: 'API V1 Nested',
+                            pages: [{ title: '', href: '/v1/api/hello-world-nested' }],
+                        },
+                    ],
+                },
+                {
+                    version: 'v2',
+                    pages: [{ title: '', href: '/v2/api/hello-world' }],
+                },
+            ],
+        }, '/v1/api/hello-world-nested', '', 'v2')).toEqual('v1');
+    });
+    it('should return correct version if there are nested pages groups and the wanted page is outside of the nested group', () => {
+        expect(getVersionOrLanguageFromPath('version', {
+            versions: [
+                {
+                    version: 'v1',
+                    pages: [
+                        { title: '', href: '/v1/hello/world' },
+                        {
+                            group: 'API V1 Nested',
+                            pages: [{ title: '', href: '/v1/api/hello-world-nested' }],
+                        },
+                    ],
+                },
+                {
+                    version: 'v2',
+                    pages: [{ title: '', href: '/v2/hello/world' }],
+                },
+            ],
+        }, '/v1/hello/world', '', 'v2')).toEqual('v1');
+    });
+    it('should return correct version for a root page in a group', () => {
+        expect(getVersionOrLanguageFromPath('version', {
+            versions: [
+                {
+                    version: 'v1',
+                    groups: [
+                        {
+                            group: 'API V1',
+                            root: { title: 'V1 Root', href: '/v1/root' },
+                            pages: [{ title: '', href: '/v1/api/hello' }],
+                        },
+                    ],
+                },
+                {
+                    version: 'v2',
+                    pages: [{ title: '', href: '/v2/api/hello' }],
+                },
+            ],
+        }, '/v1/root', '', 'v2')).toEqual('v1');
+    });
+    it('should return correct version if default version is set and there are shared pages', () => {
+        expect(getVersionOrLanguageFromPath('version', {
+            versions: [
+                {
+                    version: 'v1',
+                    pages: [{ title: '', href: '/hello/world' }],
+                },
+                {
+                    version: 'v2',
+                    default: true,
+                    pages: [{ title: '', href: '/hello/world' }],
+                },
+            ],
+        }, '/hello/world', 'v2', 'v1')).toEqual('v2');
+    });
+});

package/dist/navigation/index.d.ts

@@ -6,5 +6,10 @@ export * from './generatePathToBreadcrumbsMapForDocsConfig.js';
 export * from './getAllPathsInDocsNav.js';
 export * from './getAllPathsInDecoratedNav.js';
 export * from './checkNavAccess.js';
+export * from './filterDivisions.js';
+export * from './updateFirstHrefInDivision.js';
+export * from './scopeNavToPath.js';
+export * from './getVersionOrLanguageFromPath.js';
+export * from './isCommonPage.js';
 export * from './getFirstPageFromNavConfig.js';
 export * from './prioritize-default-division-item.js';

package/dist/navigation/index.js

@@ -6,5 +6,10 @@ export * from './generatePathToBreadcrumbsMapForDocsConfig.js';
 export * from './getAllPathsInDocsNav.js';
 export * from './getAllPathsInDecoratedNav.js';
 export * from './checkNavAccess.js';
+export * from './filterDivisions.js';
+export * from './updateFirstHrefInDivision.js';
+export * from './scopeNavToPath.js';
+export * from './getVersionOrLanguageFromPath.js';
+export * from './isCommonPage.js';
 export * from './getFirstPageFromNavConfig.js';
 export * from './prioritize-default-division-item.js';

package/dist/navigation/isCommonPage.d.ts

@@ -0,0 +1,8 @@
+import { DecoratedNavigationConfig } from '@mintlify/validation';
+/**
+ * Check if the page is common in multiple divisions
+ * @param entry - The navigation config entry
+ * @param path - The path to check
+ * @returns True if the page is common in multiple divisions, false otherwise
+ */
+export declare function isCommonPage(entry: DecoratedNavigationConfig, path: string): boolean;

package/dist/navigation/isCommonPage.js

@@ -0,0 +1,36 @@
+import { divisions } from '@mintlify/validation';
+import { readObjectArrayProperty } from '../divisions/iterateObjectArrayProperty.js';
+import { isEqualIgnoringLeadingSlash } from '../paths/isEqualIgnoringLeadingSlash.js';
+import { isPage } from './isPage.js';
+/**
+ * Check if the page is common in multiple divisions
+ * @param entry - The navigation config entry
+ * @param path - The path to check
+ * @returns True if the page is common in multiple divisions, false otherwise
+ */
+export function isCommonPage(entry, path) {
+    const occurrences = { value: 0 };
+    isCommonPageRecursive(entry, path, occurrences);
+    return occurrences.value > 1;
+}
+function isCommonPageRecursive(entry, path, occurrences) {
+    if (typeof entry !== 'object')
+        return;
+    if (isPage(entry)) {
+        if (isEqualIgnoringLeadingSlash(entry.href, path)) {
+            occurrences.value++;
+        }
+    }
+    for (const key of [...divisions, 'groups', 'pages']) {
+        if (key === 'pages' && 'root' in entry && typeof entry.root === 'object') {
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- root is a DecoratedNavigationPage
+            isCommonPageRecursive(entry.root, path, occurrences);
+        }
+        const subDivisions = readObjectArrayProperty(entry, key);
+        if (subDivisions) {
+            for (const subDivision of subDivisions) {
+                isCommonPageRecursive(subDivision, path, occurrences);
+            }
+        }
+    }
+}

package/dist/navigation/isCommonPage.test.d.ts

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

package/dist/navigation/isCommonPage.test.js

@@ -0,0 +1,56 @@
+import { isCommonPage } from './isCommonPage.js';
+describe(isCommonPage, () => {
+    it('should return true if the page is common in multiple divisions', () => {
+        expect(isCommonPage({
+            tabs: [
+                {
+                    tab: 'Getting started',
+                    pages: [{ title: '', href: '/welcome' }],
+                },
+                {
+                    tab: 'Components',
+                    pages: [{ title: '', href: '/welcome' }],
+                },
+            ],
+        }, '/welcome')).toBe(true);
+    });
+    it('should return true if the page is common in nested divisions', () => {
+        expect(isCommonPage({
+            versions: [
+                {
+                    version: 'v1',
+                    pages: [{ title: '', href: '/welcome' }],
+                },
+                {
+                    version: 'v2',
+                    tabs: [{ tab: 'Getting started', pages: [{ title: '', href: '/welcome' }] }],
+                },
+            ],
+        }, '/welcome')).toBe(true);
+    });
+    it('should return true if a root page is common across divisions', () => {
+        expect(isCommonPage({
+            tabs: [
+                {
+                    tab: 'Getting started',
+                    groups: [
+                        {
+                            group: 'Group 1',
+                            root: { title: '', href: '/welcome' },
+                            pages: [{ title: '', href: '/other' }],
+                        },
+                    ],
+                },
+                {
+                    tab: 'Components',
+                    pages: [{ title: '', href: '/welcome' }],
+                },
+            ],
+        }, '/welcome')).toBe(true);
+    });
+    it('should return false if the page is not common in multiple divisions', () => {
+        expect(isCommonPage({
+            tabs: [{ tab: 'Getting started', pages: [{ title: '', href: '/welcome' }] }],
+        }, '/welcome')).toBe(false);
+    });
+});

package/dist/navigation/pathsDifferByOneSegment.test.d.ts

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

package/dist/navigation/pathsDifferByOneSegment.test.js

@@ -0,0 +1,91 @@
+import { pathsDifferByOneSegment } from './updateFirstHrefInDivision.js';
+describe('pathsDifferByOneSegment', () => {
+    describe('language type', () => {
+        it('returns true for paths that differ only by locale prefix', () => {
+            expect(pathsDifferByOneSegment('/ja/getting-started', '/getting-started', 'language')).toBe(true);
+            expect(pathsDifferByOneSegment('/getting-started', '/ja/getting-started', 'language')).toBe(true);
+        });
+        it('returns true for paths with different locale prefixes', () => {
+            expect(pathsDifferByOneSegment('/ja/getting-started', '/es/getting-started', 'language')).toBe(true);
+            expect(pathsDifferByOneSegment('/fr/docs/intro', '/de/docs/intro', 'language')).toBe(true);
+        });
+        it('returns false for paths with different content', () => {
+            expect(pathsDifferByOneSegment('/ja/getting-started', '/ja/quickstart', 'language')).toBe(false);
+            expect(pathsDifferByOneSegment('/getting-started', '/quickstart', 'language')).toBe(false);
+        });
+        it('returns false for paths with same locale', () => {
+            expect(pathsDifferByOneSegment('/ja/getting-started', '/ja/getting-started', 'language')).toBe(false);
+        });
+        it('returns false when neither path has a locale', () => {
+            expect(pathsDifferByOneSegment('/getting-started', '/getting-started', 'language')).toBe(false);
+        });
+        describe('index page handling', () => {
+            it('treats /path/index and /path as equivalent', () => {
+                expect(pathsDifferByOneSegment('/ja/guides/getting-started/index', '/guides/getting-started', 'language')).toBe(true);
+                expect(pathsDifferByOneSegment('/guides/getting-started', '/ja/guides/getting-started/index', 'language')).toBe(true);
+            });
+            it('treats /locale/path/index and /path/index as equivalent', () => {
+                expect(pathsDifferByOneSegment('/ja/guides/getting-started/index', '/guides/getting-started/index', 'language')).toBe(true);
+            });
+            it('treats /locale1/path/index and /locale2/path as equivalent', () => {
+                expect(pathsDifferByOneSegment('/ja/guides/getting-started/index', '/es/guides/getting-started', 'language')).toBe(true);
+            });
+            it('handles deeply nested index pages', () => {
+                expect(pathsDifferByOneSegment('/ja/guides/api/reference/index', '/guides/api/reference', 'language')).toBe(true);
+            });
+            it('does not treat index as special when not the last segment', () => {
+                expect(pathsDifferByOneSegment('/ja/index/getting-started', '/index/getting-started', 'language')).toBe(true);
+                expect(pathsDifferByOneSegment('/ja/index/getting-started', '/getting-started', 'language')).toBe(false);
+            });
+        });
+        describe('with docs base path', () => {
+            it('handles docs prefix correctly', () => {
+                expect(pathsDifferByOneSegment('/docs/ja/getting-started', '/docs/getting-started', 'language')).toBe(true);
+                expect(pathsDifferByOneSegment('/docs/ja/getting-started', '/docs/es/getting-started', 'language')).toBe(true);
+            });
+            it('returns false when docs prefix differs', () => {
+                expect(pathsDifferByOneSegment('/docs/ja/getting-started', '/ja/getting-started', 'language')).toBe(false);
+            });
+            it('handles docs prefix with index pages', () => {
+                expect(pathsDifferByOneSegment('/docs/ja/guides/index', '/docs/guides', 'language')).toBe(true);
+            });
+            it('handles locale-first docs paths with version segments', () => {
+                expect(pathsDifferByOneSegment('/es/docs/2025_12/getting-started', '/docs/2025_12/getting-started', 'language')).toBe(true);
+            });
+            it('returns false for locale-first docs paths when version segment differs', () => {
+                expect(pathsDifferByOneSegment('/es/docs/2025_12/getting-started', '/docs/getting-started', 'language')).toBe(false);
+            });
+        });
+    });
+    describe('version type', () => {
+        it('returns true for paths that differ by one segment (not last)', () => {
+            expect(pathsDifferByOneSegment('/v1/getting-started', '/v2/getting-started', 'version')).toBe(true);
+        });
+        it('returns true for root-vs-prefixed paths with same content', () => {
+            expect(pathsDifferByOneSegment('/2025-09/getting-started', '/getting-started', 'version')).toBe(true);
+            expect(pathsDifferByOneSegment('/getting-started', '/2025-09/getting-started', 'version')).toBe(true);
+        });
+        it('returns true for docs-prefixed root-vs-prefixed paths with same content', () => {
+            expect(pathsDifferByOneSegment('/docs/2025-09/getting-started', '/docs/getting-started', 'version')).toBe(true);
+            expect(pathsDifferByOneSegment('/docs/2025-09/guides/overview', '/docs/guides/overview', 'version')).toBe(true);
+        });
+        it('returns false when docs base path presence differs', () => {
+            expect(pathsDifferByOneSegment('/docs/2025-09/getting-started', '/2025-09/getting-started', 'version')).toBe(false);
+        });
+        it('returns false for paths that differ by last segment', () => {
+            expect(pathsDifferByOneSegment('/api/v1', '/api/v2', 'version')).toBe(false);
+        });
+        it('returns false for paths with different lengths', () => {
+            expect(pathsDifferByOneSegment('/v1/api/docs', '/v2/api', 'version')).toBe(false);
+        });
+        it('returns false for paths with multiple differences', () => {
+            expect(pathsDifferByOneSegment('/v1/foo/bar', '/v2/baz/bar', 'version')).toBe(false);
+        });
+        it('returns false for paths with fewer than 2 segments', () => {
+            expect(pathsDifferByOneSegment('/v1', '/v2', 'version')).toBe(false);
+        });
+        it('returns false for root-vs-prefixed paths with different content', () => {
+            expect(pathsDifferByOneSegment('/2025-09/getting-started', '/quickstart', 'version')).toBe(false);
+        });
+    });
+});

package/dist/navigation/scopeNavToPath.d.ts

@@ -0,0 +1,18 @@
+import { LocaleType } from '@mintlify/models';
+import type { DecoratedNavigationConfig, DocsConfig } from '@mintlify/validation';
+import { DivisionMatch } from './updateFirstHrefInDivision.js';
+export declare function scopeDecoratedNavToPath(nav: DecoratedNavigationConfig, currentPath: string): DecoratedNavigationConfig;
+export declare function scopeDocsConfigNavToPath(docsConfig: DocsConfig, currentPath: string): DocsConfig;
+export type ScopedNavForPath = {
+    scopedNav: DecoratedNavigationConfig;
+    firstHrefInVersion: Map<string | undefined, DivisionMatch>;
+    firstHrefInLanguage: Map<LocaleType | undefined, DivisionMatch>;
+    currentVersion: string | undefined;
+    currentLanguage: LocaleType | undefined;
+};
+export declare function getScopedNavForPath({ decoratedNav, currentPath, userGroups, isPreview, }: {
+    decoratedNav: DecoratedNavigationConfig;
+    currentPath: string;
+    userGroups?: Set<string>;
+    isPreview?: boolean;
+}): ScopedNavForPath;