0
# Output and Rendering
1

2
Output generation system including themes, renderers, routing, and multiple output formats with extensive customization options for generating beautiful, navigable documentation.
3

4
## Capabilities
5

6
### Renderer Class
7

8
Main renderer that coordinates the generation of documentation output from reflection models.
9

10
```typescript { .api }
11
/**
12
 * Main renderer coordinates output generation from reflections to various formats
13
 */
14
class Renderer extends AbstractComponent<Application, RendererEvents> {
15
  /** Application instance */
16
  readonly application: Application;
17
  /** Currently active theme */
18
  theme?: Theme;
19
  
20
  /**
21
   * Render project to output directory
22
   * @param project - Project reflection to render
23
   * @param outputDirectory - Target output directory
24
   */
25
  render(project: ProjectReflection, outputDirectory: string): Promise<void>;
26
  
27
  /**
28
   * Render individual document/page
29
   * @param page - Page event containing reflection data
30
   * @returns Rendered HTML content
31
   */
32
  renderDocument(page: PageEvent<Reflection>): string;
33
  
34
  /**
35
   * Get template for rendering specific reflection type
36
   * @param reflection - Reflection to get template for
37
   * @returns Template function
38
   */
39
  getTemplate(reflection: Reflection): RenderTemplate<PageEvent<Reflection>>;
40
  
41
  /**
42
   * Add template for specific reflection type
43
   * @param name - Template name
44
   * @param template - Template function
45
   */
46
  addTemplate(name: string, template: RenderTemplate<PageEvent<Reflection>>): void;
47
  
48
  /**
49
   * Remove template
50
   * @param name - Template name to remove
51
   */
52
  removeTemplate(name: string): void;
53
}
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { Application, Renderer } from "typedoc";
60

61
const app = await Application.bootstrap({
62
  entryPoints: ["src/index.ts"],
63
  out: "docs",
64
  theme: "default",
65
});
66

67
const project = await app.convert();
68
if (project) {
69
  // Render using the application's renderer
70
  await app.renderer.render(project, "docs");
71
  
72
  // Custom rendering with event handling
73
  app.renderer.on("beginPage", (page) => {
74
    console.log(`Rendering page: ${page.url}`);
75
  });
76
  
77
  app.renderer.on("endPage", (page) => {
78
    console.log(`Completed page: ${page.url}`);
79
  });
80
}
81
```
82

83
### Theme System
84

85
Theme system providing customizable rendering templates and styling for documentation output.
86

87
```typescript { .api }
88
/**
89
 * Base theme class for rendering documentation
90
 */
91
abstract class Theme {
92
  /** Renderer instance */
93
  readonly renderer: Renderer;
94
  
95
  /**
96
   * Render a page using the theme
97
   * @param page - Page event with reflection data
98
   * @param template - Template function to use
99
   * @returns Rendered HTML content
100
   */
101
  abstract render(
102
    page: PageEvent<Reflection>, 
103
    template: RenderTemplate<PageEvent<Reflection>>
104
  ): string;
105
  
106
  /**
107
   * Get URL mappings for all pages
108
   * @param project - Project reflection
109
   * @returns Array of URL mappings
110
   */
111
  abstract getUrls(project: ProjectReflection): UrlMapping[];
112
  
113
  /**
114
   * Get navigation structure  
115
   * @param project - Project reflection
116
   * @returns Navigation element tree
117
   */
118
  abstract getNavigation(project: ProjectReflection): NavigationElement;
119
  
120
  /**
121
   * Get reflection URL
122
   * @param reflection - Reflection to get URL for
123
   * @returns URL string
124
   */
125
  getUrl(reflection: Reflection): string | undefined;
126
  
127
  /**
128
   * Get mapping between reflection and URL
129
   * @param reflection - Reflection to map
130
   * @returns URL mapping or undefined
131
   */
132
  getMapping(reflection: Reflection): UrlMapping | undefined;
133
}
134

135
/**
136
 * Default HTML theme implementation
137
 */
138
class DefaultTheme extends Theme {
139
  /** Theme context for rendering */
140
  context: DefaultThemeRenderContext;
141
  
142
  render(
143
    page: PageEvent<Reflection>, 
144
    template: RenderTemplate<PageEvent<Reflection>>
145
  ): string;
146
  
147
  getUrls(project: ProjectReflection): UrlMapping[];
148
  
149
  getNavigation(project: ProjectReflection): NavigationElement;
150
  
151
  /**
152
   * Get render context for theme
153
   * @param page - Page being rendered
154
   * @returns Render context
155
   */
156
  getRenderContext(page: PageEvent<Reflection>): DefaultThemeRenderContext;
157
}
158
```
159

