0
# Setup and Plugin System
1

2
Interfaces for extending Slidev with custom functionality including app initialization, Monaco editor setup, code runners, and various plugin hooks.
3

4
## Capabilities
5

6
### App Setup
7

8
Setup function for configuring the Vue application and router.
9

10
```typescript { .api }
11
/**
12
 * Setup function for configuring the Vue application
13
 * @param context - App context containing Vue app and router instances
14
 */
15
type AppSetup = (context: AppContext) => Awaitable<void>;
16

17
interface AppContext {
18
  app: App;
19
  router: Router;
20
}
21

22
/**
23
 * Define an app setup function
24
 */
25
function defineAppSetup(fn: AppSetup): AppSetup;
26
```
27

28
### Monaco Editor Setup
29

30
Setup function for configuring Monaco editor options and behavior.
31

32
```typescript { .api }
33
/**
34
 * Setup function for configuring Monaco editor
35
 * @param m - Monaco editor module
36
 * @returns Editor configuration options
37
 */
38
type MonacoSetup = (m: typeof monaco) => Awaitable<MonacoSetupReturn | void>;
39

40
interface MonacoSetupReturn {
41
  editorOptions?: monaco.editor.IEditorOptions;
42
}
43

44
/**
45
 * Define a Monaco setup function
46
 */
47
function defineMonacoSetup(fn: MonacoSetup): MonacoSetup;
48
```
49

50
### Root Setup
51

52
Setup function for root-level initialization.
53

54
```typescript { .api }
55
/**
56
 * Setup function for root-level initialization
57
 */
58
type RootSetup = () => Awaitable<void>;
59

60
/**
61
 * Define a root setup function
62
 */
63
function defineRootSetup(fn: RootSetup): RootSetup;
64
```
65

66
### Routes Setup
67

68
Setup function for configuring Vue router routes.
69

70
```typescript { .api }
71
/**
72
 * Setup function for configuring Vue router routes
73
 * @param routes - Array of route record raw objects
74
 * @returns Modified array of route records
75
 */
76
type RoutesSetup = (routes: RouteRecordRaw[]) => RouteRecordRaw[];
77

78
/**
79
 * Define a routes setup function
80
 */
81
function defineRoutesSetup(fn: RoutesSetup): RoutesSetup;
82
```
83

84
### Shortcuts Setup
85

86
Setup function for configuring keyboard shortcuts.
87

88
```typescript { .api }
89
/**
90
 * Setup function for configuring keyboard shortcuts
91
 * @param nav - Navigation operations
92
 * @param defaultShortcuts - Default shortcut options
93
 * @returns Array of shortcut options
94
 */
95
type ShortcutsSetup = (nav: NavOperations, defaultShortcuts: ShortcutOptions[]) => Array<ShortcutOptions>;
96

97
interface NavOperations {
98
  next: () => void;
99
  prev: () => Promise<void>;
100
  nextSlide: () => void;
101
  prevSlide: () => Promise<void>;
102
  go: (index: number) => void;
103
  goFirst: () => void;
104
  goLast: () => void;
105
  downloadPDF: () => Promise<void>;
106
  toggleDark: () => void;
107
  toggleOverview: () => void;
108
  toggleDrawing: () => void;
109
  escapeOverview: () => void;
110
  showGotoDialog: () => void;
111
}
112

113
interface ShortcutOptions {
114
  key: string | Ref<boolean>;
115
  fn?: () => void;
116
  autoRepeat?: boolean;
117
  name?: string;
118
}
119

120
/**
121
 * Define a shortcuts setup function
122
 */
123
function defineShortcutsSetup(fn: ShortcutsSetup): ShortcutsSetup;
124
```
125

126
### Code Runners Setup
127

128
Setup function for configuring code execution providers.
129

130
```typescript { .api }
131
/**
132
 * Setup function for configuring code runners
133
 * @param runners - Existing code runner providers
134
 * @returns Modified or new code runner providers
135
 */
136
type CodeRunnersSetup = (runners: CodeRunnerProviders) => Awaitable<CodeRunnerProviders | void>;
137

138
/**
139
 * Define a code runners setup function
140
 */
141
function defineCodeRunnersSetup(fn: CodeRunnersSetup): CodeRunnersSetup;
142
```
143

144
### Context Menu Setup
145

146
Setup function for configuring context menu items.
147

148
```typescript { .api }
149
/**
150
 * Context menu item type
151
 */
152
type ContextMenuItem = ContextMenuOption | 'separator';
153

154
type ContextMenuOption = {
155
  action: () => void;
156
  disabled?: boolean;
157
} & (
158
  | {
159
    small?: false;
160
    icon?: Component | string;
161
    label: string | Component;
162
  }
163
  | {
164
    small: true;
165
    icon: Component | string;
166
    label: string;
167
  }
168
);
169

170
/**
171
 * Setup function for configuring context menu
172
 * @param items - Computed ref of existing context menu items
173
 * @returns Modified computed ref of context menu items
174
 */
175
type ContextMenuSetup = (items: ComputedRef<ContextMenuItem[]>) => ComputedRef<ContextMenuItem[]>;
176

177
/**
178
 * Define a context menu setup function
179
 */
180
function defineContextMenuSetup(fn: ContextMenuSetup): ContextMenuSetup;
181
```
182

183
### Shiki Highlighter Setup
184

185
Setup function for configuring Shiki syntax highlighting.
186

