0
# Export System
1

2
Multi-format export capabilities for generating PDF, PNG, PPTX, and Markdown outputs from Slidev presentations using browser automation with Playwright.
3

4
## Capabilities
5

6
### Export Slides Function
7

8
Export slides to various formats with comprehensive configuration options for different output types.
9

10
```typescript { .api }
11
/**
12
 * Export slides to PDF, PNG, PPTX, or Markdown formats
13
 * @param options - Export configuration options
14
 * @returns Promise<string> - Path to exported file(s)
15
 */
16
function exportSlides(options: ExportOptions): Promise<string>;
17

18
interface ExportOptions {
19
  /** Total number of slides */
20
  total: number;
21
  /** Page ranges to export (e.g., "1,3-5,10") */
22
  range?: string;
23
  /** Slide information array */
24
  slides: SlideInfo[];
25
  /** Server port for rendering */
26
  port?: number;
27
  /** Base URL for server */
28
  base?: string;
29
  /** Output format */
30
  format?: 'pdf' | 'png' | 'pptx' | 'md';
31
  /** Output file path */
32
  output?: string;
33
  /** Rendering timeout in milliseconds */
34
  timeout?: number;
35
  /** Wait time before export in milliseconds */
36
  wait?: number;
37
  /** Wait until specific event */
38
  waitUntil: 'networkidle' | 'load' | 'domcontentloaded' | undefined;
39
  /** Export as dark theme */
40
  dark?: boolean;
41
  /** Router mode for URL generation */
42
  routerMode?: 'hash' | 'history';
43
  /** Slide width in pixels */
44
  width?: number;
45
  /** Slide height in pixels */
46
  height?: number;
47
  /** Export click animations */
48
  withClicks?: boolean;
49
  /** Custom browser executable path */
50
  executablePath?: string;
51
  /** Include table of contents */
52
  withToc?: boolean;
53
  /** Render slides individually (better for global components) */
54
  perSlide?: boolean;
55
  /** Scale factor for image export */
56
  scale?: number;
57
  /** Omit browser background for PNG */
58
  omitBackground?: boolean;
59
}
60
```
61

62
**Usage Examples:**
63

64
```typescript
65
import { exportSlides, resolveOptions } from "@slidev/cli";
66

67
// Basic PDF export
68
const options = await resolveOptions({ entry: "slides.md" }, "export");
69
const outputPath = await exportSlides({
70
  total: options.data.slides.length,
71
  slides: options.data.slides,
72
  port: 12445,
73
  format: 'pdf',
74
  output: 'presentation.pdf',
75
  waitUntil: 'networkidle'
76
});
77

78
// PNG export with custom dimensions
79
await exportSlides({
80
  total: options.data.slides.length,
81
  slides: options.data.slides,
82
  port: 12445,
83
  format: 'png',
84
  output: 'slides',  // Will create slides-001.png, slides-002.png, etc.
85
  width: 1920,
86
  height: 1080,
87
  scale: 2,
88
  omitBackground: true
89
});
90

91
// Export specific slides with clicks
92
await exportSlides({
93
  total: options.data.slides.length,
94
  slides: options.data.slides,
95
  port: 12445,
96
  range: "1,3-5,10",
97
  withClicks: true,
98
  dark: true,
99
  timeout: 60000
100
});
101
```
102

103
### Export Notes Function
104

105
Export slide notes to PDF format for speaker reference and presentation preparation.
106

107
```typescript { .api }
108
/**
109
 * Export slide notes to PDF format
110
 * @param options - Notes export configuration
111
 * @returns Promise<string> - Path to exported notes file
112
 */
113
function exportNotes(options: ExportNotesOptions): Promise<string>;
114

115
interface ExportNotesOptions {
116
  /** Server port for rendering */
117
  port?: number;
118
  /** Base URL for server */
119
  base?: string;
120
  /** Output file path */
121
  output?: string;
122
  /** Rendering timeout in milliseconds */
123
  timeout?: number;
124
  /** Wait time before export in milliseconds */
125
  wait?: number;
126
}
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
import { exportNotes, createServer, resolveOptions } from "@slidev/cli";
133

134
// Export speaker notes
135
const options = await resolveOptions({ entry: "slides.md" }, "export");
136
const server = await createServer(options, { server: { port: 12445 } });
137
await server.listen();
138

139
const notesPath = await exportNotes({
140
  port: 12445,
141
  output: "speaker-notes.pdf",
142
  timeout: 30000,
143
  wait: 1000
144
});
145

146
await server.close();
147
```
148

149
### Export Options Resolution
150

151
Utility function for resolving export options from CLI arguments and Slidev configuration.
152

