0
# Utility Functions
1

2
Path processing, page resolution, and sidebar generation utilities for theme customization, extension, and internal navigation logic.
3

4
## Capabilities
5

6
### Path Processing Functions
7

8
Utility functions for normalizing and processing URL paths in VuePress applications.
9

10
```javascript { .api }
11
/**
12
 * Normalize URL path by removing hash and file extensions
13
 * @param {string} path - Raw path to normalize
14
 * @returns {string} Normalized path
15
 */
16
function normalize(path): string;
17

18
/**
19
 * Extract hash fragment from path
20
 * @param {string} path - Path containing hash fragment  
21
 * @returns {string|undefined} Hash fragment or undefined
22
 */
23
function getHash(path): string | undefined;
24

25
/**
26
 * Ensure .html extension on internal paths
27
 * @param {string} path - Path to process
28
 * @returns {string} Path with .html extension
29
 */
30
function ensureExt(path): string;
31

32
/**
33
 * Check if path is external URL
34
 * @param {string} path - Path to check
35
 * @returns {boolean} True if external URL
36
 */
37
function isExternal(path): boolean;
38

39
/**
40
 * Check if path is mailto link
41
 * @param {string} path - Path to check
42
 * @returns {boolean} True if mailto link
43
 */
44
function isMailto(path): boolean;
45

46
/**
47
 * Check if path is tel link  
48
 * @param {string} path - Path to check
49
 * @returns {boolean} True if tel link
50
 */
51
function isTel(path): boolean;
52
```
53

54
**Usage Examples:**
55

56
```javascript
57
import { normalize, isExternal, ensureExt } from '@vuepress/theme-default/util';
58

59
// Normalize paths
60
normalize('/guide/installation.md#setup'); // → '/guide/installation'
61
normalize('/api.html'); // → '/api'
62

63
// Check external links
64
isExternal('https://github.com'); // → true
65
isExternal('/internal-page'); // → false
66

67
// Ensure extensions
68
ensureExt('/guide/'); // → '/guide/'  
69
ensureExt('/api'); // → '/api.html'
70
```
71

72
### Route and Navigation Functions
73

74
Functions for handling active states and route matching.
75

76
```javascript { .api }
77
/**
78
 * Check if route matches path (for active link states)
79
 * @param {object} route - Vue router route object
80
 * @param {string} path - Path to compare against
81
 * @returns {boolean} True if route is active for path
82
 */
83
function isActive(route, path): boolean;
84

85
/**
86
 * Process navigation link configuration
87
 * @param {object} linkItem - Navigation link configuration
88
 * @returns {object} Processed link item with type
89
 */
90
function resolveNavLinkItem(linkItem): object;
91
```
92

93
**Usage Examples:**
94

95
```javascript
96
// Check active state
97
const route = this.$route;
98
isActive(route, '/guide/'); // → true if current route matches
99

100
// Process nav links
101
const navItem = resolveNavLinkItem({
102
  text: 'Guide',
103
  link: '/guide/',
104
  items: [...]
105
}); // → { text: 'Guide', link: '/guide/', type: 'links' }
106
```
107

108
### Page Resolution Functions
109

110
Functions for resolving pages and building navigation structures.
111

112
```javascript { .api }
113
/**
114
 * Resolve page object from path and pages array
115
 * @param {Array} pages - Array of all site pages
116
 * @param {string} rawPath - Raw path to resolve
117
 * @param {string} [base] - Base path for resolution
118
 * @returns {object} Resolved page object
119
 */
120
function resolvePage(pages, rawPath, base?): object;
121

122
/**
123
 * Build sidebar navigation structure for current page
124
 * @param {object} page - Current page object
125
 * @param {string} regularPath - Regular path of current page
126
 * @param {object} site - Site data with pages and config
127
 * @param {string} localePath - Locale path for i18n
128
 * @returns {Array} Array of sidebar groups and items
129
 */
130
function resolveSidebarItems(page, regularPath, site, localePath): Array;
131

132
/**
133
 * Match current path to sidebar configuration
134
 * @param {string} regularPath - Regular path to match
135
 * @param {object|Array} config - Sidebar configuration
136
 * @returns {object} Matching config with base path
137
 */
138
function resolveMatchingConfig(regularPath, config): object;
139
```
140

141
**Usage Examples:**
142

143
```javascript
144
// Resolve page
145
const page = resolvePage(
146
  site.pages,
147
  '/guide/installation',
148
  '/guide/'
149
); // → { type: 'page', path: '/guide/installation.html', title: '...' }
150

151
// Build sidebar items
152
const sidebarItems = resolveSidebarItems(
153
  currentPage,
154
  '/guide/installation',
155
  site,
156
  '/'
157
); // → [{ type: 'group', title: 'Guide', children: [...] }]
158
```
159

