Add support for automatically loading themes with "typedoc-theme"

Author: Gerrit0

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 -   TypeDoc will now detect and warn if multiple instances of the package are loaded. This usually means that a plugin has its own version of TypeDoc installed, which will lead to things breaking in unexpected ways.
     It will only work if both loaded TypeDocs are v0.22.9 or later.
+-   TypeDoc will now automatically load packages with `typedoctheme` or `typedoc-theme` in their keywords.
+    Plugins which define a custom theme should include this keyword so that they can be automatically collected and displayed at https://typedoc.org/guides/themes/.
 
 ### Bug Fixes
 

src/lib/application.ts

@@ -11,7 +11,7 @@ import {
     CallbackLogger,
     loadPlugins,
     writeFile,
-    discoverNpmPlugins,
+    discoverPlugins,
     NeverIfInternal,
     TSConfigReader,
 } from "./utils/index";
@@ -135,9 +135,7 @@ export class Application extends ChildableComponent<
         }
         this.logger.level = this.options.getValue("logLevel");
 
-        const plugins = this.options.isSet("plugin")
-            ? this.options.getValue("plugin")
-            : discoverNpmPlugins(this);
+        const plugins = discoverPlugins(this);
         loadPlugins(this, plugins);
 
         this.options.reset();

src/lib/utils/general.ts

@@ -41,7 +41,7 @@ export type NeverIfInternal<T> = IfInternal<never, T>;
 const loadSymbol = Symbol.for("typedoc_loads");
 const getLoads = () => globalThis[loadSymbol as never] || 0;
 
-// @ts-expect-error
+// @ts-expect-error there's no way to add symbols to globalThis, sadly.
 globalThis[loadSymbol] = getLoads() + 1;
 
 export function hasBeenLoadedMultipleTimes() {

src/lib/utils/index.ts

@@ -48,7 +48,7 @@ export type {
     TypeDocOptionValues,
     ParameterTypeToOptionTypeMap,
 } from "./options";
-export { discoverNpmPlugins, loadPlugins } from "./plugins";
+export { discoverPlugins, loadPlugins } from "./plugins";
 export { sortReflections } from "./sort";
 export type { SortStrategy } from "./sort";
 

src/lib/utils/plugins.ts

@@ -37,7 +37,13 @@ export function loadPlugins(app: Application, plugins: readonly string[]) {
     }
 }
 
-export function discoverNpmPlugins(app: Application): string[] {
+export function discoverPlugins(app: Application): string[] {
+    // If the plugin option is set, then automatic discovery is disabled, and we should just
+    // return the plugins that the user has asked for.
+    if (app.options.isSet("plugin")) {
+        return app.options.getValue("plugin");
+    }
+
     const result: string[] = [];
     discover();
     return result;
@@ -100,6 +106,13 @@ function loadPackageInfo(logger: Logger, fileName: string): any {
     }
 }
 
+const PLUGIN_KEYWORDS = [
+    "typedocplugin",
+    "typedoc-plugin",
+    "typedoctheme",
+    "typedoc-theme",
+];
+
 /**
  * Test whether the given package info describes a TypeDoc plugin.
  */
@@ -116,7 +129,7 @@ function isPlugin(info: any): boolean {
     return keywords.some(
         (keyword) =>
             typeof keyword === "string" &&
-            keyword.toLocaleLowerCase() === "typedocplugin"
+            PLUGIN_KEYWORDS.includes(keyword.toLocaleLowerCase())
     );
 }