153
```typescript { .api }
154
/**
155
 * Resolve export options from CLI arguments and configuration
156
 * @param args - CLI export arguments
157
 * @param options - Resolved Slidev options
158
 * @param defaultOutput - Default output filename
159
 * @returns ExportOptions - Resolved export configuration
160
 */
161
function getExportOptions(
162
  args: ExportArgs,
163
  options: ResolvedSlidevOptions,
164
  defaultOutput?: string
165
): ExportOptions;
166

167
interface ExportArgs {
168
  'output'?: string;
169
  'format'?: string;
170
  'timeout'?: number;
171
  'wait'?: number;
172
  'wait-until'?: string;
173
  'range'?: string;
174
  'dark'?: boolean;
175
  'with-clicks'?: boolean;
176
  'executable-path'?: string;
177
  'with-toc'?: boolean;
178
  'per-slide'?: boolean;
179
  'scale'?: number;
180
  'omit-background'?: boolean;
181
}
182
```
183

184
**Usage Examples:**
185

186
```typescript
187
import { getExportOptions, resolveOptions } from "@slidev/cli";
188

189
const options = await resolveOptions({ entry: "slides.md" }, "export");
190
const args = {
191
  'format': 'png',
192
  'dark': true,
193
  'with-clicks': true,
194
  'scale': 2
195
};
196

197
const exportOptions = getExportOptions(args, options, "my-presentation");
198
// Automatically resolves paths, dimensions, and configuration
199
```
200

201
### Format-Specific Export Options
202

203
Different export formats support specific configuration options and behaviors.
204

205
```typescript { .api }
206
// PDF Export Configuration
207
interface PdfExportOptions {
208
  /** Page format and margins */
209
  format: 'A4' | 'Letter' | 'Legal' | 'A3';
210
  landscape: boolean;           // Always true for presentations
211
  printBackground: boolean;     // Include CSS backgrounds
212
  
213
  /** PDF metadata */
214
  title?: string;              // From presentation title
215
  author?: string;             // From presentation config
216
  subject?: string;            // From presentation description
217
  
218
  /** PDF structure */
219
  withToc: boolean;            // Include bookmark navigation
220
  perSlide: boolean;           // Individual slide rendering
221
  
222
  /** Quality settings */
223
  scale: number;               // 1-3, affects quality/size
224
  timeout: number;             // Rendering timeout per slide
225
}
226

227
// PNG Export Configuration  
228
interface PngExportOptions {
229
  /** Image dimensions */
230
  width: number;               // Slide width in pixels
231
  height: number;              // Slide height in pixels
232
  scale: number;               // Device pixel ratio (1-3)
233
  
234
  /** Visual options */
235
  omitBackground: boolean;     // Transparent background
236
  quality: number;             // 0-100, compression quality
237
  
238
  /** File naming */
239
  output: string;              // Base filename (adds -001, -002, etc.)
240
  numbering: 'sequential' | 'slide-number';
241
}
242

243
// PPTX Export Configuration
244
interface PptxExportOptions {
245
  /** Slide dimensions */
246
  slideSize: 'LAYOUT_16x9' | 'LAYOUT_4x3' | 'LAYOUT_WIDE';
247
  
248
  /** Content preservation */
249
  preserveAnimations: boolean;  // Convert click animations
250
  embedFonts: boolean;         // Include custom fonts
251
  
252
  /** Export quality */
253
  imageQuality: 'high' | 'medium' | 'low';
254
  compressImages: boolean;
255
}
256

257
// Markdown Export Configuration
258
interface MarkdownExportOptions {
259
  /** Content structure */
260
  includeNotes: boolean;       // Speaker notes
261
  includeFrontmatter: boolean; // YAML frontmatter
262
  slideDelimiter: string;      // Slide separator
263
  
264
  /** Asset handling */
265
  extractAssets: boolean;      // Save images separately
266
  assetPath: string;           // Relative path for assets
267
}
268
```
269

270
### Browser Automation Configuration
271

272
Playwright browser automation settings for rendering slides.
273

