1 | import type { Application } from "../application";
|
2 | import type { Theme } from "./theme";
|
3 | import { RendererEvent, PageEvent, IndexEvent, type MarkdownEvent } from "./events";
|
4 | import type { ProjectReflection } from "../models/reflections/project";
|
5 | import { RendererComponent } from "./components";
|
6 | import { ChildableComponent } from "../utils/component";
|
7 | import { EventHooks } from "../utils";
|
8 | import { type Comment, Reflection } from "../models";
|
9 | import type { JsxElement } from "../utils/jsx.elements";
|
10 | import type { DefaultThemeRenderContext } from "./themes/default/DefaultThemeRenderContext";
|
11 | /**
|
12 | * Describes the hooks available to inject output in the default theme.
|
13 | * If the available hooks don't let you put something where you'd like, please open an issue!
|
14 | */
|
15 | export interface RendererHooks {
|
16 | /**
|
17 | * Applied immediately after the opening `<head>` tag.
|
18 | */
|
19 | "head.begin": [DefaultThemeRenderContext];
|
20 | /**
|
21 | * Applied immediately before the closing `</head>` tag.
|
22 | */
|
23 | "head.end": [DefaultThemeRenderContext];
|
24 | /**
|
25 | * Applied immediately after the opening `<body>` tag.
|
26 | */
|
27 | "body.begin": [DefaultThemeRenderContext];
|
28 | /**
|
29 | * Applied immediately before the closing `</body>` tag.
|
30 | */
|
31 | "body.end": [DefaultThemeRenderContext];
|
32 | /**
|
33 | * Applied immediately before the main template.
|
34 | */
|
35 | "content.begin": [DefaultThemeRenderContext];
|
36 | /**
|
37 | * Applied immediately after the main template.
|
38 | */
|
39 | "content.end": [DefaultThemeRenderContext];
|
40 | /**
|
41 | * Applied immediately before calling `context.sidebar`.
|
42 | */
|
43 | "sidebar.begin": [DefaultThemeRenderContext];
|
44 | /**
|
45 | * Applied immediately after calling `context.sidebar`.
|
46 | */
|
47 | "sidebar.end": [DefaultThemeRenderContext];
|
48 | /**
|
49 | * Applied immediately before calling `context.pageSidebar`.
|
50 | */
|
51 | "pageSidebar.begin": [DefaultThemeRenderContext];
|
52 | /**
|
53 | * Applied immediately after calling `context.pageSidebar`.
|
54 | */
|
55 | "pageSidebar.end": [DefaultThemeRenderContext];
|
56 | /**
|
57 | * Applied immediately before the "Generated by TypeDoc" link in the footer.
|
58 | */
|
59 | "footer.begin": [DefaultThemeRenderContext];
|
60 | /**
|
61 | * Applied immediately after the "Generated by TypeDoc" link in the footer.
|
62 | */
|
63 | "footer.end": [DefaultThemeRenderContext];
|
64 | /**
|
65 | * Applied immediately before a comment's tags are rendered.
|
66 | *
|
67 | * This may be used to set {@link Models.CommentTag.skipRendering} on any tags which
|
68 | * should not be rendered.
|
69 | */
|
70 | "comment.beforeTags": [DefaultThemeRenderContext, Comment, Reflection];
|
71 | /**
|
72 | * Applied immediately after a comment's tags are rendered.
|
73 | *
|
74 | * This may be used to set {@link Models.CommentTag.skipRendering} on any tags which
|
75 | * should not be rendered as this hook is called before the tags are actually
|
76 | * rendered.
|
77 | */
|
78 | "comment.afterTags": [DefaultThemeRenderContext, Comment, Reflection];
|
79 | }
|
80 | export interface RendererEvents {
|
81 | beginRender: [RendererEvent];
|
82 | beginPage: [PageEvent<Reflection>];
|
83 | endPage: [PageEvent<Reflection>];
|
84 | endRender: [RendererEvent];
|
85 | parseMarkdown: [MarkdownEvent];
|
86 | prepareIndex: [IndexEvent];
|
87 | }
|
88 | /**
|
89 | * The renderer processes a {@link ProjectReflection} using a {@link Theme} instance and writes
|
90 | * the emitted html documents to a output directory. You can specify which theme should be used
|
91 | * using the `--theme <name>` command line argument.
|
92 | *
|
93 | * {@link Renderer} is a subclass of {@link EventDispatcher} and triggers a series of events while
|
94 | * a project is being processed. You can listen to these events to control the flow or manipulate
|
95 | * the output.
|
96 | *
|
97 | * * {@link Renderer.EVENT_BEGIN}<br>
|
98 | * Triggered before the renderer starts rendering a project. The listener receives
|
99 | * an instance of {@link RendererEvent}.
|
100 | *
|
101 | * * {@link Renderer.EVENT_BEGIN_PAGE}<br>
|
102 | * Triggered before a document will be rendered. The listener receives an instance of
|
103 | * {@link PageEvent}.
|
104 | *
|
105 | * * {@link Renderer.EVENT_END_PAGE}<br>
|
106 | * Triggered after a document has been rendered, just before it is written to disc. The
|
107 | * listener receives an instance of {@link PageEvent}.
|
108 | *
|
109 | * * {@link Renderer.EVENT_END}<br>
|
110 | * Triggered after the renderer has written all documents. The listener receives
|
111 | * an instance of {@link RendererEvent}.
|
112 | *
|
113 | * * {@link Renderer.EVENT_PREPARE_INDEX}<br>
|
114 | * Triggered when the JavascriptIndexPlugin is preparing the search index. Listeners receive
|
115 | * an instance of {@link IndexEvent}.
|
116 | *
|
117 | * @document ../../../internal-docs/custom-themes.md
|
118 | */
|
119 | export declare class Renderer extends ChildableComponent<Application, RendererComponent, 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 pretty;
|
175 | renderStartTime: number;
|
176 | /**
|
177 | * Define a new theme that can be used to render output.
|
178 | * This API will likely be changing at some point, to allow more easily overriding parts of the theme without
|
179 | * requiring additional boilerplate.
|
180 | * @param name
|
181 | * @param theme
|
182 | */
|
183 | defineTheme(name: string, theme: new (renderer: Renderer) => Theme): void;
|
184 | /**
|
185 | * Render the given project reflection to the specified output directory.
|
186 | *
|
187 | * @param project The project that should be rendered.
|
188 | * @param outputDirectory The path of the directory the documentation should be rendered to.
|
189 | */
|
190 | render(project: ProjectReflection, outputDirectory: string): Promise<void>;
|
191 | private runPreRenderJobs;
|
192 | private loadHighlighter;
|
193 | /**
|
194 | * Render a single page.
|
195 | *
|
196 | * @param page An event describing the current page.
|
197 | * @return TRUE if the page has been saved to disc, otherwise FALSE.
|
198 | */
|
199 | private renderDocument;
|
200 | /**
|
201 | * Ensure that a theme has been setup.
|
202 | *
|
203 | * If a the user has set a theme we try to find and load it. If no theme has
|
204 | * been specified we load the default theme.
|
205 | *
|
206 | * @returns TRUE if a theme has been setup, otherwise FALSE.
|
207 | */
|
208 | private prepareTheme;
|
209 | /**
|
210 | * Prepare the output directory. If the directory does not exist, it will be
|
211 | * created. If the directory exists, it will be emptied.
|
212 | *
|
213 | * @param directory The path to the directory that should be prepared.
|
214 | * @returns TRUE if the directory could be prepared, otherwise FALSE.
|
215 | */
|
216 | private prepareOutputDirectory;
|
217 | }
|
218 | import "./plugins";
|