@mintlify/common 1.0.1031 → 1.0.1033

package/dist/mdx/plugins/rehype/rehypeParamFieldIds.js

@@ -4,31 +4,59 @@ export function generateParamFieldId(name, count) {
     const suffix = count > 0 ? `_${count}` : '';
     return slugify(`param-${name}${suffix}`, { decamelize: true, separator: '-' });
 }
+const PARAM_FIELD_COMPONENTS = ['ParamField', 'Param', 'ResponseField'];
+const PARAM_NAME_PRECEDENCE = ['query', 'path', 'body', 'header'];
+const getStringAttribute = (element, attrName) => {
+    const attr = element.attributes.find((attr) => 'name' in attr && attr.name === attrName);
+    return attr && typeof attr.value === 'string' && attr.value ? attr.value : undefined;
+};
+const hasIdAttribute = (element) => element.attributes.some((attr) => 'name' in attr && attr.name === 'id');
+const getFieldName = (element) => {
+    if (element.name === 'ResponseField')
+        return getStringAttribute(element, 'name');
+    for (const attrName of PARAM_NAME_PRECEDENCE) {
+        const value = getStringAttribute(element, attrName);
+        if (value)
+            return value;
+    }
+    return undefined;
+};
 export const rehypeParamFieldIds = () => {
     return (tree) => {
-        const paramCounts = new Map();
+        const claimedIds = new Set();
+        const slugCounts = new Map();
+        visit(tree, 'mdxJsxFlowElement', (element) => {
+            if (!element.name || !PARAM_FIELD_COMPONENTS.includes(element.name))
+                return;
+            if (!hasIdAttribute(element))
+                return;
+            const explicitId = getStringAttribute(element, 'id');
+            if (explicitId)
+                claimedIds.add(explicitId);
+        });
         visit(tree, 'mdxJsxFlowElement', (element) => {
             var _a;
-            if (element.name === 'ParamField' ||
-                element.name === 'Param' ||
-                element.name === 'ResponseField') {
-                const nameAttr = element.attributes.find((attr) => 'name' in attr &&
-                    (attr.name === 'query' ||
-                        attr.name === 'path' ||
-                        attr.name === 'body' ||
-                        attr.name === 'header' ||
-                        attr.name === 'name'));
-                if (nameAttr && typeof nameAttr.value === 'string' && nameAttr.value) {
-                    const currentCount = (_a = paramCounts.get(nameAttr.value)) !== null && _a !== void 0 ? _a : 0;
-                    paramCounts.set(nameAttr.value, currentCount + 1);
-                    const id = generateParamFieldId(nameAttr.value, currentCount);
-                    element.attributes.push({
-                        type: 'mdxJsxAttribute',
-                        name: 'id',
-                        value: id,
-                    });
-                }
+            if (!element.name || !PARAM_FIELD_COMPONENTS.includes(element.name))
+                return;
+            if (hasIdAttribute(element))
+                return;
+            const name = getFieldName(element);
+            if (!name)
+                return;
+            const baseSlug = generateParamFieldId(name, 0);
+            let count = (_a = slugCounts.get(baseSlug)) !== null && _a !== void 0 ? _a : 0;
+            let id = generateParamFieldId(name, count);
+            while (claimedIds.has(id)) {
+                count += 1;
+                id = generateParamFieldId(name, count);
             }
+            slugCounts.set(baseSlug, count + 1);
+            claimedIds.add(id);
+            element.attributes.push({
+                type: 'mdxJsxAttribute',
+                name: 'id',
+                value: id,
+            });
         });
         return tree;
     };

package/dist/mdx/plugins/remark/remarkComponentIds.js

@@ -93,31 +93,31 @@ export const remarkComponentIds = (pageMetadata) => (tree) => {
     const processTabsRecursively = (node) => {
         if (node.type === 'mdxJsxFlowElement' && node.name === 'Tab') {
             const slug = tabSlugs.get(node);
-            if (!slug)
-                return;
-            // `slug` already equals the explicit `id` when one was provided, so only
-            // add the attribute when the Tab doesn't already have one.
-            const hasId = node.attributes.some((attr) => 'name' in attr && attr.name === 'id');
-            if (!hasId) {
-                node.attributes.push(createMdxJsxAttribute('id', slug));
-            }
-            const childTabIds = [];
-            for (const child of node.children) {
-                const childIds = collectDirectChildIds(child, 'Tab');
-                childTabIds.push(...childIds);
-            }
-            if (childTabIds.length > 0) {
-                try {
-                    node.attributes.push(createMdxJsxAttribute(CHILD_TAB_IDS_ATTRIBUTE, JSON.stringify(childTabIds)));
+            if (slug) {
+                // `slug` already equals the explicit `id` when one was provided, so only
+                // add the attribute when the Tab doesn't already have one.
+                const hasId = node.attributes.some((attr) => 'name' in attr && attr.name === 'id');
+                if (!hasId) {
+                    node.attributes.push(createMdxJsxAttribute('id', slug));
                 }
-                catch (_a) { }
-            }
-            const childHeadingIds = collectDirectChildIds(node, 'Heading');
-            if (childHeadingIds.length > 0) {
-                try {
-                    node.attributes.push(createMdxJsxAttribute(CHILD_HEADING_IDS_ATTRIBUTE, JSON.stringify(childHeadingIds)));
+                const childTabIds = [];
+                for (const child of node.children) {
+                    const childIds = collectDirectChildIds(child, 'Tab');
+                    childTabIds.push(...childIds);
+                }
+                if (childTabIds.length > 0) {
+                    try {
+                        node.attributes.push(createMdxJsxAttribute(CHILD_TAB_IDS_ATTRIBUTE, JSON.stringify(childTabIds)));
+                    }
+                    catch (_a) { }
+                }
+                const childHeadingIds = collectDirectChildIds(node, 'Heading');
+                if (childHeadingIds.length > 0) {
+                    try {
+                        node.attributes.push(createMdxJsxAttribute(CHILD_HEADING_IDS_ATTRIBUTE, JSON.stringify(childHeadingIds)));
+                    }
+                    catch (_b) { }
                 }
-                catch (_b) { }
             }
             for (const child of node.children) {
                 processTabsRecursively(child);

package/dist/mdx/plugins/remark/remarkExtractChangelogFilters.js

@@ -21,11 +21,20 @@ export function remarkExtractChangelogFilters(mdxExtracts) {
             if (!Array.isArray(tags)) {
                 continue;
             }
-            tags.forEach((tag) => {
-                if (!!tag.trim()) {
-                    tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
+            const nodeTags = new Set();
+            for (const tag of tags) {
+                if (typeof tag !== 'string') {
+                    console.warn(`Invalid tag ${JSON.stringify(tag)} in <Update> tags — tags must be strings. Skipping it.`);
+                    continue;
                 }
-            });
+                const trimmed = tag.trim();
+                if (trimmed) {
+                    nodeTags.add(trimmed);
+                }
+            }
+            for (const tag of nodeTags) {
+                tagCounts.set(tag, (tagCounts.get(tag) || 0) + 1);
+            }
         }
         const filters = Array.from(tagCounts.entries())
             .map(([tag, count]) => ({

package/dist/mdx/plugins/remark/remarkExtractTableOfContents.js

@@ -28,9 +28,13 @@ export const remarkExtractTableOfContents = (mdxExtracts, pageMetadata) => {
         seenSlugs.set(slug, count + 1);
         if (count === 0)
             return slug;
-        const suffixed = `${slug}-${count + 1}`;
-        if (!seenSlugs.has(suffixed))
-            seenSlugs.set(suffixed, 0);
+        let suffix = count + 1;
+        let suffixed = `${slug}-${suffix}`;
+        while (seenSlugs.has(suffixed)) {
+            suffix += 1;
+            suffixed = `${slug}-${suffix}`;
+        }
+        seenSlugs.set(suffixed, 1);
         return suffixed;
     };
     return (tree) => {

package/dist/mdx/plugins/remark/remarkSplitTabs.js

@@ -1,4 +1,12 @@
 import { visit } from 'unist-util-visit';
+import { isMdxJsxFlowElement } from '../../utils.js';
+const countTabs = (children) => children.reduce((count, child) => {
+    if (!isMdxJsxFlowElement(child))
+        return count;
+    if (child.name == null)
+        return count + countTabs(child.children);
+    return child.name === 'Tab' ? count + 1 : count;
+}, 0);
 export const remarkSplitTabs = () => (tree) => {
     const tabsToProcess = [];
     visit(tree, 'mdxJsxFlowElement', (node, index, parent) => {
@@ -9,7 +17,7 @@ export const remarkSplitTabs = () => (tree) => {
     // process in reverse document order so splices don't shift the saved
     // indices of earlier siblings or clone-before-split nested Tabs
     for (const { node, index, parent } of tabsToProcess.reverse()) {
-        const numberOfTabs = node.children.length;
+        const numberOfTabs = countTabs(node.children);
         if (numberOfTabs <= 1)
             continue;
         const newNodes = [];

package/dist/mdx/plugins/remark/remarkValidateTabs.js

@@ -1,11 +1,19 @@
-import { visit } from 'unist-util-visit';
+import { visitParents } from 'unist-util-visit-parents';
+import { isMdxJsxFlowElement, isMdxJsxFragment } from '../../utils.js';
 export const remarkValidateTabs = () => (tree) => {
-    visit(tree, 'mdxJsxFlowElement', (node, _idx, parent) => {
-        if (node.name === 'Tab') {
-            const parentElement = parent;
-            if (!parentElement || parentElement.name !== 'Tabs') {
-                console.warn('Please ensure that all <Tab> components are direct children of <Tabs>.');
-            }
+    visitParents(tree, 'mdxJsxFlowElement', (node, ancestors) => {
+        var _a;
+        if (node.name !== 'Tab')
+            return;
+        const meaningfulAncestors = ancestors.filter((ancestor) => !isMdxJsxFragment(ancestor));
+        const parent = meaningfulAncestors[meaningfulAncestors.length - 1];
+        const parentIsTabs = parent !== undefined && isMdxJsxFlowElement(parent) && parent.name === 'Tabs';
+        if (!parentIsTabs) {
+            console.warn('Please ensure that all <Tab> components are direct children of <Tabs>.');
+        }
+        const title = (_a = node.attributes.find((attr) => 'name' in attr && attr.name === 'title')) === null || _a === void 0 ? void 0 : _a.value;
+        if (title === '') {
+            console.warn('<Tab> has an empty title — the tab has no accessible name and cannot deep-link. Add a descriptive title.');
         }
     });
 };

package/dist/navigation/getScopedNavForPath.test.js

@@ -87,12 +87,16 @@ function divisionSummary(result) {
 function mapHrefs(map) {
     return new Map([...map.entries()].map(([key, value]) => [key, value.href]));
 }
-function assertInvariantForEveryPath(nav) {
+function assertInvariantForEveryPath(nav, includeProductVersionMetadata = false) {
     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 scoped = getScopedNavForPath({
+            decoratedNav: nav,
+            currentPath,
+            includeProductVersionMetadata,
+        });
         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);
@@ -132,4 +136,149 @@ describe(getScopedNavForPath, () => {
         expect(serialized).not.toContain('/v1/es/guides/overview');
         expect(serialized).toContain('/en/guides/new-in-v2');
     });
+    describe('includeProductVersionMetadata', () => {
+        const productNav = {
+            products: [
+                {
+                    product: 'Model Serving',
+                    versions: [
+                        {
+                            version: '6.0',
+                            default: true,
+                            groups: [
+                                {
+                                    group: 'Guides',
+                                    pages: [
+                                        { title: 'Quickstart', href: '/serving/6.0/quickstart' },
+                                        { title: 'Endpoints', href: '/serving/6.0/endpoints' },
+                                    ],
+                                },
+                            ],
+                        },
+                        {
+                            version: '5.9',
+                            groups: [
+                                {
+                                    group: 'Guides',
+                                    pages: [{ title: 'Quickstart', href: '/serving/5.9/quickstart' }],
+                                },
+                            ],
+                        },
+                    ],
+                },
+                {
+                    product: 'Workbench',
+                    global: {
+                        versions: [{ version: 'external-9.9', href: 'https://legacy.example.com' }],
+                    },
+                    versions: [
+                        {
+                            version: '3.2',
+                            name: 'Workbench 3.2',
+                            default: true,
+                            groups: [
+                                { group: 'Guides', pages: [{ title: 'Setup', href: '/workbench/3.2/setup' }] },
+                            ],
+                        },
+                        {
+                            version: '3.1',
+                            groups: [
+                                { group: 'Guides', pages: [{ title: 'Setup', href: '/workbench/3.1/setup' }] },
+                            ],
+                        },
+                        {
+                            version: '3.0-beta',
+                            hidden: true,
+                            groups: [
+                                { group: 'Guides', pages: [{ title: 'Setup', href: '/workbench/3.0/setup' }] },
+                            ],
+                        },
+                    ],
+                },
+            ],
+        };
+        const currentPath = '/serving/6.0/quickstart';
+        function findProduct(nav, name) {
+            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
+            const products = nav.products;
+            return products.find((product) => product.product === name);
+        }
+        it('drops sibling product versions by default', () => {
+            var _a;
+            const scoped = getScopedNavForPath({ decoratedNav: productNav, currentPath });
+            expect((_a = findProduct(scoped.scopedNav, 'Workbench')) === null || _a === void 0 ? void 0 : _a.versions).toBeUndefined();
+        });
+        it('keeps pageless version metadata on sibling product stubs when enabled', () => {
+            var _a;
+            const scoped = getScopedNavForPath({
+                decoratedNav: productNav,
+                currentPath,
+                includeProductVersionMetadata: true,
+            });
+            expect((_a = findProduct(scoped.scopedNav, 'Workbench')) === null || _a === void 0 ? void 0 : _a.versions).toEqual([
+                { version: '3.2', name: 'Workbench 3.2' },
+                { version: '3.1' },
+            ]);
+            expect(JSON.stringify(scoped.scopedNav)).not.toContain('/workbench/3.1/setup');
+            expect(JSON.stringify(scoped.scopedNav)).not.toContain('external-9.9');
+        });
+        it('leaves the active product and jump maps unchanged when enabled', () => {
+            const scoped = getScopedNavForPath({ decoratedNav: productNav, currentPath });
+            const withMetadata = getScopedNavForPath({
+                decoratedNav: productNav,
+                currentPath,
+                includeProductVersionMetadata: true,
+            });
+            expect(findProduct(withMetadata.scopedNav, 'Model Serving')).toEqual(findProduct(scoped.scopedNav, 'Model Serving'));
+            expect(withMetadata.firstHrefInVersion).toEqual(scoped.firstHrefInVersion);
+            expect(withMetadata.firstHrefInLanguage).toEqual(scoped.firstHrefInLanguage);
+            expect(withMetadata.currentVersion).toBe(scoped.currentVersion);
+        });
+        it('filters identically to the full nav for every path when enabled', () => {
+            assertInvariantForEveryPath(multiDivisionNav, true);
+            assertInvariantForEveryPath(decoratedNavigationConfig, true);
+        });
+        it('changes nothing but the added metadata for every path', () => {
+            const paths = getAllPathsInDecoratedNav(productNav);
+            expect(paths.length).toBeGreaterThan(0);
+            for (const path of paths) {
+                const currentPath = `/${path.replace(/^\//, '')}`;
+                const scopedOff = getScopedNavForPath({ decoratedNav: productNav, currentPath });
+                const scopedOn = getScopedNavForPath({
+                    decoratedNav: productNav,
+                    currentPath,
+                    includeProductVersionMetadata: true,
+                });
+                expect(stripMetadataVersions(scopedOn.scopedNav), currentPath).toEqual(scopedOff.scopedNav);
+                expect(scopedOn.firstHrefInVersion, currentPath).toEqual(scopedOff.firstHrefInVersion);
+                expect(scopedOn.firstHrefInLanguage, currentPath).toEqual(scopedOff.firstHrefInLanguage);
+                expect(scopedOn.currentVersion, currentPath).toBe(scopedOff.currentVersion);
+                expect(scopedOn.currentLanguage, currentPath).toBe(scopedOff.currentLanguage);
+                const filteredOff = filterWith(scopedOff.scopedNav, currentPath, scopedOff.currentVersion, scopedOff.currentLanguage);
+                const filteredOn = filterWith(scopedOn.scopedNav, currentPath, scopedOn.currentVersion, scopedOn.currentLanguage);
+                expect(divisionSummary(filteredOn), currentPath).toEqual(divisionSummary(filteredOff));
+                expect(filteredOn.groupsOrPages, currentPath).toEqual(filteredOff.groupsOrPages);
+                expect(mapHrefs(filteredOn.firstHrefInVersion), currentPath).toEqual(mapHrefs(filteredOff.firstHrefInVersion));
+            }
+        });
+    });
 });
+function stripMetadataVersions(value) {
+    if (Array.isArray(value))
+        return value.map(stripMetadataVersions);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const entries = Object.entries(value).flatMap(([key, entry]) => {
+        if (key === 'versions' &&
+            Array.isArray(entry) &&
+            entry.every((version) => typeof version === 'object' &&
+                version !== null &&
+                !('pages' in version) &&
+                !('groups' in version) &&
+                !('href' in version))) {
+            return [];
+        }
+        return [[key, stripMetadataVersions(entry)]];
+    });
+    return Object.fromEntries(entries);
+}

package/dist/navigation/scopeNavToPath.d.ts

@@ -10,9 +10,10 @@ export type ScopedNavForPath = {
     currentVersion: string | undefined;
     currentLanguage: LocaleType | undefined;
 };
-export declare function getScopedNavForPath({ decoratedNav, currentPath, userGroups, isPreview, }: {
+export declare function getScopedNavForPath({ decoratedNav, currentPath, userGroups, isPreview, includeProductVersionMetadata, }: {
     decoratedNav: DecoratedNavigationConfig;
     currentPath: string;
     userGroups?: Set<string>;
     isPreview?: boolean;
+    includeProductVersionMetadata?: boolean;
 }): ScopedNavForPath;

package/dist/navigation/scopeNavToPath.js

@@ -357,6 +357,40 @@ function scopeDivisionArray(entries, key, ctx) {
         return stubDivision(entry, key, ctx);
     });
 }
+function collectProductVersionMetadata(node, out, seen) {
+    if (Array.isArray(node)) {
+        for (const entry of node) {
+            collectProductVersionMetadata(entry, out, seen);
+        }
+        return;
+    }
+    if (!isNavNode(node))
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        // versions under a nested product belong to that product, and global
+        // holds external links never attributed to a product by the consumer
+        if (key === 'products' || key === 'global')
+            continue;
+        if (key === 'versions' && Array.isArray(value)) {
+            for (const version of value) {
+                if (!isNavNode(version))
+                    continue;
+                if (typeof version.version !== 'string' || version.hidden === true)
+                    continue;
+                if (seen.has(version.version))
+                    continue;
+                seen.add(version.version);
+                const metadata = { version: version.version };
+                if (typeof version.name === 'string')
+                    metadata.name = version.name;
+                out.push(metadata);
+            }
+        }
+        if (Array.isArray(value) || isNavNode(value)) {
+            collectProductVersionMetadata(value, out, seen);
+        }
+    }
+}
 function stubProduct(product, ctx) {
     if (typeof product.href === 'string')
         return product;
@@ -373,6 +407,14 @@ function stubProduct(product, ctx) {
             stub[entryKey] = value;
         }
     }
+    if (ctx.includeProductVersionMetadata) {
+        const versionMetadata = [];
+        collectProductVersionMetadata(product, versionMetadata, new Set());
+        // pageless version entries so the search version filter can list a
+        // non-active product's versions; invisible to sidebar/dict consumers
+        if (versionMetadata.length)
+            stub.versions = versionMetadata;
+    }
     stub.pages = target.isRaw
         ? [target.href]
         : [makeStubPage(typeof product.product === 'string' ? product.product : '', target)];
@@ -433,7 +475,7 @@ export function scopeDocsConfigNavToPath(docsConfig, currentPath) {
         // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
         navigation: scopeNode(docsConfig.navigation, { currentPath }) });
 }
-export function getScopedNavForPath({ decoratedNav, currentPath, userGroups = new Set(), isPreview = false, }) {
+export function getScopedNavForPath({ decoratedNav, currentPath, userGroups = new Set(), isPreview = false, includeProductVersionMetadata = false, }) {
     var _a, _b, _c, _d, _e, _f, _g, _h;
     const containingProductNames = new Set();
     collectContainingProductNames(
@@ -489,6 +531,7 @@ export function getScopedNavForPath({ decoratedNav, currentPath, userGroups = ne
         userGroups,
         isPreview,
         skipVersionLanguageStubs: productAmbiguous,
+        includeProductVersionMetadata,
     }
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- structural nav traversal over the zod union types
     );

package/dist/rss/index.js

@@ -1,6 +1,7 @@
 import slugify from '@sindresorhus/slugify';
 import { stringifyTree } from '../mdx/index.js';
 import { getArrayExpressionStringProperties, getObjectExpressionStringProperty, } from '../mdx/utils.js';
+import { safeCleanHeadingId } from '../slugify.js';
 export const isFrontmatter = (node) => {
     return (node === null || node === void 0 ? void 0 : node.type) === 'yaml';
 };
@@ -85,6 +86,17 @@ export const getRssPropsData = (updateComponent) => {
     const description = getObjectExpressionStringProperty('description', rssData);
     return { rssTitle: title, rssDescription: description };
 };
+const getUpdateAnchorId = (updateComponent) => {
+    const idAttribute = updateComponent.attributes.find((attribute) => attribute.type === 'mdxJsxAttribute' &&
+        attribute.name === 'id' &&
+        typeof attribute.value === 'string');
+    if (typeof (idAttribute === null || idAttribute === void 0 ? void 0 : idAttribute.value) !== 'string')
+        return undefined;
+    // Match the page's id pipeline (Update.tsx uses safeCleanHeadingId) so feed
+    // fragment links point at the same DOM id the page renders; the RSS pipeline
+    // never runs the ToC plugin, so the cleaning must happen here.
+    return safeCleanHeadingId(idAttribute.value) || undefined;
+};
 export const getUpdateTitle = (updateComponent) => {
     var _a;
     const attributes = updateComponent.attributes;
@@ -313,7 +325,7 @@ export const processUpdatePerNode = ({ updateNode, date, title, description, })
         return [];
     }
     const rssTitle = title || label;
-    const anchor = slugify(label);
+    const anchor = getUpdateAnchorId(updateNode) || slugify(label);
     const categories = getTags(updateNode);
     const contentNodes = updateNode.children.filter((child) => isNormalMarkdown(child));
     const contentString = stringifyTreeForRSS({