274
```typescript { .api }
275
// Browser automation configuration
276
interface BrowserConfig {
277
  /** Browser selection */
278
  browser: 'chromium' | 'firefox' | 'webkit';
279
  executablePath?: string;     // Custom browser path
280
  
281
  /** Rendering options */
282
  headless: boolean;           // Always true for export
283
  deviceScaleFactor: number;   // From scale option
284
  viewport: {
285
    width: number;
286
    height: number;
287
  };
288
  
289
  /** Performance settings */
290
  timeout: number;             // Per-page timeout
291
  waitUntil: 'networkidle' | 'load' | 'domcontentloaded';
292
  
293
  /** Resource handling */
294
  ignoreHTTPSErrors: boolean;
295
  bypassCSP: boolean;         // For embedded content
296
  
297
  /** Network optimization */
298
  blockResources: string[];    // Block unnecessary resources
299
  cachingEnabled: boolean;
300
}
301

302
// Page rendering configuration
303
interface PageRenderConfig {
304
  /** Click simulation */
305
  withClicks: boolean;
306
  clickDelay: number;          // Delay between clicks (ms)
307
  maxClicks: number;           // Safety limit
308
  
309
  /** Theme handling */
310
  dark: boolean;
311
  colorScheme: 'light' | 'dark' | 'no-preference';
312
  
313
  /** Wait strategies */
314
  waitForSelector?: string;    // Custom wait selector
315
  waitForFunction?: string;    // Custom wait function
316
  additionalDelay: number;     // Extra wait time
317
}
318
```
319

320
### Export Progress and Monitoring
321

322
Progress tracking and monitoring capabilities for long-running exports.
323

324
```typescript { .api }
325
// Progress tracking interface
326
interface ExportProgress {
327
  /** Overall progress */
328
  currentSlide: number;
329
  totalSlides: number;
330
  percentage: number;
331
  
332
  /** Current operation */
333
  operation: 'loading' | 'rendering' | 'processing' | 'saving';
334
  slideTitle?: string;
335
  
336
  /** Timing information */
337
  startTime: Date;
338
  elapsedTime: number;        // Milliseconds
339
  estimatedRemaining: number; // Milliseconds
340
  
341
  /** Error tracking */
342
  errors: ExportError[];
343
  warnings: string[];
344
}
345

346
interface ExportError {
347
  slideIndex: number;
348
  slideTitle?: string;
349
  error: Error;
350
  recoverable: boolean;
351
  retryCount: number;
352
}
353

354
// Progress monitoring utilities
355
interface ProgressMonitoring {
356
  /** Progress callback for CLI progress bar */
357
  onProgress?: (progress: ExportProgress) => void;
358
  
359
  /** Error handling callback */
360
  onError?: (error: ExportError) => 'retry' | 'skip' | 'abort';
361
  
362
  /** Completion callback */
363
  onComplete?: (results: ExportResults) => void;
364
}
365
```
366

367
### Error Handling and Recovery
368

369
Comprehensive error handling for export operations.
370

371
```typescript { .api }
372
// Export error scenarios
373
interface ExportErrorHandling {
374
  /** Browser automation errors */
375
  browserErrors: {
376
    launchFailure: "install-playwright";
377
    navigationTimeout: "increase-timeout";
378
    renderingError: "retry-with-fallback";
379
    memoryLeak: "restart-browser";
380
  };
381
  
382
  /** Content rendering errors */
383
  contentErrors: {
384
    missingAssets: "skip-and-warn";
385
    fontLoadingFailure: "fallback-fonts";
386
    componentError: "error-placeholder";
387
    networkFailure: "offline-mode";
388
  };
389
  
390
  /** File system errors */
391
  fileSystemErrors: {
392
    permissionDenied: "check-permissions";
393
    diskFull: "cleanup-and-retry";
394
    pathNotFound: "create-directories";
395
  };
396
  
397
  /** Format-specific errors */
398
  formatErrors: {
399
    pdfGeneration: "retry-with-different-settings";
400
    imageCompression: "reduce-quality";
401
    pptxCreation: "fallback-to-pdf";
402
  };
403
}
404
```
405

406
**Usage Examples:**
407

408
```typescript
409
import { exportSlides } from "@slidev/cli";
410

411
async function exportWithErrorHandling() {
412
  try {
413
    const result = await exportSlides({
414
      total: 20,
415
      slides: slideData,
416
      port: 12445,
417
      format: 'pdf',
418
      timeout: 60000,  // Increased timeout
419
      waitUntil: 'networkidle'
420
    });
421
    
422
    console.log("Export completed:", result);
423
    
424
  } catch (error) {
425
    if (error.message.includes('timeout')) {
426
      console.log("Export timed out, trying with increased timeout...");
427
      // Retry with longer timeout
428
    } else if (error.message.includes('browser')) {
429
      console.log("Browser launch failed, check Playwright installation");
430
    } else {
431
      console.error("Export failed:", error);
432
    }
433
  }
434
}
435
```
436

437
## Integration with CLI
438

439
The export functions are used internally by CLI export commands:
440

441
```bash
442
# CLI commands internally call:
443
slidev export [entry..]           # → exportSlides(options)
444
slidev export-notes [entry..]     # → exportNotes(options)
445
slidev build --download           # → exportSlides() during build
446
```
447

448
The programmatic API provides fine-grained control over export processes for custom workflows and batch processing scenarios.