0
# Navigation
1

2
Navigation utilities for creating hierarchical structures, breadcrumbs, and finding related content based on file-system organization and content relationships.
3

4
## Capabilities
5

6
### Find Page Breadcrumb
7

8
Generates breadcrumb trail from navigation tree for a given path.
9

10
```typescript { .api }
11
/**
12
 * Finds breadcrumb trail for given path in navigation tree
13
 * @param navigation - Navigation tree to search in
14
 * @param path - Path to find breadcrumbs for
15
 * @param options - Configuration options for breadcrumb generation
16
 * @returns Array of navigation items forming the breadcrumb trail
17
 */
18
function findPageBreadcrumb(
19
  navigation?: ContentNavigationItem[],
20
  path?: string,
21
  options?: FindPageBreadcrumbOptions
22
): ContentNavigationItem[];
23

24
interface FindPageBreadcrumbOptions {
25
  /** Include current page in breadcrumb trail */
26
  current?: boolean;
27
  /** Treat index pages as child pages */
28
  indexAsChild?: boolean;
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
import { findPageBreadcrumb } from '@nuxt/content/utils';
36

37
// Generate breadcrumb for current page
38
const navigation = await queryCollectionNavigation('docs');
39
const breadcrumb = findPageBreadcrumb(navigation, '/docs/guide/getting-started');
40

41
// Include current page in breadcrumb
42
const breadcrumbWithCurrent = findPageBreadcrumb(
43
  navigation, 
44
  '/docs/guide/getting-started',
45
  { current: true }
46
);
47

48
// Treat index pages as children
49
const breadcrumbWithIndex = findPageBreadcrumb(
50
  navigation,
51
  '/docs/guide/index',
52
  { indexAsChild: true }
53
);
54
```
55

56
### Find Page Children
57

58
Finds child pages for a given path in the navigation tree.
59

60
```typescript { .api }
61
/**
62
 * Finds child pages for given path in navigation tree
63
 * @param navigation - Navigation tree to search in
64
 * @param path - Parent path to find children for
65
 * @param options - Configuration options for child finding
66
 * @returns Array of child navigation items
67
 */
68
function findPageChildren(
69
  navigation?: ContentNavigationItem[],
70
  path?: string,
71
  options?: FindPageOptions
72
): ContentNavigationItem[];
73

74
interface FindPageOptions {
75
  /** Treat index pages as child pages */
76
  indexAsChild?: boolean;
77
}
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
import { findPageChildren } from '@nuxt/content/utils';
84

85
// Find children of a section
86
const navigation = await queryCollectionNavigation('docs');
87
const children = findPageChildren(navigation, '/docs/guide');
88

89
// Include index pages as children
90
const childrenWithIndex = findPageChildren(
91
  navigation,
92
  '/docs/guide',
93
  { indexAsChild: true }
94
);
95
```
96

97
### Find Page Siblings
98

99
Finds sibling pages at the same level as the given path.
100

101
```typescript { .api }
102
/**
103
 * Finds sibling pages for given path in navigation tree
104
 * @param navigation - Navigation tree to search in
105
 * @param path - Path to find siblings for
106
 * @param options - Configuration options for sibling finding
107
 * @returns Array of sibling navigation items
108
 */
109
function findPageSiblings(
110
  navigation?: ContentNavigationItem[],
111
  path?: string,
112
  options?: FindPageOptions
113
): ContentNavigationItem[];
114
```
115

116
**Usage Examples:**
117

118
```typescript
119
import { findPageSiblings } from '@nuxt/content/utils';
120

121
// Find sibling pages
122
const navigation = await queryCollectionNavigation('docs');
123
const siblings = findPageSiblings(navigation, '/docs/guide/installation');
124

125
// Include index pages as siblings
126
const siblingsWithIndex = findPageSiblings(
127
  navigation,
128
  '/docs/guide/installation',
129
  { indexAsChild: true }
130
);
131
```
132

133
### Find Page Headline
134

135
Finds the headline or parent title for a given path.
136

137
```typescript { .api }
138
/**
139
 * Finds headline/parent title for given path
140
 * @param navigation - Navigation tree to search in
141
 * @param path - Path to find headline for
142
 * @param options - Configuration options for headline finding
143
 * @returns Headline string or undefined if not found
144
 */
145
function findPageHeadline(
146
  navigation?: ContentNavigationItem[],
147
  path?: string,
148
  options?: FindPageOptions
149
): string | undefined;
150
```
151