160
**Usage Examples:**
161

162
```typescript
163
import { DefaultTheme, Theme } from "typedoc";
164

165
// Create custom theme extending default
166
class CustomTheme extends DefaultTheme {
167
  render(page: PageEvent<Reflection>, template: RenderTemplate<PageEvent<Reflection>>): string {
168
    // Add custom header/footer
169
    const content = super.render(page, template);
170
    return `
171
      <div class="custom-header">Custom Documentation</div>
172
      ${content}
173
      <div class="custom-footer">© 2024 My Company</div>
174
    `;
175
  }
176
  
177
  getUrls(project: ProjectReflection): UrlMapping[] {
178
    const urls = super.getUrls(project);
179
    
180
    // Add custom pages
181
    urls.push({
182
      url: "custom-page.html",
183
      template: this.customPageTemplate,
184
      model: { title: "Custom Page", content: "Custom content" }
185
    });
186
    
187
    return urls;
188
  }
189
  
190
  private customPageTemplate = (page: PageEvent<any>) => {
191
    return `<h1>${page.model.title}</h1><p>${page.model.content}</p>`;
192
  };
193
}
194

195
// Register custom theme
196
app.renderer.theme = new CustomTheme(app.renderer);
197
```
198

199
### Routing System
200

201
URL routing system that determines how reflections map to output files and URLs.
202

203
```typescript { .api }
204
/**
205
 * Base router interface for URL generation
206
 */
207
interface Router {
208
  /**
209
   * Get URL for reflection
210
   * @param reflection - Reflection to get URL for
211
   * @returns URL string or undefined
212
   */
213
  getUrl(reflection: Reflection): string | undefined;
214
  
215
  /**
216
   * Get all URL mappings
217
   * @param project - Project reflection
218
   * @returns Array of URL mappings
219
   */
220
  getUrls(project: ProjectReflection): UrlMapping[];
221
}
222

223
/**
224
 * Base router implementation
225
 */
226
class BaseRouter implements Router {
227
  /** Application instance */
228
  readonly application: Application;
229
  
230
  getUrl(reflection: Reflection): string | undefined;
231
  getUrls(project: ProjectReflection): UrlMapping[];
232
  
233
  /**
234
   * Build URL mapping for reflection
235
   * @param reflection - Reflection to map
236
   * @param template - Template to use
237
   * @returns URL mapping
238
   */
239
  buildUrlMapping(
240
    reflection: Reflection, 
241
    template: RenderTemplate<PageEvent<Reflection>>
242
  ): UrlMapping;
243
}
244

245
/**
246
 * Router that organizes output by reflection kind
247
 */
248
class KindRouter extends BaseRouter {
249
  /** Generate URLs with kind-based prefixes */
250
  getUrl(reflection: Reflection): string | undefined;
251
}
252

253
/**
254
 * Router that creates directories by reflection kind
255
 */
256
class KindDirRouter extends BaseRouter {
257
  /** Generate URLs with kind-based directory structure */
258
  getUrl(reflection: Reflection): string | undefined;
259
}
260

261
/**
262
 * Router that organizes by category
263
 */
264
class CategoryRouter extends BaseRouter {
265
  /** Generate URLs with category-based organization */
266
  getUrl(reflection: Reflection): string | undefined;
267
}
268

269
/**
270
 * Router that organizes by group
271
 */
272
class GroupRouter extends BaseRouter {
273
  /** Generate URLs with group-based organization */
274
  getUrl(reflection: Reflection): string | undefined;
275
}
276

277
/**
278
 * Router that uses project structure for URLs
279
 */
280
class StructureRouter extends BaseRouter {
281
  /** Generate URLs following source structure */
282
  getUrl(reflection: Reflection): string | undefined;
283
}
284

285
/**
286
 * Router that creates directories following project structure
287
 */
288
class StructureDirRouter extends BaseRouter {
289
  /** Generate URLs with directory structure matching source */
290
  getUrl(reflection: Reflection): string | undefined;
291
}
292
```
293

