feat: add breadcrumbs option to frontmatter and implement showBreadcrumbs logic

Author: onmax

docs/vitepress-theme/frontmatter.md

@@ -30,6 +30,7 @@ The Nimiq Vitepress theme supports the following frontmatter options:
 | ------------------ | ------------------ | ----------------------------------------------- | -------------------------------------------------------- |
 | `layout`           | `'home' \| 'docs'` | `'docs'`                                        | Layout type to use for the page                          |
 | `sidebar`          | `boolean`          | `true` for docs layout                          | Whether to show the sidebar                              |
+| `breadcrumbs`      | `boolean`          | `true` for docs layout, `false` for home layout | Whether to show the breadcrumbs navigation               |
 | `outline`          | `boolean`          | `true` if headings exist                        | Whether to show the outline (table of contents)          |
 | `secondarySidebar` | `boolean`          | `true` for docs layout, `false` for home layout | Whether to show the secondary sidebar                    |
 | `widget`           | `boolean`          | `true` for docs layout, `false` for home layout | Whether to show the widget area in the secondary sidebar |

packages/nimiq-vitepress-theme/src/composables/__tests__/useBreadcrumbs.test.ts

@@ -1,5 +1,5 @@
 import type { Breadcrumb } from '../useBreadcrumbs'
-import { useRoute } from 'vitepress'
+import { useData, useRoute } from 'vitepress'
 import { describe, expect, it, vi } from 'vitest'
 import { computed } from 'vue'
 import { useBreadcrumbs } from '../useBreadcrumbs'
@@ -8,6 +8,7 @@ import { useCurrentModule } from '../useCurrentModule'
 // Mock dependencies
 vi.mock('vitepress', () => ({
   useRoute: vi.fn(),
+  useData: vi.fn(),
   withBase: (p: string) => `/base${p}`,
 }))
 vi.mock('../useCurrentModule', () => ({
@@ -32,6 +33,7 @@ describe('useBreadcrumbs', () => {
       currentDocModule: computed(() => moduleData),
     })
     ;(useRoute as any).mockReturnValue({ path: '/base/page1/' })
+    ;(useData as any).mockReturnValue({ frontmatter: computed(() => ({})) })
 
     const { breadcrumbs } = useBreadcrumbs()
     expect(breadcrumbs.value).toEqual<Breadcrumb[]>([
@@ -63,6 +65,7 @@ describe('useBreadcrumbs', () => {
       currentDocModule: computed(() => moduleData),
     })
     ;(useRoute as any).mockReturnValue({ path: '/base/child/' })
+    ;(useData as any).mockReturnValue({ frontmatter: computed(() => ({})) })
 
     const { breadcrumbs } = useBreadcrumbs()
     expect(breadcrumbs.value).toEqual<Breadcrumb[]>([
@@ -72,4 +75,52 @@ describe('useBreadcrumbs', () => {
       { text: 'Child' },
     ])
   })
+
+  it('should show breadcrumbs by default for docs layout', () => {
+    const moduleData = {
+      text: 'Module',
+      subpath: 'mod',
+      sidebar: [],
+    }
+    ;(useCurrentModule as any).mockReturnValue({
+      currentDocModule: computed(() => moduleData),
+    })
+    ;(useRoute as any).mockReturnValue({ path: '/base/test/' })
+    ;(useData as any).mockReturnValue({ frontmatter: computed(() => ({})) })
+
+    const { showBreadcrumbs } = useBreadcrumbs()
+    expect(showBreadcrumbs.value).toBe(true)
+  })
+
+  it('should hide breadcrumbs by default for home layout', () => {
+    const moduleData = {
+      text: 'Module',
+      subpath: 'mod',
+      sidebar: [],
+    }
+    ;(useCurrentModule as any).mockReturnValue({
+      currentDocModule: computed(() => moduleData),
+    })
+    ;(useRoute as any).mockReturnValue({ path: '/base/test/' })
+    ;(useData as any).mockReturnValue({ frontmatter: computed(() => ({ layout: 'home' })) })
+
+    const { showBreadcrumbs } = useBreadcrumbs()
+    expect(showBreadcrumbs.value).toBe(false)
+  })
+
+  it('should respect explicit breadcrumbs frontmatter setting', () => {
+    const moduleData = {
+      text: 'Module',
+      subpath: 'mod',
+      sidebar: [],
+    }
+    ;(useCurrentModule as any).mockReturnValue({
+      currentDocModule: computed(() => moduleData),
+    })
+    ;(useRoute as any).mockReturnValue({ path: '/base/test/' })
+    ;(useData as any).mockReturnValue({ frontmatter: computed(() => ({ breadcrumbs: false })) })
+
+    const { showBreadcrumbs } = useBreadcrumbs()
+    expect(showBreadcrumbs.value).toBe(false)
+  })
 })

packages/nimiq-vitepress-theme/src/composables/useBreadcrumbs.ts

@@ -1,4 +1,4 @@
-import { useRoute, withBase } from 'vitepress'
+import { useData, useRoute, withBase } from 'vitepress'
 import { computed } from 'vue'
 import { useCurrentModule } from './useCurrentModule'
 
@@ -11,6 +11,15 @@ export interface Breadcrumb {
 export function useBreadcrumbs() {
   const { currentDocModule } = useCurrentModule()
   const route = useRoute()
+  const { frontmatter } = useData()
+
+  const showBreadcrumbs = computed(() => {
+    if (frontmatter.value.breadcrumbs !== undefined)
+      return frontmatter.value.breadcrumbs
+    if (frontmatter.value.layout === 'home')
+      return false
+    return true
+  })
 
   const breadcrumbs = computed<Breadcrumb[]>(() => {
     const items: Breadcrumb[] = []
@@ -61,5 +70,6 @@ export function useBreadcrumbs() {
 
   return {
     breadcrumbs,
+    showBreadcrumbs,
   }
 }

packages/nimiq-vitepress-theme/src/layout/PageContent.vue

@@ -12,7 +12,7 @@ import '../assets/typography.css'
 import '../assets/github-callouts.css'
 
 const { page } = useData<NimiqVitepressThemeConfig>()
-const { breadcrumbs } = useBreadcrumbs()
+const { breadcrumbs, showBreadcrumbs } = useBreadcrumbs()
 
 const { secondarySidebar } = useSecondarySidebar()
 
@@ -31,7 +31,7 @@ function useEditUrl(relativePath: string): string {
 <template>
   <div :class="secondarySidebar ? 'f-pr-xs f-pl-xl' : 'f-px-xl'" f-pt-sm f="$px $px-min-48 $px-max-72" f-pb-sm flex="~ gap-16" relative h-full>
     <div flex="~ col" h-full flex-1 w="[calc(100vw-2*var(--nq-sidebar-width)-2*var(--f-px))]">
-      <ul px-32 f-pb-lg flex="~ items-center gap-12">
+      <ul v-if="showBreadcrumbs" px-32 f-pb-lg flex="~ items-center gap-12">
         <li v-for="({ text, icon }, i) in breadcrumbs" :key="text" contents w-max>
           <div v-if="icon" :class="icon" />
           <span nq-label f-text-2xs w-max>{{ text }}</span>