0
# VuePress Default Theme
1

2
VuePress Default Theme is a Vue.js-based documentation theme that provides a complete layout system with navigation, sidebar, search functionality, and responsive design. It includes built-in plugins for active header links, search, progress indicators, and custom container blocks.
3

4
## Package Information
5

6
- **Package Name**: @vuepress/theme-default
7
- **Package Type**: npm  
8
- **Language**: JavaScript (Vue.js)
9
- **Installation**: `npm install @vuepress/theme-default`
10

11
## Core Imports
12

13
```javascript
14
// Theme configuration function
15
const defaultTheme = require('@vuepress/theme-default');
16

17
// Individual utility functions
18
const { 
19
  normalize, 
20
  isExternal, 
21
  resolvePage, 
22
  resolveSidebarItems 
23
} = require('@vuepress/theme-default/util');
24
```
25

26
For ESM:
27

28
```javascript
29
import defaultTheme from '@vuepress/theme-default';
30
import { normalize, isExternal } from '@vuepress/theme-default/util';
31
```
32

33
## Basic Usage
34

35
```javascript
36
// VuePress config file
37
module.exports = {
38
  theme: '@vuepress/theme-default',
39
  themeConfig: {
40
    navbar: [
41
      { text: 'Home', link: '/' },
42
      { text: 'Guide', link: '/guide/' }
43
    ],
44
    sidebar: {
45
      '/guide/': [
46
        {
47
          title: 'Getting Started',
48
          children: ['/guide/', '/guide/installation']
49
        }
50
      ]
51
    },
52
    searchMaxSuggestions: 10,
53
    smoothScroll: true
54
  }
55
}
56
```
57

58
## Architecture
59

60
VuePress Default Theme is organized around several key components:
61

62
- **Theme Configuration**: Main theme function that configures plugins and component aliases
63
- **Layout System**: Two main layouts (Layout.vue for content pages, 404.vue for error pages)  
64
- **Component Library**: 15+ Vue components for navigation, sidebar, content display
65
- **Global Components**: Reusable components (Badge, CodeGroup, CodeBlock) available globally
66
- **Utility Functions**: Path processing, page resolution, and sidebar generation utilities  
67
- **Styling System**: Stylus-based styles with customizable variables and responsive design
68

69
## Capabilities
70

71
### Theme Configuration
72

73
Main theme configuration function that sets up plugins, aliases, and component resolution based on theme options.
74

75
```javascript { .api }
76
/**
77
 * VuePress theme configuration function
78
 * @param {object} options - Theme configuration options
79
 * @param {object} ctx - VuePress context with themeConfig and siteConfig
80
 * @returns {object} Theme configuration with plugins and aliases
81
 */
82
function defaultTheme(options, ctx): {
83
  alias(): object;
84
  plugins: Array<string | [string, object]>;
85
};
86
```
87

88
[Theme Configuration](./theme-configuration.md)
89

90
### Navigation Components
91

92
Navigation bar and dropdown menu components for site-wide navigation with responsive design and active state handling.
93

94
```javascript { .api }
95
// Vue component exports (available as @theme/components/*)
96
const Navbar: VueComponent;
97
const NavLinks: VueComponent;
98
const NavLink: VueComponent;
99
const DropdownLink: VueComponent;
100
```
101

102
[Navigation](./navigation.md)
103

104
### Sidebar Components  
105

106
Sidebar navigation system with collapsible groups, active link highlighting, and mobile responsive behavior.
107

108
```javascript { .api }
109
// Vue component exports  
110
const Sidebar: VueComponent;
111
const SidebarLinks: VueComponent;
112
const SidebarLink: VueComponent;
113
const SidebarGroup: VueComponent;
114
const SidebarButton: VueComponent;
115
```
116

117
[Sidebar](./sidebar.md)
118

119
### Page Layout Components
120

121
Core page layout and content display components including homepage hero layout and standard page wrapper.
122

123
```javascript { .api }
124
// Vue component exports
125
const Layout: VueComponent;  // Main layout with navbar, sidebar, content
126
const Home: VueComponent;    // Homepage hero layout
127
const Page: VueComponent;    // Standard page content wrapper
128
const PageEdit: VueComponent; // Edit page links and metadata
129
const PageNav: VueComponent; // Next/previous page navigation
130
```
131

132
[Page Layout](./page-layout.md)
133

134
### Global Components
135

136
Globally available Vue components for content enhancement including badges, code blocks, and tabbed code groups.
137

138
```javascript { .api }
139
// Globally registered components (available in all markdown files)
140
const Badge: VueComponent;     // Inline badge/label with color variants
141
const CodeGroup: VueComponent; // Tabbed code block container  
142
const CodeBlock: VueComponent; // Individual code block
143
```
144

145
[Global Components](./global-components.md)
146

147
### Utility Functions
148

149
Path processing, page resolution, and sidebar generation utilities for theme customization and extension.
150

151
```javascript { .api }
152
// Core utility functions
153
function normalize(path: string): string;
154
function isExternal(path: string): boolean;
155
function resolvePage(pages: Page[], rawPath: string, base?: string): Page;
156
function resolveSidebarItems(page: Page, regularPath: string, site: SiteData, localePath: string): SidebarGroup[];
157
```
158

159
[Utilities](./utilities.md)
160

161
## Types
162

163
```javascript { .api }
164
interface VueComponent {
165
  // Vue.js component definition
166
  name?: string;
167
  props?: object;
168
  data?(): object;
169
  methods?: object;
170
  computed?: object;
171
  // ... other Vue component options
172
}
173

174
interface Page {
175
  key: string;
176
  path: string;
177
  regularPath: string;
178
  title: string;
179
  frontmatter: object;
180
  headers?: Header[];
181
}
182

183
interface Header {
184
  level: number;
185
  title: string;
186
  slug: string;
187
  children?: Header[];
188
}
189

190
interface SiteData {
191
  pages: Page[];
192
  themeConfig: object;
193
}
194

195
interface SidebarGroup {
196
  type: 'group' | 'page' | 'external' | 'auto';
197
  title?: string;
198
  path?: string;
199
  children?: SidebarGroup[];
200
  collapsable?: boolean;
201
  sidebarDepth?: number;
202
}
203
```