0
# Theme System
1

2
Custom theme implementation that controls how TypeDoc models are rendered as markdown files, providing complete customization support through contexts, templates, and rendering hooks.
3

4
## Capabilities
5

6
### MarkdownTheme Class
7

8
The main theme class that controls how TypeDoc models are mapped to files and templates.
9

10
```typescript { .api }
11
/**
12
 * The main theme class for the plugin that controls how TypeDoc models 
13
 * are mapped to files and templates for markdown generation
14
 */
15
class MarkdownTheme extends Theme {
16
  /** The router instance used for file organization */
17
  router: Router;
18
  
19
  /**
20
   * Creates a new markdown theme instance
21
   * @param renderer - The TypeDoc renderer instance
22
   */
23
  constructor(renderer: Renderer);
24
  
25
  /**
26
   * Renders a template and page model to a markdown string
27
   * @param page - The page event containing model and context
28
   * @returns Rendered markdown content
29
   */
30
  render(page: MarkdownPageEvent): string;
31
  
32
  /**
33
   * Gets navigation structure for the project
34
   * @param project - The TypeDoc project reflection
35
   * @returns Navigation item hierarchy
36
   */
37
  getNavigation(project: ProjectReflection): NavigationItem[];
38
  
39
  /**
40
   * Gets the render context for a specific page
41
   * @param page - The page event for a reflection
42
   * @returns Theme context with templates, partials, and helpers
43
   */
44
  getRenderContext(page: MarkdownPageEvent<Reflection>): MarkdownThemeContext;
45
  
46
  /**
47
   * Renders the main index template for projects
48
   * @param page - Page event for project reflection
49
   * @returns Rendered index markdown
50
   */
51
  indexTemplate(page: MarkdownPageEvent<ProjectReflection>): string;
52
  
53
  /**
54
   * Renders template for declaration reflections (classes, interfaces, etc.)
55
   * @param page - Page event for declaration reflection
56
   * @returns Rendered declaration markdown
57
   */
58
  reflectionTemplate(page: MarkdownPageEvent<DeclarationReflection>): string;
59
  
60
  /**
61
   * Renders template for document reflections (readme files, etc.)
62
   * @param page - Page event for document reflection
63
   * @returns Rendered document markdown
64
   */
65
  documentTemplate(page: MarkdownPageEvent<DocumentReflection>): string;
66
  
67
  /**
68
   * Renders hierarchy template showing class/interface inheritance
69
   * @param page - Page event for project reflection
70
   * @returns Rendered hierarchy markdown
71
   */
72
  hierarchyTemplate(page: MarkdownPageEvent<ProjectReflection>): string;
73
}
74
```
75

76
**Usage Example:**
77

78
```typescript
79
import { MarkdownTheme } from "typedoc-plugin-markdown";
80
import { Renderer } from "typedoc";
81

82
// Create custom theme
83
class CustomMarkdownTheme extends MarkdownTheme {
84
  constructor(renderer: Renderer) {
85
    super(renderer);
86
  }
87
  
88
  // Override rendering behavior
89
  render(page: MarkdownPageEvent): string {
90
    const context = this.getRenderContext(page);
91
    
92
    // Custom rendering logic
93
    let content = super.render(page);
94
    content = `<!-- Custom Header -->\n${content}`;
95
    
96
    return content;
97
  }
98
}
99

100
// Register custom theme
101
renderer.defineTheme('custom-markdown', CustomMarkdownTheme);
102
```
103

104
### MarkdownThemeContext Class
105

106
The theme context class that provides context and utilities for rendering every page.
107

108
```typescript { .api }
109
/**
110
 * The theme context class that provides context on the rendering of every page.
111
 * Contains templates, partials, helpers, and utility functions for markdown generation.
112
 */
113
class MarkdownThemeContext {
114
  /** The markdown router instance for URL generation */
115
  public router: Router;
116
  
117
  /** The theme instance */
118
  readonly theme: MarkdownTheme;
119
  
120
  /** The current page event being rendered */
121
  readonly page: MarkdownPageEvent<Reflection>;
122
  
123
  /** The options provided to the application */
124
  readonly options: Options;
125
  
126
  /** The templates namespace with main page templates */
127
  templates: any;
128
  
129
  /** The partials namespace with component partials */
130
  partials: any;
131
  
132
  /** The helpers namespace with utility functions */
133
  helpers: any;
134
  
135
  /** Hook into TypeDoc rendering system */
136
  hook: MarkdownRenderer['markdownHooks']['emit'];
137
  
138
  /**
139
   * Creates a new theme context instance
140
   * @param theme - The markdown theme instance
141
   * @param page - The current page event
142
   * @param options - TypeDoc options
143
   */
144
  constructor(
145
    theme: MarkdownTheme, 
146
    page: MarkdownPageEvent<Reflection>, 
147
    options: Options
148
  );
149
  
150
  /**
151
   * Gets package metadata for a specific package name
152
   * @param packageName - Name of the package
153
   * @returns Package metadata or undefined if not found
154
   */
155
  getPackageMetaData(packageName: string): PackageMetaData | undefined;
156
  
157
  /**
158
   * Returns the number of packages in the project (for packages mode)
159
   * @returns Number of packages
160
   */
161
  getPackagesCount(): number;
162
  
163
  /**
164
   * Returns a URL relative to the current page
165
   * @param url - The absolute URL to make relative
166
   * @returns Relative URL string
167
   */
168
  relativeURL(url: string): string;
169
  
170
  /**
171
   * Returns the relative URL of a given reflection
172
   * @param reflection - The reflection to get URL for
173
   * @returns Relative URL to the reflection
174
   */
175
  urlTo(reflection: Reflection): string;
176
}
177
```
178

