UI5 · nnaydenow · Mar 12, 2026
diff --git a/packages/website/build-scripts/api-reference-generation/components.mjs b/packages/website/build-scripts/api-reference-generation/components.mjs
@@ -6,6 +6,92 @@ import { findDeclaration, realPackagesName } from "./manifest.mjs";
 
 const packages = ["main", "fiori", "compat", "ai"];
 
+/**
+ * Calculate the correct slug for a component based on its file path
+ * @param {string} filePath - Full path to the .mdx file
+ * @param {string} packageName - Package name (main, fiori, compat, ai)
+ * @param {string} componentName - Component name (filename without extension)
+ * @returns {string} - The calculated slug
+ */
+const calculateSlug = (filePath, packageName, componentName) => {
+    // Normalize path separators for cross-platform compatibility
+    const normalizedPath = filePath.replace(/\\/g, '/');
+
+    // Extract the path relative to _components_pages/<package>/
+    const packagePattern = new RegExp(`_components_pages/${packageName}/(.*)$`);
+    const match = normalizedPath.match(packagePattern);
+
+    if (!match) {
+        console.warn(`Warning: Could not extract relative path for ${filePath}`);
+        return null;
+    }
+
+    const relativeFromPackage = match[1];
+    const fileDir = path.dirname(relativeFromPackage);
+
+    // Determine depth:
+    // - "Component.mdx" (at package root) -> depth 0
+    // - "Component/Component.mdx" (in subdirectory) -> depth 1
+    const isInSubdirectory = fileDir !== '.';
+
+    if (packageName === "main") {
+        // Main package: URLs are /components/ComponentName
+        if (isInSubdirectory) {
+            // From main/Component/Component.mdx -> ../../Component
+            return `../../${componentName}`;
+        } else {
+            // From main/Component.mdx -> ../Component
+            return `../${componentName}`;
+        }
+    } else {
+        // Other packages (fiori, ai, compat): URLs are /components/<package>/ComponentName
+        if (isInSubdirectory) {
+            // From fiori/Component/Component.mdx -> ../Component
+            return `../${componentName}`;
+        } else {
+            // From fiori/Component.mdx -> ./Component
+            return `./${componentName}`;
+        }
+    }
+};
+
+/**
+ * Inject or update slug in frontmatter
+ * @param {string} fileContent - Original file content
+ * @param {string} slug - Calculated slug
+ * @returns {string} - Updated file content with correct slug
+ */
+const injectSlug = (fileContent, slug) => {
+    if (!slug) {
+        return fileContent;
+    }
+
+    // Check if frontmatter exists
+    const frontmatterMatch = fileContent.match(/^---\n([\s\S]*?)\n---/);
+
+    if (!frontmatterMatch) {
+        // No frontmatter - add it with slug
+        return `---\nslug: ${slug}\n---\n\n${fileContent}`;
+    }
+
+    const frontmatter = frontmatterMatch[1];
+    const slugMatch = frontmatter.match(/^slug:\s*(.+)$/m);
+
+    if (slugMatch) {
+        // Slug exists - replace it
+        const oldSlug = slugMatch[1].trim();
+        if (oldSlug !== slug) {
+            console.log(`  Updating slug: ${oldSlug} -> ${slug}`);
+        }
+        const updatedFrontmatter = frontmatter.replace(/^slug:\s*(.+)$/m, `slug: ${slug}`);
+        return fileContent.replace(frontmatterMatch[0], `---\n${updatedFrontmatter}\n---`);
+    } else {
+        // Frontmatter exists but no slug - add slug
+        const updatedFrontmatter = `slug: ${slug}\n${frontmatter}`;
+        return fileContent.replace(frontmatterMatch[0], `---\n${updatedFrontmatter}\n---`);
+    }
+};
+
 const generateComponents = (source = "./docs/_components_pages", level = 1) => {
     const sourcePath = path.resolve(source);
     const targetPath = source.replace("_components_pages", "components");
@@ -44,9 +130,14 @@ const generateComponents = (source = "./docs/_components_pages", level = 1) => {
             }
 
             if (packageName) {
-                const fileContent = fs.readFileSync(path.join(sourcePath, file), { encoding: "utf-8" });
+                const filePath = path.join(sourcePath, file);
+                let fileContent = fs.readFileSync(filePath, { encoding: "utf-8" });
                 const declaration = findDeclaration({ package: realPackagesName(packageName), name: fileName })
 
+                // Calculate and inject correct slug
+                const calculatedSlug = calculateSlug(filePath, packageName, fileName);
+                fileContent = injectSlug(fileContent, calculatedSlug);
+
                 fs.writeFileSync(path.join(targetPath, `${fileName}.mdx`), parseComponentDeclaration(declaration, fileContent))
             }
         }

