0
# Navigation Utilities
1

2
Helper functions for working with navigation trees, extracting breadcrumbs, children, siblings, and headlines from hierarchical content structures. These utilities are essential for building navigation components and understanding content relationships.
3

4
## Capabilities
5

6
### Find Page Breadcrumb
7

8
Generates a breadcrumb trail from the navigation tree to a specific page path.
9

10
```typescript { .api }
11
/**
12
 * Generates a breadcrumb trail from navigation tree to a specific path
13
 * @param navigation - The navigation tree array
14
 * @param path - The target 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 | undefined | null, 
21
  options?: FindPageBreadcrumbOptions
22
): ContentNavigationItem[];
23

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

32
**Usage Examples:**
33

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

37
// Generate breadcrumb trail
38
const breadcrumbs = findPageBreadcrumb(navigation, '/docs/guide/installation');
39
// Result: [{ title: 'Docs', path: '/docs' }, { title: 'Guide', path: '/docs/guide' }]
40

41
// Include current page in breadcrumbs
42
const fullBreadcrumbs = findPageBreadcrumb(
43
  navigation, 
44
  '/docs/guide/installation',
45
  { current: true }
46
);
47
// Result: [{ title: 'Docs', path: '/docs' }, { title: 'Guide', path: '/docs/guide' }, { title: 'Installation', path: '/docs/guide/installation' }]
48
```
49

50
### Find Page Children
51

52
Finds all direct children of a specific page in the navigation tree.
53

54
```typescript { .api }
55
/**
56
 * Finds all direct children of a specific page in navigation tree
57
 * @param navigation - The navigation tree array
58
 * @param path - The parent path to find children for
59
 * @param options - Configuration options
60
 * @returns Array of direct child navigation items
61
 */
62
function findPageChildren(
63
  navigation?: ContentNavigationItem[], 
64
  path?: string | undefined | null, 
65
  options?: FindPageOptions
66
): ContentNavigationItem[];
67

68
interface FindPageOptions {
69
  /** Treat index pages as children rather than parents */
70
  indexAsChild?: boolean;
71
}
72
```
73

74
**Usage Examples:**
75

76
```typescript
77
import { findPageChildren } from '@nuxt/content/utils';
78

79
// Find all children of a section
80
const children = findPageChildren(navigation, '/docs/guide');
81
// Result: [{ title: 'Installation', path: '/docs/guide/installation' }, { title: 'Configuration', path: '/docs/guide/configuration' }]
82

83
// Handle index pages as children
84
const indexChildren = findPageChildren(
85
  navigation, 
86
  '/docs/guide',
87
  { indexAsChild: true }
88
);
89
```
90

91
### Find Page Siblings
92

93
Finds all sibling pages (pages at the same level) for a specific page path.
94

95
```typescript { .api }
96
/**
97
 * Finds all sibling pages at the same level as the specified path
98
 * @param navigation - The navigation tree array  
99
 * @param path - The path to find siblings for
100
 * @param options - Configuration options
101
 * @returns Array of sibling navigation items (excludes the current page)
102
 */
103
function findPageSiblings(
104
  navigation?: ContentNavigationItem[], 
105
  path?: string | undefined | null, 
106
  options?: FindPageOptions
107
): ContentNavigationItem[];
108
```
109

110
**Usage Examples:**
111

112
```typescript
113
import { findPageSiblings } from '@nuxt/content/utils';
114

115
// Find sibling pages
116
const siblings = findPageSiblings(navigation, '/docs/guide/installation');
117
// Result: [{ title: 'Configuration', path: '/docs/guide/configuration' }, { title: 'Usage', path: '/docs/guide/usage' }]
118
// Note: excludes '/docs/guide/installation' itself
119
```
120

121
### Find Page Headline
122

123
Extracts the headline (parent section title) for a specific page path.
124

125
```typescript { .api }
126
/**
127
 * Extracts the headline/parent section title for a specific page
128
 * @param navigation - The navigation tree array
129
 * @param path - The path to find headline for  
130
 * @param options - Configuration options
131
 * @returns The headline string or undefined if not found
132
 */
133
function findPageHeadline(
134
  navigation?: ContentNavigationItem[], 
135
  path?: string | undefined | null, 
136
  options?: FindPageOptions
137
): string | undefined;
138
```
139

140
**Usage Examples:**
141

142
```typescript
143
import { findPageHeadline } from '@nuxt/content/utils';
144

145
// Get page headline
146
const headline = findPageHeadline(navigation, '/docs/guide/installation');
147
// Result: "Guide" (the parent section title)
148

149
// Handle index pages
150
const indexHeadline = findPageHeadline(
151
  navigation,
152
  '/docs/guide/index',
153
  { indexAsChild: true }
154
);
155
```
156

157
## Types
158

159
```typescript { .api }
160
interface ContentNavigationItem {
161
  title: string;
162
  path: string;
163
  stem?: string;
164
  children?: ContentNavigationItem[];
165
  page?: false;
166
  [key: string]: unknown;
167
}
168

169
interface FindPageBreadcrumbOptions {
170
  current?: boolean;
171
  indexAsChild?: boolean;
172
}
173

174
interface FindPageOptions {
175
  indexAsChild?: boolean;
176
}
177
```