diff --git a/docs/developer_docs/components/design-system/index.mdx b/docs/developer_docs/components/design-system/index.mdx
index 6f856ca6187..03eb7f824fb 100644
--- a/docs/developer_docs/components/design-system/index.mdx
+++ b/docs/developer_docs/components/design-system/index.mdx
@@ -29,10 +29,10 @@ sidebar_position: 1
 
 ## Components
 
-- [DropdownContainer](./dropdowncontainer.md)
-- [Flex](./flex.md)
-- [Grid](./grid.md)
-- [Layout](./layout.md)
-- [MetadataBar](./metadatabar.md)
-- [Space](./space.md)
-- [Table](./table.md)
+- [DropdownContainer](./dropdowncontainer.mdx)
+- [Flex](./flex.mdx)
+- [Grid](./grid.mdx)
+- [Layout](./layout.mdx)
+- [MetadataBar](./metadatabar.mdx)
+- [Space](./space.mdx)
+- [Table](./table.mdx)
diff --git a/docs/developer_docs/components/ui/index.mdx b/docs/developer_docs/components/ui/index.mdx
index f78260823a2..1bcc81edc15 100644
--- a/docs/developer_docs/components/ui/index.mdx
+++ b/docs/developer_docs/components/ui/index.mdx
@@ -29,49 +29,49 @@ sidebar_position: 1
 
 ## Components
 
-- [AutoComplete](./autocomplete.md)
-- [Avatar](./avatar.md)
-- [Badge](./badge.md)
-- [Breadcrumb](./breadcrumb.md)
-- [Button](./button.md)
-- [ButtonGroup](./buttongroup.md)
-- [CachedLabel](./cachedlabel.md)
-- [Card](./card.md)
-- [Checkbox](./checkbox.md)
-- [Collapse](./collapse.md)
-- [DatePicker](./datepicker.md)
-- [Divider](./divider.md)
-- [EditableTitle](./editabletitle.md)
-- [EmptyState](./emptystate.md)
-- [FaveStar](./favestar.md)
-- [IconButton](./iconbutton.md)
-- [Icons](./icons.md)
-- [IconTooltip](./icontooltip.md)
-- [InfoTooltip](./infotooltip.md)
-- [Input](./input.md)
-- [Label](./label.md)
-- [List](./list.md)
-- [ListViewCard](./listviewcard.md)
-- [Loading](./loading.md)
-- [Menu](./menu.md)
-- [Modal](./modal.md)
-- [ModalTrigger](./modaltrigger.md)
-- [Popover](./popover.md)
-- [ProgressBar](./progressbar.md)
-- [Radio](./radio.md)
-- [SafeMarkdown](./safemarkdown.md)
-- [Select](./select.md)
-- [Skeleton](./skeleton.md)
-- [Slider](./slider.md)
-- [Steps](./steps.md)
-- [Switch](./switch.md)
-- [TableCollection](./tablecollection.md)
-- [TableView](./tableview.md)
-- [Tabs](./tabs.md)
-- [Timer](./timer.md)
-- [Tooltip](./tooltip.md)
-- [Tree](./tree.md)
-- [TreeSelect](./treeselect.md)
-- [Typography](./typography.md)
-- [UnsavedChangesModal](./unsavedchangesmodal.md)
-- [Upload](./upload.md)
+- [AutoComplete](./autocomplete.mdx)
+- [Avatar](./avatar.mdx)
+- [Badge](./badge.mdx)
+- [Breadcrumb](./breadcrumb.mdx)
+- [Button](./button.mdx)
+- [ButtonGroup](./buttongroup.mdx)
+- [CachedLabel](./cachedlabel.mdx)
+- [Card](./card.mdx)
+- [Checkbox](./checkbox.mdx)
+- [Collapse](./collapse.mdx)
+- [DatePicker](./datepicker.mdx)
+- [Divider](./divider.mdx)
+- [EditableTitle](./editabletitle.mdx)
+- [EmptyState](./emptystate.mdx)
+- [FaveStar](./favestar.mdx)
+- [IconButton](./iconbutton.mdx)
+- [Icons](./icons.mdx)
+- [IconTooltip](./icontooltip.mdx)
+- [InfoTooltip](./infotooltip.mdx)
+- [Input](./input.mdx)
+- [Label](./label.mdx)
+- [List](./list.mdx)
+- [ListViewCard](./listviewcard.mdx)
+- [Loading](./loading.mdx)
+- [Menu](./menu.mdx)
+- [Modal](./modal.mdx)
+- [ModalTrigger](./modaltrigger.mdx)
+- [Popover](./popover.mdx)
+- [ProgressBar](./progressbar.mdx)
+- [Radio](./radio.mdx)
+- [SafeMarkdown](./safemarkdown.mdx)
+- [Select](./select.mdx)
+- [Skeleton](./skeleton.mdx)
+- [Slider](./slider.mdx)
+- [Steps](./steps.mdx)
+- [Switch](./switch.mdx)
+- [TableCollection](./tablecollection.mdx)
+- [TableView](./tableview.mdx)
+- [Tabs](./tabs.mdx)
+- [Timer](./timer.mdx)
+- [Tooltip](./tooltip.mdx)
+- [Tree](./tree.mdx)
+- [TreeSelect](./treeselect.mdx)
+- [Typography](./typography.mdx)
+- [UnsavedChangesModal](./unsavedchangesmodal.mdx)
+- [Upload](./upload.mdx)
diff --git a/docs/scripts/generate-superset-components.mjs b/docs/scripts/generate-superset-components.mjs
index c3ca472a26b..48e55855b5c 100644
--- a/docs/scripts/generate-superset-components.mjs
+++ b/docs/scripts/generate-superset-components.mjs
@@ -1260,13 +1260,15 @@ function generateCategoryIndex(category, components) {
   };
   const componentList = components
     .sort((a, b) => a.componentName.localeCompare(b.componentName))
-    // `.md` suffix on the relative link is required: Docusaurus only
-    // validates and rewrites *file-based* references (.md/.mdx). Bare
-    // relative paths bypass the file resolver and get emitted as raw
-    // HTML hrefs that the browser resolves against the current URL —
-    // which gives the wrong directory for trailing-slash routes and
-    // breaks SPA navigation. See docs/scripts/lint-docs-links.mjs.
-    .map(c => `- [${c.componentName}](./${c.componentName.toLowerCase()}.md)`)
+    // `.mdx` suffix matches the actual component page files emitted
+    // by this generator (see the MDX wrappers below). The extension
+    // is required: Docusaurus only validates and rewrites *file-based*
+    // references (.md/.mdx). Bare relative paths bypass the file
+    // resolver and get emitted as raw HTML hrefs that the browser
+    // resolves against the current URL — which gives the wrong
+    // directory for trailing-slash routes and breaks SPA navigation.
+    // See docs/scripts/lint-docs-links.mjs.
+    .map(c => `- [${c.componentName}](./${c.componentName.toLowerCase()}.mdx)`)
     .join('\n');
 
   return `---