294
### Page Generation
295

296
System for generating pages and managing page events during rendering.
297

298
```typescript { .api }
299
/**
300
 * Event fired for each page being rendered
301
 */
302
class PageEvent<Model = Reflection> extends Event {
303
  /** URL for this page */
304
  url: string;
305
  /** Data model for the page */
306
  model: Model;
307
  /** Page template */
308
  template: RenderTemplate<PageEvent<Model>>;
309
  /** Project being rendered */
310
  project: ProjectReflection;
311
  /** Rendered page contents */
312
  contents?: string;
313
  /** Page filename */
314
  filename: string;
315
  
316
  /**
317
   * Create page event
318
   * @param name - Page name
319
   * @param model - Page data model
320
   * @param url - Page URL
321
   * @param template - Rendering template
322
   */
323
  constructor(
324
    name: string,
325
    model: Model,
326
    url: string, 
327
    template: RenderTemplate<PageEvent<Model>>
328
  );
329
}
330

331
/**
332
 * Types of pages that can be generated
333
 */
334
enum PageKind {
335
  Document = "document",
336
  Module = "module", 
337
  Namespace = "namespace",
338
  Class = "class",
339
  Interface = "interface",
340
  Enum = "enum",
341
  Function = "function",
342
  Variable = "variable",
343
  TypeAlias = "typealias",
344
  Index = "index",
345
  Hierarchy = "hierarchy",
346
  Search = "search",
347
}
348

349
/**
350
 * Page definition for routing
351
 */
352
interface PageDefinition {
353
  /** Page kind */
354
  kind: PageKind;
355
  /** URL pattern */
356
  url: string;
357
  /** Template function */
358
  template: RenderTemplate<PageEvent<Reflection>>;
359
  /** Page title pattern */
360
  title?: string;
361
}
362

363
/**
364
 * Router target for URL mapping
365
 */
366
interface RouterTarget {
367
  /** Target reflection */
368
  reflection: Reflection;
369
  /** Target URL */
370
  url: string;
371
  /** Page kind */
372
  kind: PageKind;
373
}
374

375
/**
376
 * URL mapping result
377
 */
378
interface UrlMapping {
379
  /** Target URL */
380
  url: string;
381
  /** Page template */
382
  template: RenderTemplate<PageEvent<any>>;
383
  /** Page model/data */
384
  model: any;
385
}
386
```
387

388
### Navigation System
389

390
Navigation structure generation and management for documentation sites.
391

392
```typescript { .api }
393
/**
394
 * Navigation element in the documentation structure
395
 */
396
interface NavigationElement {
397
  /** Element title */
398
  title: string;
399
  /** Element URL */
400
  url?: string;
401
  /** Child navigation elements */
402
  children?: NavigationElement[];
403
  /** CSS classes for styling */
404
  cssClasses?: string;
405
  /** Whether element is expanded */
406
  expanded?: boolean;
407
  /** Associated reflection */
408
  reflection?: Reflection;
409
}
410

411
/**
412
 * Page heading structure
413
 */
414
interface PageHeading {
415
  /** Heading level (1-6) */
416
  level: number;
417
  /** Heading text */
418
  title: string;
419
  /** Heading anchor/ID */
420
  anchor: string;
421
  /** CSS classes */
422
  cssClasses?: string;
423
}
424
```
425

