UNPKG

8.88 kBTypeScriptView Raw
1import type { Application } from "../application.js";
2import type { Theme } from "./theme.js";
3import { RendererEvent, PageEvent, IndexEvent, type MarkdownEvent } from "./events.js";
4import type { ProjectReflection } from "../models/reflections/project.js";
5import { EventHooks, AbstractComponent } from "../utils/index.js";
6import { type Comment, Reflection } from "../models/index.js";
7import type { JsxElement } from "../utils/jsx.elements.js";
8import type { DefaultThemeRenderContext } from "./themes/default/DefaultThemeRenderContext.js";
9import { MarkedPlugin } from "./plugins/index.js";
10/**
11 * Describes the hooks available to inject output in the default theme.
12 * If the available hooks don't let you put something where you'd like, please open an issue!
13 */
14export interface RendererHooks {
15 /**
16 * Applied immediately after the opening `<head>` tag.
17 */
18 "head.begin": [DefaultThemeRenderContext];
19 /**
20 * Applied immediately before the closing `</head>` tag.
21 */
22 "head.end": [DefaultThemeRenderContext];
23 /**
24 * Applied immediately after the opening `<body>` tag.
25 */
26 "body.begin": [DefaultThemeRenderContext];
27 /**
28 * Applied immediately before the closing `</body>` tag.
29 */
30 "body.end": [DefaultThemeRenderContext];
31 /**
32 * Applied immediately before the main template.
33 */
34 "content.begin": [DefaultThemeRenderContext];
35 /**
36 * Applied immediately after the main template.
37 */
38 "content.end": [DefaultThemeRenderContext];
39 /**
40 * Applied immediately before calling `context.sidebar`.
41 */
42 "sidebar.begin": [DefaultThemeRenderContext];
43 /**
44 * Applied immediately after calling `context.sidebar`.
45 */
46 "sidebar.end": [DefaultThemeRenderContext];
47 /**
48 * Applied immediately before calling `context.pageSidebar`.
49 */
50 "pageSidebar.begin": [DefaultThemeRenderContext];
51 /**
52 * Applied immediately after calling `context.pageSidebar`.
53 */
54 "pageSidebar.end": [DefaultThemeRenderContext];
55 /**
56 * Applied immediately before the "Generated by TypeDoc" link in the footer.
57 */
58 "footer.begin": [DefaultThemeRenderContext];
59 /**
60 * Applied immediately after the "Generated by TypeDoc" link in the footer.
61 */
62 "footer.end": [DefaultThemeRenderContext];
63 /**
64 * Applied immediately before a comment's tags are rendered.
65 *
66 * This may be used to set {@link Models.CommentTag.skipRendering} on any tags which
67 * should not be rendered.
68 */
69 "comment.beforeTags": [DefaultThemeRenderContext, Comment, Reflection];
70 /**
71 * Applied immediately after a comment's tags are rendered.
72 *
73 * This may be used to set {@link Models.CommentTag.skipRendering} on any tags which
74 * should not be rendered as this hook is called before the tags are actually
75 * rendered.
76 */
77 "comment.afterTags": [DefaultThemeRenderContext, Comment, Reflection];
78}
79export interface RendererEvents {
80 beginRender: [RendererEvent];
81 beginPage: [PageEvent<Reflection>];
82 endPage: [PageEvent<Reflection>];
83 endRender: [RendererEvent];
84 parseMarkdown: [MarkdownEvent];
85 prepareIndex: [IndexEvent];
86}
87/**
88 * The renderer processes a {@link ProjectReflection} using a {@link Theme} instance and writes
89 * the emitted html documents to a output directory. You can specify which theme should be used
90 * using the `--theme <name>` command line argument.
91 *
92 * {@link Renderer} is a subclass of {@link EventDispatcher} and triggers a series of events while
93 * a project is being processed. You can listen to these events to control the flow or manipulate
94 * the output.
95 *
96 * * {@link Renderer.EVENT_BEGIN}<br>
97 * Triggered before the renderer starts rendering a project. The listener receives
98 * an instance of {@link RendererEvent}.
99 *
100 * * {@link Renderer.EVENT_BEGIN_PAGE}<br>
101 * Triggered before a document will be rendered. The listener receives an instance of
102 * {@link PageEvent}.
103 *
104 * * {@link Renderer.EVENT_END_PAGE}<br>
105 * Triggered after a document has been rendered, just before it is written to disc. The
106 * listener receives an instance of {@link PageEvent}.
107 *
108 * * {@link Renderer.EVENT_END}<br>
109 * Triggered after the renderer has written all documents. The listener receives
110 * an instance of {@link RendererEvent}.
111 *
112 * * {@link Renderer.EVENT_PREPARE_INDEX}<br>
113 * Triggered when the JavascriptIndexPlugin is preparing the search index. Listeners receive
114 * an instance of {@link IndexEvent}.
115 *
116 * @summary Writes HTML output from TypeDoc's models
117 * @group Common
118 */
119export declare class Renderer extends AbstractComponent<Application, RendererEvents> {
120 private themes;
121 /** @event */
122 static readonly EVENT_BEGIN_PAGE = "beginPage";
123 /** @event */
124 static readonly EVENT_END_PAGE = "endPage";
125 /** @event */
126 static readonly EVENT_BEGIN = "beginRender";
127 /** @event */
128 static readonly EVENT_END = "endRender";
129 /** @event */
130 static readonly EVENT_PREPARE_INDEX = "prepareIndex";
131 /**
132 * A list of async jobs which must be completed *before* rendering output.
133 * They will be called after {@link RendererEvent.BEGIN} has fired, but before any files have been written.
134 *
135 * This may be used by plugins to register work that must be done to prepare output files. For example: asynchronously
136 * transform markdown to HTML.
137 *
138 * Note: This array is cleared after calling the contained functions on each {@link Renderer.render} call.
139 */
140 preRenderAsyncJobs: Array<(output: RendererEvent) => Promise<void>>;
141 /**
142 * A list of async jobs which must be completed after rendering output files but before generation is considered successful.
143 * These functions will be called after all documents have been written to the filesystem.
144 *
145 * This may be used by plugins to register work that must be done to finalize output files. For example: asynchronously
146 * generating an image referenced in a render hook.
147 *
148 * Note: This array is cleared after calling the contained functions on each {@link Renderer.render} call.
149 */
150 postRenderAsyncJobs: Array<(output: RendererEvent) => Promise<void>>;
151 /**
152 * The theme that is used to render the documentation.
153 */
154 theme?: Theme;
155 /**
156 * Hooks which will be called when rendering pages.
157 * Note:
158 * - Hooks added during output will be discarded at the end of rendering.
159 * - Hooks added during a page render will be discarded at the end of that page's render.
160 *
161 * See {@link RendererHooks} for a description of each available hook, and when it will be called.
162 */
163 hooks: EventHooks<RendererHooks, JsxElement>;
164 /** @internal */
165 private accessor themeName;
166 private accessor cleanOutputDir;
167 private accessor cname;
168 private accessor githubPages;
169 /** @internal */
170 accessor cacheBust: boolean;
171 private accessor lightTheme;
172 private accessor darkTheme;
173 private accessor highlightLanguages;
174 private accessor ignoredHighlightLanguages;
175 private accessor pretty;
176 renderStartTime: number;
177 markedPlugin: MarkedPlugin;
178 constructor(owner: Application);
179 /**
180 * Define a new theme that can be used to render output.
181 * This API will likely be changing at some point, to allow more easily overriding parts of the theme without
182 * requiring additional boilerplate.
183 * @param name
184 * @param theme
185 */
186 defineTheme(name: string, theme: new (renderer: Renderer) => Theme): void;
187 /**
188 * Render the given project reflection to the specified output directory.
189 *
190 * @param project The project that should be rendered.
191 * @param outputDirectory The path of the directory the documentation should be rendered to.
192 */
193 render(project: ProjectReflection, outputDirectory: string): Promise<void>;
194 private runPreRenderJobs;
195 private loadHighlighter;
196 /**
197 * Render a single page.
198 *
199 * @param page An event describing the current page.
200 * @return TRUE if the page has been saved to disc, otherwise FALSE.
201 */
202 private renderDocument;
203 /**
204 * Ensure that a theme has been setup.
205 *
206 * If a the user has set a theme we try to find and load it. If no theme has
207 * been specified we load the default theme.
208 *
209 * @returns TRUE if a theme has been setup, otherwise FALSE.
210 */
211 private prepareTheme;
212 /**
213 * Prepare the output directory. If the directory does not exist, it will be
214 * created. If the directory exists, it will be emptied.
215 *
216 * @param directory The path to the directory that should be prepared.
217 * @returns TRUE if the directory could be prepared, otherwise FALSE.
218 */
219 private prepareOutputDirectory;
220}