Introduce cacheBust option

Closes #2124

Author: Gerrit0

CHANGELOG.md

@@ -44,7 +44,8 @@
 -   TypeDoc will now produce more informative error messages for options which cannot be set from the cli, #2022.
 -   TypeDoc will now attempt to guess what option you may have meant if given an invalid option name.
 -   TypeDoc options may now be set under the `typedocOptions` key in `package.json`, #2112.
--   Moved sidebar to left of content for consistency with most other websites, #2189
+-   Moved sidebar to left of content for consistency with most other websites, #2189.
+-   Added `--cacheBust` option to tell TypeDoc to include include the generation time in files, #2124.
 
 ### Bug Fixes
 

src/lib/output/renderer.ts

@@ -179,6 +179,10 @@ export class Renderer extends ChildableComponent<
     @BindOption("githubPages")
     githubPages!: boolean;
 
+    /** @internal */
+    @BindOption("cacheBust")
+    cacheBust!: boolean;
+
     /** @internal */
     @BindOption("lightHighlightTheme")
     lightTheme!: ShikiTheme;
@@ -187,6 +191,8 @@ export class Renderer extends ChildableComponent<
     @BindOption("darkHighlightTheme")
     darkTheme!: ShikiTheme;
 
+    renderStartTime = -1;
+
     /**
      * Define a new theme that can be used to render output.
      * This API will likely be changing at some point, to allow more easily overriding parts of the theme without
@@ -212,10 +218,12 @@ export class Renderer extends ChildableComponent<
         outputDirectory: string
     ): Promise<void> {
         const momento = this.hooks.saveMomento();
-        const start = Date.now();
+        this.renderStartTime = Date.now();
         await loadHighlighter(this.lightTheme, this.darkTheme);
         this.application.logger.verbose(
-            `Renderer: Loading highlighter took ${Date.now() - start}ms`
+            `Renderer: Loading highlighter took ${
+                Date.now() - this.renderStartTime
+            }ms`
         );
         if (
             !this.prepareTheme() ||

src/lib/output/themes/default/DefaultThemeRenderContext.ts

@@ -60,11 +60,17 @@ export class DefaultThemeRenderContext {
         this.theme.owner.hooks.emit(name, this);
 
     /** Avoid this in favor of urlTo if possible */
-    relativeURL = (url: string | undefined) => {
-        return url ? this.theme.markedPlugin.getRelativeUrl(url) : url;
+    relativeURL = (url: string, cacheBust = false) => {
+        const result = this.theme.markedPlugin.getRelativeUrl(url);
+        if (cacheBust && this.theme.owner.cacheBust) {
+            return result + `?cache=${this.theme.owner.renderStartTime}`;
+        }
+        return result;
     };
 
-    urlTo = (reflection: Reflection) => this.relativeURL(reflection.url)!;
+    urlTo = (reflection: Reflection) => {
+        return reflection.url ? this.relativeURL(reflection.url) : "";
+    };
 
     markdown = (
         md: readonly CommentDisplayPart[] | NeverIfInternal<string | undefined>

src/lib/output/themes/default/layouts/default.tsx

@@ -17,12 +17,12 @@ export const defaultLayout = (context: DefaultThemeRenderContext, props: PageEve
             <meta name="description" content={"Documentation for " + props.project.name} />
             <meta name="viewport" content="width=device-width, initial-scale=1" />
 
-            <link rel="stylesheet" href={context.relativeURL("assets/style.css")} />
-            <link rel="stylesheet" href={context.relativeURL("assets/highlight.css")} />
+            <link rel="stylesheet" href={context.relativeURL("assets/style.css", true)} />
+            <link rel="stylesheet" href={context.relativeURL("assets/highlight.css", true)} />
             {context.options.getValue("customCss") && (
-                <link rel="stylesheet" href={context.relativeURL("assets/custom.css")} />
+                <link rel="stylesheet" href={context.relativeURL("assets/custom.css", true)} />
             )}
-            <script async src={context.relativeURL("assets/search.js")} id="search-script"></script>
+            <script async src={context.relativeURL("assets/search.js", true)} id="search-script"></script>
             {context.hook("head.end")}
         </head>
         <body>
@@ -49,7 +49,7 @@ export const defaultLayout = (context: DefaultThemeRenderContext, props: PageEve
             {context.footer()}
 
             <div class="overlay"></div>
-            <script src={context.relativeURL("assets/main.js")}></script>
+            <script src={context.relativeURL("assets/main.js", true)}></script>
 
             {context.analytics()}
             {context.hook("body.end")}

src/lib/utils/options/declaration.ts

@@ -130,6 +130,7 @@ export interface TypeDocOptionMap {
     githubPages: boolean;
     gaID: string;
     hideGenerator: boolean;
+    cacheBust: boolean;
     searchInComments: boolean;
     cleanOutputDir: boolean;
     titleLink: string;

src/lib/utils/options/sources/typedoc.ts

@@ -362,6 +362,11 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         help: "Do not print the TypeDoc link at the end of the page.",
         type: ParameterType.Boolean,
     });
+    options.addDeclaration({
+        name: "cacheBust",
+        help: "Include the generation time in links to static assets.",
+        type: ParameterType.Boolean,
+    });
     options.addDeclaration({
         name: "searchInComments",
         help: "If set, the search index will also include comments. This will greatly increase the size of the search index.",