426
### Template System
427

428
Template system for rendering HTML content with JSX support.
429

430
```typescript { .api }
431
/**
432
 * Template function type for rendering pages
433
 */
434
type RenderTemplate<T extends PageEvent<any>> = (data: T) => string;
435

436
/**
437
 * Icons interface for theme customization
438
 */
439
interface Icons {
440
  /** Icon for modules */
441
  module: string;
442
  /** Icon for classes */
443
  class: string;
444
  /** Icon for interfaces */
445
  interface: string;
446
  /** Icon for enums */
447
  enum: string;
448
  /** Icon for functions */
449
  function: string;
450
  /** Icon for variables */
451
  variable: string;
452
  /** Icon for type aliases */
453
  typeAlias: string;
454
  /** Icon for properties */
455
  property: string;
456
  /** Icon for methods */
457
  method: string;
458
  /** Icon for constructors */
459
  constructor: string;
460
  /** Icon for accessors */
461
  accessor: string;
462
  /** Icon for parameters */
463
  parameter: string;
464
  /** Search icon */
465
  search: string;
466
  /** Menu icon */
467
  menu: string;
468
  /** Chevron icons for navigation */
469
  chevronDown: string;
470
  chevronSmall: string;
471
}
472

473
/**
474
 * Default theme render context
475
 */
476
class DefaultThemeRenderContext {
477
  /** Icon set */
478
  icons: Icons;
479
  /** Hook functions for customization */
480
  hooks: RendererHooks;
481
  
482
  /**
483
   * Render reflection as HTML
484
   * @param reflection - Reflection to render
485
   * @returns HTML string
486
   */
487
  reflectionTemplate(reflection: Reflection): string;
488
  
489
  /**
490
   * Render navigation
491
   * @param navigation - Navigation structure
492
   * @returns HTML string
493
   */
494
  navigationTemplate(navigation: NavigationElement): string;
495
  
496
  /**
497
   * Render page header
498
   * @param page - Page event
499
   * @returns HTML string
500
   */
501
  headerTemplate(page: PageEvent<Reflection>): string;
502
  
503
  /**
504
   * Render page footer
505
   * @param page - Page event  
506
   * @returns HTML string
507
   */
508
  footerTemplate(page: PageEvent<Reflection>): string;
509
}
510
```
511

512
### URL Slug Generation
513

514
Utility for generating URL-safe slugs from reflection names.
515

516
```typescript { .api }
517
/**
518
 * URL slug generator with collision handling
519
 */
520
class Slugger {
521
  /**
522
   * Generate URL slug from text
523
   * @param text - Text to convert to slug
524
   * @returns URL-safe slug
525
   */
526
  slug(text: string): string;
527
  
528
  /**
529
   * Reset slug generator state
530
   */
531
  reset(): void;
532
  
533
  /**
534
   * Check if slug already exists
535
   * @param slug - Slug to check
536
   * @returns True if slug exists
537
   */
538
  hasSlug(slug: string): boolean;
539
}
540
```
541

542
### Output Management
543

544
System for managing multiple output formats and destinations.
545

546
```typescript { .api }
547
/**
548
 * Output format management
549
 */
550
class Outputs {
551
  /** Application instance */
552
  readonly application: Application;
553
  
554
  /**
555
   * Add output format
556
   * @param name - Output format name
557
   * @param output - Output function
558
   */
559
  addOutput(
560
    name: string,
561
    output: (path: string, project: ProjectReflection) => Promise<void>
562
  ): void;
563
  
564
  /**
565
   * Set default output format name
566
   * @param name - Default output name
567
   */
568
  setDefaultOutputName(name: string): void;
569
  
570
  /**
571
   * Get output specifications from configuration
572
   * @returns Array of output specifications
573
   */
574
  getOutputSpecs(): OutputSpecification[];
575
  
576
  /**
577
   * Generate all configured outputs
578
   * @param project - Project to output
579
   * @param logger - Logger for messages
580
   */
581
  async generate(project: ProjectReflection, logger: Logger): Promise<void>;
582
}
583

584
/**
585
 * Output specification
586
 */
587
interface OutputSpecification {
588
  /** Output name/format */
589
  name: string;
590
  /** Output path */
591
  path: string;
592
  /** Format-specific options */
593
  options?: Partial<TypeDocOptions>;
594
}
595
```
596