187
```typescript { .api }
188
/**
189
 * Setup function for configuring Shiki highlighter
190
 * @param shiki - Shiki context with theme loading capability
191
 * @returns Shiki configuration options
192
 */
193
type ShikiSetup = (shiki: ShikiContext) => Awaitable<ShikiSetupReturn | void>;
194

195
interface ShikiContext {
196
  /** @deprecated Pass directly the theme name */
197
  loadTheme: (path: string) => Promise<any>;
198
}
199

200
type ShikiSetupReturn = Partial<
201
  & Omit<CodeToHastOptionsCommon<BuiltinLanguage>, 'lang'>
202
  & CodeOptionsThemes<BuiltinTheme>
203
  & CodeOptionsMeta
204
  & {
205
    setup: (highlighter: Highlighter) => Awaitable<void>;
206
    langs: (LanguageInput | BuiltinLanguage)[];
207
  }
208
>;
209

210
/**
211
 * Define a Shiki setup function
212
 */
213
function defineShikiSetup(fn: ShikiSetup): ShikiSetup;
214
```
215

216
### Mermaid Setup
217

218
Setup function for configuring Mermaid diagram rendering.
219

220
```typescript { .api }
221
/**
222
 * Setup function for configuring Mermaid diagrams
223
 * @returns Mermaid configuration options
224
 */
225
type MermaidSetup = () => Awaitable<Partial<MermaidConfig> | void>;
226

227
/**
228
 * Define a Mermaid setup function
229
 */
230
function defineMermaidSetup(fn: MermaidSetup): MermaidSetup;
231
```
232

233
### KaTeX Setup
234

235
Setup function for configuring KaTeX math rendering.
236

237
```typescript { .api }
238
/**
239
 * Setup function for configuring KaTeX math rendering
240
 * @returns KaTeX configuration options
241
 */
242
type KatexSetup = () => Awaitable<Partial<KatexOptions> | void>;
243

244
/**
245
 * Define a KaTeX setup function
246
 */
247
function defineKatexSetup(fn: KatexSetup): KatexSetup;
248
```
249

250
### UnoCSS Setup
251

252
Setup function for configuring UnoCSS.
253

254
```typescript { .api }
255
/**
256
 * Setup function for configuring UnoCSS
257
 * @returns UnoCSS configuration options
258
 */
259
type UnoSetup = () => Awaitable<Partial<UnoCssConfig> | void>;
260

261
/**
262
 * Define a UnoCSS setup function
263
 */
264
function defineUnoSetup(fn: UnoSetup): UnoSetup;
265
```
266

267
### Transformers Setup
268

269
Setup function for configuring markdown transformers.
270

271
```typescript { .api }
272
/**
273
 * Setup function for configuring markdown transformers
274
 * @returns Transformer configuration
275
 */
276
type TransformersSetup = () => Awaitable<Partial<TransformersSetupReturn>>;
277

278
interface TransformersSetupReturn {
279
  pre: (MarkdownTransformer | false)[];
280
  preCodeblock: (MarkdownTransformer | false)[];
281
  postCodeblock: (MarkdownTransformer | false)[];
282
  post: (MarkdownTransformer | false)[];
283
}
284

285
/**
286
 * Define a transformers setup function
287
 */
288
function defineTransformersSetup(fn: TransformersSetup): TransformersSetup;
289
```
290

291
### Preparser Setup
292

293
Setup function for configuring content preparsers.
294

295
```typescript { .api }
296
/**
297
 * Setup function for configuring preparsers
298
 * @param context - Context with filepath, headmatter, and mode
299
 * @returns Array of preparser extensions
300
 */
301
type PreparserSetup = (context: {
302
  filepath: string;
303
  headmatter: Record<string, unknown>;
304
  mode?: string;
305
}) => Awaitable<SlidevPreparserExtension[]>;
306

307
/**
308
 * Define a preparser setup function
309
 */
310
function definePreparserSetup(fn: PreparserSetup): PreparserSetup;
311
```
312

313
### Vite Plugins Setup
314

315
Setup function for configuring Vite plugins.
316

317
```typescript { .api }
318
/**
319
 * Setup function for configuring Vite plugins (server-side)
320
 * @param options - Resolved Slidev options
321
 * @returns Array of Vite plugins
322
 */
323
type VitePluginsSetup = (options: ResolvedSlidevOptions) => Awaitable<VitePlugin[]>;
324

325
/**
326
 * Define a Vite plugins setup function
327
 */
328
function defineVitePluginsSetup(fn: VitePluginsSetup): VitePluginsSetup;
329
```
330

331
## Usage Examples
332

333
```typescript
334
import { 
335
  defineAppSetup, 
336
  defineMonacoSetup, 
337
  defineShortcutsSetup,
338
  defineCodeRunnersSetup 
339
} from "@slidev/types";
340

341
// App setup example
342
export default defineAppSetup(({ app, router }) => {
343
  // Configure Vue app
344
  app.config.globalProperties.$myGlobal = "value";
345
  
346
  // Add router guards
347
  router.beforeEach((to, from, next) => {
348
    console.log(`Navigating to ${to.path}`);
349
    next();
350
  });
351
});
352

353
// Monaco setup example
354
export default defineMonacoSetup((monaco) => {
355
  // Configure Monaco editor
356
  monaco.languages.typescript.typescriptDefaults.setEagerModelSync(true);
357
  
358
  return {
359
    editorOptions: {
360
      fontSize: 14,
361
      theme: 'vs-dark'
362
    }
363
  };
364
});
365

366
// Shortcuts setup example
367
export default defineShortcutsSetup((nav, shortcuts) => {
368
  return [
369
    ...shortcuts,
370
    {
371
      key: 'ctrl+shift+p',
372
      fn: () => console.log('Custom shortcut pressed'),
373
      name: 'Custom Action'
374
    }
375
  ];
376
});
377
```