Automatically add a .nojekyll file to support GitHub Pages

This behavior is controlled by the new githubPages option which defaults to true.

Fixes TypeStrong#1680.

src/lib/output/plugins/index.ts

@@ -1,5 +1,5 @@
 export { AssetsPlugin } from "./AssetsPlugin";
 export { JavascriptIndexPlugin } from "./JavascriptIndexPlugin";
 export { MarkedLinksPlugin } from "./MarkedLinksPlugin";
-export { MarkedPlugin as MarkedPlugin } from "../themes/MarkedPlugin";
+export { MarkedPlugin } from "../themes/MarkedPlugin";
 export { LegendPlugin } from "./LegendPlugin";

src/lib/output/renderer.ts

@@ -8,6 +8,7 @@
  */
 import type * as ts from "typescript";
 import * as fs from "fs";
+import * as path from "path";
 
 import type { Application } from "../application";
 import type { Theme } from "./theme";
@@ -95,6 +96,10 @@ export class Renderer extends ChildableComponent<
     @BindOption("gaSite")
     gaSite!: string;
 
+    /** @internal */
+    @BindOption("githubPages")
+    githubPages!: boolean;
+
     /** @internal */
     @BindOption("hideGenerator")
     hideGenerator!: boolean;
@@ -301,11 +306,27 @@ export class Renderer extends ChildableComponent<
             fs.mkdirSync(directory, { recursive: true });
         } catch (error) {
             this.application.logger.error(
-                `Could not create output directory ${directory}`
+                `Could not create output directory ${directory}.`
             );
             return false;
         }
 
+        if (this.githubPages) {
+            try {
+                const text =
+                    "TypeDoc added this file to prevent GitHub Pages from " +
+                    "using Jekyll. You can turn off this behavior by setting " +
+                    "the `githubPages` option to false.";
+
+                fs.writeFileSync(path.join(directory, ".nojekyll"), text);
+            } catch (error) {
+                this.application.logger.warn(
+                    "Could not create .nojekyll file."
+                );
+                return false;
+            }
+        }
+
         return true;
     }
 }

src/lib/utils/options/declaration.ts

@@ -86,6 +86,7 @@ export interface TypeDocOptionMap {
     gitRemote: string;
     gaID: string;
     gaSite: string;
+    githubPages: boolean;
     hideGenerator: boolean;
     hideLegend: boolean;
     cleanOutputDir: boolean;

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

@@ -248,6 +248,12 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         help: "Set the site name for Google Analytics. Defaults to `auto`.",
         defaultValue: "auto",
     });
+    options.addDeclaration({
+        name: "githubPages",
+        help: "Generate a .nojekyll file to prevent 404 errors in GitHub Pages. Defaults to `true`.",
+        type: ParameterType.Boolean,
+        defaultValue: true,
+    });
     options.addDeclaration({
         name: "hideGenerator",
         help: "Do not print the TypeDoc link at the end of the page.",