597
## Renderer Events
598

599
Events fired during the rendering process for customization and plugin integration.
600

601
```typescript { .api }
602
/**
603
 * Events fired during rendering
604
 */
605
interface RendererEvents {
606
  /** Begin rendering process */
607
  BEGIN: [RendererEvent];
608
  /** End rendering process */
609
  END: [RendererEvent];
610
  /** Begin rendering page */
611
  BEGIN_PAGE: [PageEvent<Reflection>];
612
  /** End rendering page */
613
  END_PAGE: [PageEvent<Reflection>];
614
  /** Markdown content processing */
615
  MARK_DOWN: [MarkdownEvent];
616
  /** Index generation */
617
  INDEX: [IndexEvent];
618
}
619

620
/**
621
 * Renderer hooks for customization
622
 */
623
interface RendererHooks {
624
  /** Custom head content injection */
625
  head: (context: DefaultThemeRenderContext) => string;
626
  /** Custom body content injection */
627
  body: (context: DefaultThemeRenderContext) => string;
628
  /** Custom sidebar content */
629
  sidebar: (context: DefaultThemeRenderContext) => string;
630
}
631

632
/**
633
 * Base renderer event
634
 */
635
class RendererEvent extends Event {
636
  /** Project being rendered */
637
  readonly project: ProjectReflection;
638
  /** Output directory */
639
  readonly outputDirectory: string;
640
  /** URL mappings */
641
  readonly urls: UrlMapping[];
642
}
643

644
/**
645
 * Markdown processing event
646
 */
647
class MarkdownEvent extends Event {
648
  /** Original markdown content */
649
  readonly parsedText: string;
650
  /** Processed markdown content */
651
  outputText: string;
652
  /** Source reflection */
653
  readonly reflection?: Reflection;
654
}
655

656
/**
657
 * Index generation event
658
 */
659
class IndexEvent extends Event {
660
  /** Search index data */
661
  readonly searchResults: any[];
662
  /** Index file content */
663
  indexContent: string;
664
}
665
```
666

667
**Usage Examples:**
668

669
```typescript
670
import { Application, RendererEvents } from "typedoc";
671

672
const app = await Application.bootstrap();
673

674
// Customize rendering process
675
app.renderer.on("beginPage", (page) => {
676
  console.log(`Rendering: ${page.url}`);
677
  
678
  // Add custom data to page
679
  if (page.model.kind === ReflectionKind.Class) {
680
    page.model.customData = "This is a class";
681
  }
682
});
683

684
app.renderer.on("markDown", (event) => {
685
  // Process markdown content
686
  event.outputText = event.parsedText.replace(
687
    /TODO:/g,
688
    '<span class="todo">TODO:</span>'
689
  );
690
});
691

692
app.renderer.on("endPage", (page) => {
693
  // Post-process rendered content
694
  if (page.contents) {
695
    page.contents = page.contents.replace(
696
      /<h1>/g,
697
      '<h1 class="custom-heading">'
698
    );
699
  }
700
});
701
```
702

703
## Error Handling
704

705
The output system handles various error conditions:
706

707
- **File System Errors**: Permission issues, disk space, invalid paths
708
- **Template Errors**: Missing templates, template compilation failures, JSX errors  
709
- **Theme Errors**: Theme loading failures, missing resources, CSS/JS errors
710
- **URL Generation**: Slug collisions, invalid characters, path length limits
711
- **Content Processing**: Markdown parsing errors, image loading failures, broken links
712

713
All errors are logged with detailed context about the failing operation and source reflection.