@sit-onyx/nuxt-docs 0.2.0-dev-20260112121557 → 0.2.0-dev-20260113092604

package/app/components/PackageManagerCodeTabs.vue

@@ -29,10 +29,20 @@ const tabs = computed(() => {
 
   return tabs.filter((tab) => tab.code);
 });
+
+const getMDCValue = (code: string, language: string) => {
+  return `
+\`\`\`${language}
+${code}
+\`\`\`
+`;
+};
 </script>
 
 <template>
   <OnyxUnstableCodeTabs v-model="selectedTab">
-    <OnyxUnstableCodeTab v-for="tab in tabs" v-bind="tab" :key="tab.value" :label="tab.value" />
+    <OnyxUnstableCodeTab v-for="tab in tabs" v-bind="tab" :key="tab.value" :label="tab.value">
+      <MDC :value="getMDCValue(tab.code, tab.language)" />
+    </OnyxUnstableCodeTab>
   </OnyxUnstableCodeTabs>
 </template>

package/app/composables/useSidebarNavigation.ts

@@ -49,7 +49,10 @@ export const useSidebarNavigation = async () => {
     },
   );
 
-  const navigation = computed(() => {
+  /**
+   * All navigation items.
+   */
+  const allItems = computed(() => {
     // map the items from "@nuxt/content" to our custom data scheme for better type support
     const mapItem = (item: ContentNavigationItem): SidebarNavigationItem => {
       return {
@@ -61,18 +64,30 @@ export const useSidebarNavigation = async () => {
       };
     };
 
-    const items = data.value.map(mapItem);
+    return data.value.map(mapItem);
+  });
 
+  const navigation = computed(() => {
     // support multiple sidebars / roots so different pages can have their own sub-sidebar
-    const root = findDeepestRoot(items, route.path);
-    if (!root) return items;
+    const root = findDeepestRoot(allItems.value, route.path);
+    if (!root) return allItems.value;
     return root.children ?? [root];
   });
 
-  const findDeepestRoot = (
+  /**
+   * Finds the "previous root" (parent root) for the currently active route within the navigation tree.
+   * Useful to e.g. display a back button to traverse up the navigation tree.
+   */
+  const previousRootItem = computed(() => findPreviousRootItem(allItems.value, route.path));
+
+  /**
+   * Recursively searches for the deepest item marked as a sidebar root
+   * that contains the `currentPath` within its subtree.
+   */
+  function findDeepestRoot(
     items: SidebarNavigationItem[],
-    activePath: string,
-  ): SidebarNavigationItem | undefined => {
+    currentPath: string,
+  ): SidebarNavigationItem | undefined {
     /** Helper function to check if a path exists anywhere in a node's subtree */
     const containsPath = (node: SidebarNavigationItem, path: string): boolean => {
       if (node.path === path) return true;
@@ -82,16 +97,68 @@ export const useSidebarNavigation = async () => {
     for (const item of items) {
       // 1. Check children first (to find something deeper)
       if (item.children) {
-        const deeperResult = findDeepestRoot(item.children, activePath);
+        const deeperResult = findDeepestRoot(item.children, currentPath);
         if (deeperResult) return deeperResult;
       }
 
       // 2. If no deeper root was found, check if this current node is a match
-      if (item.sidebar?.root && containsPath(item, activePath)) {
+      if (item.sidebar?.root && containsPath(item, currentPath)) {
         return item;
       }
     }
-  };
+  }
+
+  /**
+   * Finds the "previous root" (parent root) for a given current path within the navigation tree.
+   * - If depth >= 2: returns the previous root item
+   * - If depth == 1: returns the first item in the navigation (typically a "Home" item)
+   * - If depth == 0: returns undefined (no back button needed)
+   *
+   * @param items - The full navigation array
+   * @param currentPath - The path of the currently active page
+   * @param rootStack - (Internal) Accumulator for recursion
+   */
+  function findPreviousRootItem(
+    items: SidebarNavigationItem[],
+    currentPath: string,
+    rootStack: SidebarNavigationItem[] = [],
+  ): SidebarNavigationItem | undefined {
+    for (const item of items) {
+      const isRoot = item.sidebar?.root === true;
+
+      // 1. update stack: if item is a root, add to ancestry
+      const nextRootStack = isRoot ? [...rootStack, item] : rootStack;
+
+      // 2. check if item is the active item
+      if (item.path === currentPath) {
+        // case A: deep nesting (e.g. Stack: [Home -> Examples -> Example 1])
+        // return the previous root (Examples)
+        if (nextRootStack.length >= 2) {
+          return nextRootStack[nextRootStack.length - 2];
+        }
+
+        // case B: first level of nesting (e.g. Stack: [Home])
+        // return the first item in the navigation (typically a "Home" item)
+        if (nextRootStack.length === 1) {
+          // if the root is part of the highest navigation level, we want to return undefined
+          // (so no back button is shown), otherwise we return the first available item
+          const isSameLevel = allItems.value.some((item) => item.path === nextRootStack[0]?.path);
+          return isSameLevel ? undefined : allItems.value[0];
+        }
+
+        // case C: no nested roots active
+        return undefined;
+      }
+
+      // 3. recursive step for children
+      if (item.children) {
+        const result = findPreviousRootItem(item.children, currentPath, nextRootStack);
+        if (result !== undefined) {
+          return result;
+        }
+      }
+    }
+  }
 
-  return { navigation };
+  return { navigation, allItems, previousRootItem };
 };

package/app/layouts/sidebar.vue

@@ -1,4 +1,5 @@
 <script lang="ts" setup>
+import { iconArrowSmallLeft } from "@sit-onyx/icons";
 import type { OnyxPageLayoutProps, OnyxSidebarProps } from "sit-onyx";
 import type { SidebarNavigationItem } from "../composables/useSidebarNavigation.js";
 
@@ -27,6 +28,7 @@ const slots = defineSlots<{
   sidebarBody?(props: { items: SidebarNavigationItem[] }): unknown;
   /**
    * Optionally override the sidebar header content.
+   * By default, a back button will be shown if a nested sidebar root is opened.
    */
   sidebarHeader?(): unknown;
   /**
@@ -35,7 +37,7 @@ const slots = defineSlots<{
   sidebarFooter?(): unknown;
 }>();
 
-const { navigation } = await useSidebarNavigation();
+const { navigation, previousRootItem } = await useSidebarNavigation();
 </script>
 
 <template>
@@ -46,8 +48,18 @@ const { navigation } = await useSidebarNavigation();
         v-bind="props.sidebar"
         :label="$t('onyx.navigation.navigationHeadline')"
       >
-        <template v-if="slots.sidebarHeader" #header>
-          <slot name="sidebarHeader"> </slot>
+        <template v-if="slots.sidebarHeader || previousRootItem" #header>
+          <slot name="sidebarHeader">
+            <OnyxButton
+              v-if="previousRootItem"
+              class="sidebar__back"
+              :label="$t('onyx.back')"
+              color="neutral"
+              mode="plain"
+              :link="previousRootItem.path"
+              :icon="iconArrowSmallLeft"
+            />
+          </slot>
         </template>
 
         <slot name="sidebarBody" :items="navigation">
@@ -85,5 +97,10 @@ const { navigation } = await useSidebarNavigation();
   &__empty {
     max-width: 100%;
   }
+
+  &__back {
+    width: 100%;
+    justify-content: flex-start;
+  }
 }
 </style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sit-onyx/nuxt-docs",
-  "version": "0.2.0-dev-20260112121557",
+  "version": "0.2.0-dev-20260113092604",
   "description": "Nuxt layer/template for creating documentations with the onyx design system",
   "type": "module",
   "author": "Schwarz IT KG",
@@ -28,12 +28,12 @@
     "@nuxt/content": ">= 3",
     "@nuxt/image": ">= 1",
     "@nuxtjs/color-mode": ">= 4",
-    "@nuxtjs/mdc": ">= 0.13.0",
+    "@nuxtjs/mdc": ">= 0.17.2",
     "@nuxtjs/i18n": ">= 10",
     "sass-embedded": ">= 1",
-    "@sit-onyx/icons": "^1.4.0-dev-20260112121557",
+    "@sit-onyx/icons": "^1.4.0-dev-20260113092604",
     "@sit-onyx/nuxt": "^1.0.1",
-    "sit-onyx": "^1.6.0-dev-20260112121557"
+    "sit-onyx": "^1.6.0-dev-20260113092604"
   },
   "devDependencies": {
     "@fontsource-variable/source-code-pro": ">= 5",
@@ -42,17 +42,17 @@
     "@nuxt/image": ">= 1",
     "@nuxt/test-utils": "^3.23.0",
     "@nuxtjs/color-mode": ">= 4",
-    "@nuxtjs/mdc": ">= 0.13.0",
+    "@nuxtjs/mdc": ">= 0.17.2",
     "@playwright/experimental-ct-vue": "1.57.0",
     "@playwright/test": "1.57.0",
     "nuxt": "4.2.2",
     "sass-embedded": "1.97.2",
     "typescript": "5.9.3",
     "vue": "3.5.26",
-    "@sit-onyx/icons": "^1.4.0-dev-20260112121557",
+    "@sit-onyx/icons": "^1.4.0-dev-20260113092604",
     "@sit-onyx/nuxt": "^1.0.1",
     "@sit-onyx/shared": "^0.1.0",
-    "sit-onyx": "^1.6.0-dev-20260112121557"
+    "sit-onyx": "^1.6.0-dev-20260113092604"
   },
   "scripts": {
     "dev": "pnpm dev:prepare && nuxi dev playground",