160
### Header Processing Functions
161

162
Functions for processing and organizing page headers for navigation.
163

164
```javascript { .api }
165
/**
166
 * Group h3 headers under h2 parent headers
167
 * @param {Array} headers - Array of header objects
168
 * @returns {Array} Grouped headers with h3s as children of h2s
169
 */
170
function groupHeaders(headers): Array;
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
const headers = [
177
  { level: 2, title: 'Getting Started', slug: 'getting-started' },
178
  { level: 3, title: 'Installation', slug: 'installation' },
179
  { level: 3, title: 'Configuration', slug: 'configuration' },
180
  { level: 2, title: 'Advanced', slug: 'advanced' }
181
];
182

183
const grouped = groupHeaders(headers);
184
// → [
185
//     { 
186
//       level: 2, 
187
//       title: 'Getting Started', 
188
//       children: [
189
//         { level: 3, title: 'Installation', slug: 'installation' },
190
//         { level: 3, title: 'Configuration', slug: 'configuration' }
191
//       ]
192
//     },
193
//     { level: 2, title: 'Advanced', slug: 'advanced' }
194
//   ]
195
```
196

197
## Regular Expressions
198

199
Utility regular expressions for path processing:
200

201
```javascript { .api }
202
/** Regex for URL hash fragments (#section) */
203
const hashRE: RegExp = /#.*$/;
204

205
/** Regex for .md and .html file extensions */
206
const extRE: RegExp = /\.(md|html)$/;
207

208
/** Regex for trailing slashes */
209
const endingSlashRE: RegExp = /\/$/;
210

211
/** Regex for external URLs (protocol prefixes) */
212
const outboundRE: RegExp = /^[a-z]+:/i;
213
```
214

215
**Usage:**
216

217
```javascript
218
// Test against patterns
219
hashRE.test('/guide#setup'); // → true
220
extRE.test('/api.md'); // → true
221
endingSlashRE.test('/guide/'); // → true
222
outboundRE.test('https://example.com'); // → true
223
```
224

225
## Type Definitions
226

227
```javascript { .api }
228
interface Page {
229
  /** Unique page key */
230
  key: string;
231
  /** Full page path with extension */
232
  path: string;
233
  /** Regular path without extension */
234
  regularPath: string;
235
  /** Page title */
236
  title: string;
237
  /** Frontmatter data */
238
  frontmatter: object;
239
  /** Page headers for navigation */
240
  headers?: Header[];
241
}
242

243
interface Header {
244
  /** Header level (1-6) */
245
  level: number;
246
  /** Header text content */
247
  title: string;
248
  /** URL slug for linking */
249
  slug: string;
250
  /** Nested child headers */
251
  children?: Header[];
252
}
253

254
interface SiteData {
255
  /** All site pages */
256
  pages: Page[];
257
  /** Theme configuration */
258
  themeConfig: object;
259
}
260

261
interface ResolvedPage {
262
  /** Page type */
263
  type: 'page' | 'external';
264
  /** Page path */
265
  path: string;
266
  /** Page title */
267
  title?: string;
268
  /** Page headers */
269
  headers?: Header[];
270
}
271

272
interface SidebarGroup {
273
  /** Group type */
274
  type: 'group' | 'page' | 'external' | 'auto';
275
  /** Group title */
276
  title?: string;
277
  /** Group path */
278
  path?: string;
279
  /** Child items */
280
  children?: SidebarGroup[];
281
  /** Whether group can be collapsed */
282
  collapsable?: boolean;
283
  /** Sidebar depth */
284
  sidebarDepth?: number;
285
  /** Initial open group index */
286
  initialOpenGroupIndex?: number;
287
}
288

289
interface NavLinkItem {
290
  /** Link text */
291
  text: string;
292
  /** Link URL */
293
  link?: string;
294
  /** Nested items for dropdown */
295
  items?: NavLinkItem[];
296
  /** Link type */
297
  type?: 'link' | 'links';
298
}
299
```
300

301
## Error Handling
302

303
Utility functions include error handling and logging:
304

305
```javascript
306
// Page resolution with error logging
307
function resolvePage(pages, rawPath, base) {
308
  // ... resolution logic ...
309
  if (!found) {
310
    console.error(`[vuepress] No matching page found for sidebar item "${rawPath}"`);
311
    return {};
312
  }
313
  return page;
314
}
315
```
316

317
Functions gracefully handle edge cases:
318
- Missing or malformed paths
319
- Invalid page configurations  
320
- Circular reference detection
321
- Locale fallback resolution