diff --git a/packages/website/docs/_components_pages/ai/Button/Button.mdx b/packages/website/docs/_components_pages/ai/Button/Button.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../Button
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/packages/website/docs/_components_pages/ai/Button/ButtonState.mdx b/packages/website/docs/_components_pages/ai/Button/ButtonState.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../ButtonState
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/packages/website/docs/_components_pages/compat/Table/Table.mdx b/packages/website/docs/_components_pages/compat/Table/Table.mdx
@@ -1,7 +1,3 @@
----
-slug: ../Table
----
-
 import Basic from "../../../_samples/compat/Table/Basic/Basic.md";
 import ActiveRows from "../../../_samples/compat/Table/ActiveRows/ActiveRows.md";
 import Grouping from "../../../_samples/compat/Table/Grouping/Grouping.md";

diff --git a/packages/website/docs/_components_pages/compat/Table/TableCell.mdx b/packages/website/docs/_components_pages/compat/Table/TableCell.mdx
@@ -1,7 +1,3 @@
----
-slug: ../TableCell
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/compat/Table/TableColumn.mdx b/packages/website/docs/_components_pages/compat/Table/TableColumn.mdx
@@ -1,7 +1,3 @@
----
-slug: ../TableColumn
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/compat/Table/TableGroupRow.mdx b/packages/website/docs/_components_pages/compat/Table/TableGroupRow.mdx
@@ -1,7 +1,3 @@
----
-slug: ../TableGroupRow
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/compat/Table/TableRow.mdx b/packages/website/docs/_components_pages/compat/Table/TableRow.mdx
@@ -1,7 +1,3 @@
----
-slug: ../TableRow
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/fiori/DynamicPage/DynamicPage.mdx b/packages/website/docs/_components_pages/fiori/DynamicPage/DynamicPage.mdx
@@ -1,7 +1,3 @@
----
-slug: ../DynamicPage
----
-
 import Basic from "../../../_samples/fiori/DynamicPage/Basic/Basic.md";
 
 <%COMPONENT_OVERVIEW%>

diff --git a/packages/website/docs/_components_pages/fiori/DynamicPage/DynamicPageHeader.mdx b/packages/website/docs/_components_pages/fiori/DynamicPage/DynamicPageHeader.mdx
@@ -1,7 +1,3 @@
----
-slug: ../DynamicPageHeader
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/fiori/DynamicPage/DynamicPageTitle.mdx b/packages/website/docs/_components_pages/fiori/DynamicPage/DynamicPageTitle.mdx
@@ -1,7 +1,3 @@
----
-slug: ../DynamicPageTitle
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/fiori/MediaGallery/MediaGalleryItem.mdx b/packages/website/docs/_components_pages/fiori/MediaGallery/MediaGalleryItem.mdx
@@ -1,7 +1,3 @@
----
-slug: ../MediaGalleryItem
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/...ite/docs/_components_pages/fiori/NotificationList/NotificationListGroupItem.mdx b/...ite/docs/_components_pages/fiori/NotificationList/NotificationListGroupItem.mdx
@@ -1,7 +1,3 @@
----
-slug: ../NotificationListGroupItem
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/.../website/docs/_components_pages/fiori/NotificationList/NotificationListItem.mdx b/.../website/docs/_components_pages/fiori/NotificationList/NotificationListItem.mdx
@@ -1,7 +1,3 @@
----
-slug: ../NotificationListItem
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/fiori/ProductSwitch/ProductSwitchItem.mdx b/packages/website/docs/_components_pages/fiori/ProductSwitch/ProductSwitchItem.mdx
@@ -1,7 +1,3 @@
----
-slug: ../ProductSwitchItem
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/fiori/Search/SearchItem.mdx b/packages/website/docs/_components_pages/fiori/Search/SearchItem.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../SearchItem
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/packages/website/docs/_components_pages/fiori/Search/SearchItemGroup.mdx b/packages/website/docs/_components_pages/fiori/Search/SearchItemGroup.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../SearchItemGroup
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/packages/website/docs/_components_pages/fiori/Search/SearchMessageArea.mdx b/packages/website/docs/_components_pages/fiori/Search/SearchMessageArea.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../SearchMessageArea
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/packages/website/docs/_components_pages/fiori/Search/SearchScope.mdx b/packages/website/docs/_components_pages/fiori/Search/SearchScope.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../SearchScope
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/packages/website/docs/_components_pages/fiori/ShellBar/ShellBarBranding.mdx b/packages/website/docs/_components_pages/fiori/ShellBar/ShellBarBranding.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../ShellBarBranding
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/packages/website/docs/_components_pages/fiori/ShellBar/ShellBarItem.mdx b/packages/website/docs/_components_pages/fiori/ShellBar/ShellBarItem.mdx
@@ -1,7 +1,3 @@
----
-slug: ../ShellBarItem
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/fiori/ShellBar/ShellBarSearch.mdx b/packages/website/docs/_components_pages/fiori/ShellBar/ShellBarSearch.mdx
@@ -1,7 +1,3 @@
----
-slug: ../ShellBarSearch
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/fiori/ShellBar/ShellBarSpacer.mdx b/packages/website/docs/_components_pages/fiori/ShellBar/ShellBarSpacer.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../ShellBarSpacer
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/...ges/website/docs/_components_pages/fiori/SideNavigation/SideNavigationGroup.mdx b/...ges/website/docs/_components_pages/fiori/SideNavigation/SideNavigationGroup.mdx
@@ -1,7 +1,3 @@
----
-slug: ../SideNavigationGroup
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/...ages/website/docs/_components_pages/fiori/SideNavigation/SideNavigationItem.mdx b/...ages/website/docs/_components_pages/fiori/SideNavigation/SideNavigationItem.mdx
@@ -1,7 +1,3 @@
----
-slug: ../SideNavigationItem
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/...s/website/docs/_components_pages/fiori/SideNavigation/SideNavigationSubItem.mdx b/...s/website/docs/_components_pages/fiori/SideNavigation/SideNavigationSubItem.mdx
@@ -1,7 +1,3 @@
----
-slug: ../SideNavigationSubItem
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/fiori/Timeline/TimelineGroupItem.mdx b/packages/website/docs/_components_pages/fiori/Timeline/TimelineGroupItem.mdx
@@ -1,7 +1,3 @@
----
-slug: ../TimelineGroupItem
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/fiori/Timeline/TimelineItem.mdx b/packages/website/docs/_components_pages/fiori/Timeline/TimelineItem.mdx
@@ -1,7 +1,3 @@
----
-slug: ../TimelineItem
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/.../website/docs/_components_pages/fiori/UploadCollection/UploadCollectionItem.mdx b/.../website/docs/_components_pages/fiori/UploadCollection/UploadCollectionItem.mdx
@@ -1,7 +1,3 @@
----
-slug: ../UploadCollectionItem
----
-
 <%COMPONENT_OVERVIEW%>
 
 <%COMPONENT_METADATA%>