152
**Usage Examples:**
153

154
```typescript
155
import { findPageHeadline } from '@nuxt/content/utils';
156

157
// Find section headline for a page
158
const navigation = await queryCollectionNavigation('docs');
159
const headline = findPageHeadline(navigation, '/docs/guide/installation');
160
// Returns the title of the parent section, e.g., "Guide"
161

162
// Use with index pages
163
const headlineWithIndex = findPageHeadline(
164
  navigation,
165
  '/docs/guide/index',
166
  { indexAsChild: true }
167
);
168
```
169

170
## Usage Patterns
171

172
### Complete Navigation Component
173

174
```vue
175
<template>
176
  <nav>
177
    <!-- Breadcrumb -->
178
    <ol class="breadcrumb">
179
      <li v-for="item in breadcrumb" :key="item.path">
180
        <NuxtLink :to="item.path">{{ item.title }}</NuxtLink>
181
      </li>
182
    </ol>
183

184
    <!-- Current section headline -->
185
    <h1 v-if="headline">{{ headline }}</h1>
186

187
    <!-- Navigation sidebar -->
188
    <aside>
189
      <ul>
190
        <li v-for="child in children" :key="child.path">
191
          <NuxtLink :to="child.path">{{ child.title }}</NuxtLink>
192
        </li>
193
      </ul>
194
    </aside>
195

196
    <!-- Previous/Next navigation -->
197
    <div class="pagination">
198
      <NuxtLink v-if="siblings.length" :to="previousSibling?.path">
199
        Previous: {{ previousSibling?.title }}
200
      </NuxtLink>
201
      <NuxtLink v-if="siblings.length" :to="nextSibling?.path">
202
        Next: {{ nextSibling?.title }}
203
      </NuxtLink>
204
    </div>
205
  </nav>
206
</template>
207

208
<script setup>
209
import { findPageBreadcrumb, findPageChildren, findPageSiblings, findPageHeadline } from '@nuxt/content/utils';
210

211
const route = useRoute();
212
const navigation = await queryCollectionNavigation('docs');
213

214
const breadcrumb = findPageBreadcrumb(navigation, route.path);
215
const children = findPageChildren(navigation, route.path);
216
const siblings = findPageSiblings(navigation, route.path);
217
const headline = findPageHeadline(navigation, route.path);
218

219
// Find previous and next siblings
220
const currentIndex = siblings.findIndex(item => item.path === route.path);
221
const previousSibling = currentIndex > 0 ? siblings[currentIndex - 1] : null;
222
const nextSibling = currentIndex < siblings.length - 1 ? siblings[currentIndex + 1] : null;
223
</script>
224
```
225

226
### Navigation Tree Component
227

228
```vue
229
<template>
230
  <ul class="navigation-tree">
231
    <li v-for="item in navigation" :key="item.path" class="nav-item">
232
      <NuxtLink 
233
        :to="item.path" 
234
        :class="{ active: isActive(item.path) }"
235
      >
236
        {{ item.title }}
237
      </NuxtLink>
238
      
239
      <!-- Recursive children -->
240
      <NavigationTree 
241
        v-if="item.children?.length" 
242
        :navigation="item.children"
243
        class="nav-children"
244
      />
245
    </li>
246
  </ul>
247
</template>
248

249
<script setup>
250
interface Props {
251
  navigation: ContentNavigationItem[];
252
}
253

254
const props = defineProps<Props>();
255
const route = useRoute();
256

257
const isActive = (path: string) => {
258
  return route.path === path || route.path.startsWith(path + '/');
259
};
260
</script>
261
```
262

263
## Types
264

265
```typescript { .api }
266
interface ContentNavigationItem {
267
  /** Display title for navigation item */
268
  title: string;
269
  /** URL path for navigation item */
270
  path: string;
271
  /** File stem (filename without extension) */
272
  stem?: string;
273
  /** Child navigation items */
274
  children?: ContentNavigationItem[];
275
  /** Whether this is a page (true) or directory (false) */
276
  page?: boolean;
277
  /** Additional custom fields from content frontmatter */
278
  [key: string]: unknown;
279
}
280

281
interface FindPageBreadcrumbOptions {
282
  /** Include current page in breadcrumb trail */
283
  current?: boolean;
284
  /** Treat index pages as child pages */
285
  indexAsChild?: boolean;
286
}
287

288
interface FindPageOptions {
289
  /** Treat index pages as child pages */
290
  indexAsChild?: boolean;
291
}
292
```