Merge pull request #1693 from srmagura/nojekyll

Automatically add .nojekyll file to support GitHub Pages

examples/basic/src/index.ts

@@ -0,0 +1,15 @@
+export * from "./access";
+export * from "./classes";
+export * from "./default-export";
+export * from "./enumerations";
+export * from "./flattened";
+export * from "./functions";
+export * from "./generics";
+export * from "./hidden";
+export * from "./markdown";
+export * from "./mixin";
+export * from "./mod";
+export * from "./mod2";
+export * from "./modules";
+export { default as SingleExportedClass } from "./single-export";
+export * from "./weird-names";

examples/basic/tsconfig.json

@@ -5,7 +5,8 @@
         "jsx": "react",
         "experimentalDecorators": true,
         "resolveJsonModule": true,
-        "rootDir": "."
+        "rootDir": ".",
+        "esModuleInterop": true
     },
     "include": ["."]
 }

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.",