diff --git a/packages/website/docs/_components_pages/fiori/UserMenu/UserMenu.mdx b/packages/website/docs/_components_pages/fiori/UserMenu/UserMenu.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserMenu
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/packages/website/docs/_components_pages/fiori/UserMenu/UserMenuAccount.mdx b/packages/website/docs/_components_pages/fiori/UserMenu/UserMenuAccount.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserMenuAccount
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/packages/website/docs/_components_pages/fiori/UserMenu/UserMenuItem.mdx b/packages/website/docs/_components_pages/fiori/UserMenu/UserMenuItem.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserMenuItem
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/packages/website/docs/_components_pages/fiori/UserMenu/UserMenuItemGroup.mdx b/packages/website/docs/_components_pages/fiori/UserMenu/UserMenuItemGroup.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserMenuItemGroup
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/...ite/docs/_components_pages/fiori/UserSettingsDialog/UserSettingsAccountView.mdx b/...ite/docs/_components_pages/fiori/UserSettingsDialog/UserSettingsAccountView.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserSettingsAccountView
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/.../docs/_components_pages/fiori/UserSettingsDialog/UserSettingsAppearanceView.mdx b/.../docs/_components_pages/fiori/UserSettingsDialog/UserSettingsAppearanceView.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserSettingsAppearanceView
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/.../_components_pages/fiori/UserSettingsDialog/UserSettingsAppearanceViewGroup.mdx b/.../_components_pages/fiori/UserSettingsDialog/UserSettingsAppearanceViewGroup.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserSettingsAppearanceViewGroup
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/...s/_components_pages/fiori/UserSettingsDialog/UserSettingsAppearanceViewItem.mdx b/...s/_components_pages/fiori/UserSettingsDialog/UserSettingsAppearanceViewItem.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserSettingsAppearanceViewItem
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/.../website/docs/_components_pages/fiori/UserSettingsDialog/UserSettingsDialog.mdx b/.../website/docs/_components_pages/fiori/UserSettingsDialog/UserSettingsDialog.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserSettingsDialog
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/...es/website/docs/_components_pages/fiori/UserSettingsDialog/UserSettingsItem.mdx b/...es/website/docs/_components_pages/fiori/UserSettingsDialog/UserSettingsItem.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserSettingsItem
 sidebar_class_name: newComponentBadge
 ---
 

diff --git a/...es/website/docs/_components_pages/fiori/UserSettingsDialog/UserSettingsView.mdx b/...es/website/docs/_components_pages/fiori/UserSettingsDialog/UserSettingsView.mdx
@@ -1,5 +1,4 @@
 ---
-slug: ../UserSettingsView
 sidebar_class_name: newComponentBadge
 ---