179
**Usage Example:**
180

181
```typescript
182
// Using context in custom templates
183
function customTemplate(context: MarkdownThemeContext): string {
184
  const { page, options, helpers, partials } = context;
185
  
186
  // Use helpers for common operations
187
  const title = helpers.getReflectionTitle(page.model);
188
  const toc = partials.toc(page.model);
189
  
190
  // Access current page information
191
  const isIndex = page.pageKind === 'index';
192
  const packageCount = context.getPackagesCount();
193
  
194
  // Generate relative URLs
195
  const homeUrl = context.relativeURL('/');
196
  
197
  return `# ${title}
198
  
199
${toc}
200

201
[Back to Home](${homeUrl})
202
`;
203
}
204
```
205

206
### NavigationBuilder Class
207

208
Builds navigation structure for the documentation site.
209

210
```typescript { .api }
211
/**
212
 * Builds navigation structure for the documentation
213
 */
214
class NavigationBuilder {
215
  /** Router instance for URL generation */
216
  router: Router;
217
  
218
  /** Theme instance */
219
  theme: MarkdownTheme;
220
  
221
  /** Project being documented */
222
  project: ProjectReflection;
223
  
224
  /**
225
   * Creates a new navigation builder
226
   * @param router - Router instance
227
   * @param theme - Theme instance  
228
   * @param project - Project instance
229
   */
230
  constructor(router: Router, theme: MarkdownTheme, project: ProjectReflection);
231
  
232
  /**
233
   * Gets the complete navigation structure for the project
234
   * @returns Hierarchical navigation items
235
   */
236
  getNavigation(): NavigationItem[];
237
}
238
```
239

240
### Theme Resource Functions
241

242
Auto-generated resource functions that bind templates, partials, and helpers to the theme context.
243

244
```typescript { .api }
245
/**
246
 * Returns bound template functions for the theme context
247
 * @param context - The markdown theme context
248
 * @returns Object containing bound template functions
249
 */
250
function resourceTemplates(context: MarkdownThemeContext): any;
251

252
/**
253
 * Returns bound partial functions for the theme context
254
 * @param context - The markdown theme context
255
 * @returns Object containing bound partial functions
256
 */
257
function resourcePartials(context: MarkdownThemeContext): any;
258

259
/**
260
 * Returns bound helper functions for the theme context
261
 * @param context - The markdown theme context
262
 * @returns Object containing bound helper functions
263
 */
264
function resourceHelpers(context: MarkdownThemeContext): any;
265
```
266

267
### Theme Utilities
268

269
Utility functions for common theme operations.
270

271
```typescript { .api }
272
/**
273
 * Gets hierarchy roots from a project for rendering inheritance trees
274
 * @param project - The TypeDoc project
275
 * @returns Root reflections for hierarchy display
276
 */
277
function getHierarchyRoots(project: ProjectReflection): Reflection[];
278

279
/**
280
 * Checks if a section is a "None" section (ungrouped items)
281
 * @param section - The reflection group or category
282
 * @returns True if this is a "None" section
283
 */
284
function isNoneSection(section: ReflectionGroup | ReflectionCategory): boolean;
285

286
/**
287
 * Sorts sections with "None" section appearing first
288
 * @param sections - Array of sections to sort
289
 * @returns Sorted sections with None first
290
 */
291
function sortNoneSectionFirst<T extends ReflectionGroup | ReflectionCategory>(
292
  sections: T[]
293
): T[];
294
```
295

296
**Custom Theme Development Example:**
297

298
```typescript
299
import { 
300
  MarkdownTheme, 
301
  MarkdownThemeContext,
302
  MarkdownPageEvent 
303
} from "typedoc-plugin-markdown";
304

305
class DocumentationTheme extends MarkdownTheme {
306
  constructor(renderer: Renderer) {
307
    super(renderer);
308
  }
309
  
310
  // Customize index page rendering
311
  indexTemplate(page: MarkdownPageEvent<ProjectReflection>): string {
312
    const context = this.getRenderContext(page);
313
    
314
    return `# ${page.model.name} Documentation
315

316
Welcome to the ${page.model.name} API documentation.
317

318
## Quick Navigation
319

320
${this.getNavigation(page.model).map(item => 
321
  `- [${item.title}](${item.path})`
322
).join('\n')}
323

324
## Overview
325

326
${context.helpers.getProjectDescription(page.model)}
327

328
---
329
*Generated with TypeDoc Plugin Markdown*
330
`;
331
  }
332
  
333
  // Add custom CSS classes to code blocks
334
  render(page: MarkdownPageEvent): string {
335
    let content = super.render(page);
336
    
337
    // Add custom styling
338
    content = content.replace(
339
      /```typescript/g, 
340
      '```typescript { .language-typescript .custom-theme }'
341
    );
342
    
343
    return content;
344
  }
345
}
346
```