fix: Handle TypeDoc 0.21.3 options breaking change

packages/typedoc-plugin-markdown/src/index.ts

@@ -1,11 +1,16 @@
-import * as fs from 'fs';
 import * as path from 'path';
 
-import { Application, Converter, ParameterType, Renderer } from 'typedoc';
+import { Application, ParameterType } from 'typedoc';
 
+import { CustomOptionsReader } from './options-reader';
 import MarkdownTheme from './theme';
 
 export function load(app: Application) {
+  addDeclarations(app);
+  loadTheme(app);
+}
+
+function addDeclarations(app: Application) {
   app.options.addDeclaration({
     help: '[Markdown Plugin] Do not render page title.',
     name: 'hidePageTitle',
@@ -21,23 +26,20 @@ export function load(app: Application) {
   });
 
   app.options.addDeclaration({
-    help:
-      '[Markdown Plugin] Specifies the base path that all links to be served from. If omitted all urls will be relative.',
+    help: '[Markdown Plugin] Specifies the base path that all links to be served from. If omitted all urls will be relative.',
     name: 'publicPath',
     type: ParameterType.String,
   });
 
   app.options.addDeclaration({
-    help:
-      '[Markdown Plugin] Use HTML named anchors as fragment identifiers for engines that do not automatically assign header ids. Should be set for Bitbucket Server docs.',
+    help: '[Markdown Plugin] Use HTML named anchors as fragment identifiers for engines that do not automatically assign header ids. Should be set for Bitbucket Server docs.',
     name: 'namedAnchors',
     type: ParameterType.Boolean,
     defaultValue: false,
   });
 
   app.options.addDeclaration({
-    help:
-      '[Markdown Plugin] Output all reflections into seperate output files.',
+    help: '[Markdown Plugin] Output all reflections into seperate output files.',
     name: 'allReflectionsHaveOwnDocument',
     type: ParameterType.Boolean,
     defaultValue: false,
@@ -69,37 +71,35 @@ export function load(app: Application) {
     name: 'indexTitle',
     type: ParameterType.String,
   });
+}
 
-  app.converter.on(Converter.EVENT_BEGIN, () => {
-    Renderer.getDefaultTheme = () => path.join(__dirname, 'resources');
-  });
-
-  app.converter.on(Converter.EVENT_RESOLVE_BEGIN, () => {
-    const themeName = app.options.getValue('theme');
-
-    const themeDir = path.join(__dirname);
-
-    if (![themeDir, 'default', 'markdown'].includes(themeName)) {
-      // For custom themes check that the theme is a markdown theme
-      // If it is return and pass through to renderer
-      const themeFileName = path.resolve(path.join(themeName, 'theme.js'));
-      if (fs.existsSync(themeFileName) && isMarkdownTheme(themeFileName)) {
-        return;
-      }
+function loadTheme(app: Application) {
+  const themeRef = app.options.getValue('theme');
+  const themeDir = path.join(__dirname);
+  const basePath = themeDir + '/resources';
+
+  if ([themeDir, 'default', 'markdown'].includes(themeRef)) {
+    app.renderer.theme = new MarkdownTheme(app.renderer, basePath);
+  } else {
+    const CustomTheme = getCustomTheme(
+      path.resolve(path.join(themeRef, 'theme.js')),
+    );
+    if (CustomTheme !== null) {
+      app.options.addReader(new CustomOptionsReader());
+      app.renderer.theme = new CustomTheme(app.renderer, basePath);
+    } else {
       app.logger.warn(
-        `[typedoc-plugin-markdown] '${themeName}' is not a recognised markdown theme. If an html theme is required, please disable this plugin.`,
+        `[typedoc-plugin-markdown] '${themeRef}' is not a recognised markdown theme.`,
       );
     }
-
-    app.options.setValue('theme', themeDir);
-  });
+  }
 }
 
-function isMarkdownTheme(themeFileName: string) {
+function getCustomTheme(themeFile: string) {
   try {
-    const ThemeClass = require(themeFileName).default;
-    return ThemeClass.prototype instanceof MarkdownTheme;
+    const ThemeClass = require(themeFile).default;
+    return ThemeClass.prototype instanceof MarkdownTheme ? ThemeClass : null;
   } catch (e) {
-    return false;
+    return null;
   }
 }

packages/typedoc-plugin-markdown/src/options-reader.ts

@@ -0,0 +1,29 @@
+import * as path from 'path';
+
+import { Options, OptionsReader } from 'typedoc';
+import { Logger } from 'typedoc/dist/lib/utils';
+
+export class CustomOptionsReader implements OptionsReader {
+  priority = 900;
+
+  name = 'custom-options';
+
+  read(container: Options, logger: Logger) {
+    const options = this.getOptionsFile(
+      path.resolve(path.join(container.getValue('theme'), 'options.js')),
+    );
+    if (options) {
+      Object.entries(options).forEach(([key, value]) => {
+        container.setValue(key, value);
+      });
+    }
+  }
+
+  getOptionsFile(optionsFile: string) {
+    try {
+      return require(optionsFile).default;
+    } catch (e) {
+      return null;
+    }
+  }
+}

packages/typedoc-plugin-markdown/src/theme.ts

@@ -38,7 +38,7 @@ export default class MarkdownTheme extends Theme {
   @BindOption('filenameSeparator')
   filenameSeparator!: string;
   @BindOption('entryDocument')
-  entryDocument!: string;
+  entryDocument: string;
 
   // creates an isolated Handlebars environment to store context aware helpers
   static HANDLEBARS = Handlebars.create();
@@ -237,12 +237,8 @@ export default class MarkdownTheme extends Theme {
       const navigationItem = new NavigationItem(title, url);
       navigationItem.isLabel = isLabel;
       navigationItem.children = children;
-      const {
-        reflection,
-        parent,
-        cssClasses,
-        ...filteredNavigationItem
-      } = navigationItem;
+      const { reflection, parent, cssClasses, ...filteredNavigationItem } =
+        navigationItem;
       return filteredNavigationItem as NavigationItem;
     };
     const navigation = createNavigationItem(project.name, undefined, false);

packages/typedoc-plugin-markdown/test/specs/__snapshots__/comments.spec.ts.snap

@@ -11,7 +11,7 @@ You can write <strong>HTML</strong> tags directly in comments
 `;
 
 exports[`Comments: should build @link references' 1`] = `
-"See [\`CommentClass\`](commentclass.md) and [CommentClass's comment property](commentclass.md#comment).
+"See [\`CommentClass\`](CommentClass.md) and [CommentClass's comment property](CommentClass.md#comment).
 Also, check out [Google](https://www.google.com) and
 [GitHub](https://github.com).
 
@@ -61,7 +61,7 @@ Another tag description
 exports[`Comments: should convert symbols brackets to symbol links' 1`] = `
 "Additionally you can link to other classes, members or functions using double square brackets.
 
-- Link to an external reflection: [CommentClass](commentclass.md)
+- Link to an external reflection: [CommentClass](CommentClass.md)
 - Link to an internal reflection: [commentsInReturn](../modules.md#commentsinreturn)
 - Link to an undefined reflection: [[VOID]]
 "

packages/typedoc-plugin-markdown/test/specs/__snapshots__/generics.spec.ts.snap

@@ -46,7 +46,7 @@ exports[`Generics: should compile function with complex type params' 1`] = `
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| \`A\` | extends [\`ClassWithTypeParams\`](classwithtypeparams.md)<\`string\`, \`number\`, \`A\`\\\\> | Comment for type \`A\` |
+| \`A\` | extends [\`ClassWithTypeParams\`](ClassWithTypeParams.md)<\`string\`, \`number\`, \`A\`\\\\> | Comment for type \`A\` |
 | \`B\` | \`string\` \\\\| \`boolean\` | Comment for type \`B\` |
 | \`C\` | \`string\` | - |
 

packages/typedoc-plugin-markdown/test/specs/__snapshots__/hierarchy.spec.ts.snap

@@ -1,19 +1,19 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`Hierarchy: should compile nested type hierarchy 1`] = `
-"- [\`ParentClass\`](parentclass.md)
+"- [\`ParentClass\`](ParentClass.md)
 
   ↳ **\`ChildClassA\`**
 
-  ↳↳ [\`GrandChildClassA\`](grandchildclassa.md)
+  ↳↳ [\`GrandChildClassA\`](GrandChildClassA.md)
 "
 `;
 
 exports[`Hierarchy: should compile type hierarchy 1`] = `
 "- **\`ParentClass\`**
 
-  ↳ [\`ChildClassA\`](childclassa.md)
+  ↳ [\`ChildClassA\`](ChildClassA.md)
 
-  ↳ [\`ChildClassB\`](childclassb.md)
+  ↳ [\`ChildClassB\`](ChildClassB.md)
 "
 `;

packages/typedoc-plugin-markdown/test/specs/__snapshots__/options.spec.ts.snap

@@ -1,5 +1,5 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`Options: (defaults) should compile relativeURL helper 1`] = `"breadcrumbs.md"`;
+exports[`Options: (defaults) should compile relativeURL helper 1`] = `"Breadcrumbs.md"`;
 
-exports[`Options: (with plugin options) should compile relativeURL helper with public path 1`] = `"test-public-pathclasses/breadcrumbs.md"`;
+exports[`Options: (with plugin options) should compile relativeURL helper with public path 1`] = `"test-public-pathclasses/Breadcrumbs.md"`;

packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflections.spec.ts.snap

@@ -12,7 +12,14 @@ exports[`Reflections: (header) should compile template with breadcrumbs and with
 exports[`Reflections: (template) should compile Enum 1`] = `
 "# Enumeration: EnumReflection
 
-[helper: toc]
+## Table of contents
+
+### Enumeration members
+
+- [Down](../enums/EnumReflection.md#down)
+- [Left](../enums/EnumReflection.md#left)
+- [Right](../enums/EnumReflection.md#right)
+- [Up](../enums/EnumReflection.md#up)
 
 [partial: members]
 "
@@ -27,8 +34,6 @@ exports[`Reflections: (template) should compile a callable reflection 1`] = `
 
 [partial: member.signature]
 
-[helper: toc]
-
 [partial: members]
 "
 `;
@@ -42,8 +47,6 @@ exports[`Reflections: (template) should compile an indexable reflection 1`] = `
 
 [partial: comment]
 
-[helper: toc]
-
 [partial: members]
 "
 `;
@@ -53,9 +56,13 @@ exports[`Reflections: (template) should compile implemented class 1`] = `
 
 ## Implements
 
-- [\`ReflectionClass\`](../classes/reflectionclass.md)
+- [\`ReflectionClass\`](../classes/ReflectionClass.md)
 
-[helper: toc]
+## Table of contents
+
+### Constructors
+
+- [constructor](../classes/ImplementedClass.md#constructor)
 
 [partial: members]
 "
@@ -64,7 +71,14 @@ exports[`Reflections: (template) should compile implemented class 1`] = `
 exports[`Reflections: (template) should compile module with breadcrumbs and project title 1`] = `
 "# Enumeration: EnumReflection
 
-[helper: toc]
+## Table of contents
+
+### Enumeration members
+
+- [Down](../enums/EnumReflection.md#down)
+- [Left](../enums/EnumReflection.md#left)
+- [Right](../enums/EnumReflection.md#right)
+- [Up](../enums/EnumReflection.md#up)
 
 [partial: members]
 "

packages/typedoc-plugin-markdown/test/specs/__snapshots__/signatures.spec.ts.snap

@@ -84,7 +84,7 @@ Some nested params.
 | \`params.nestedObj\` | \`Object\` | A nested object. |
 | \`params.nestedObj.name\` | \`string\` | - |
 | \`params.nestedObj.obj\` | \`Object\` | - |
-| \`params.nestedObj.obj.name\` | () => \`void\` | - |
+| \`params.nestedObj.obj.name\` |  | - |
 | \`params.nestedObj.value\` | \`number\` | - |
 | \`params.parent?\` | \`number\` | - |
 | \`context\` | \`any\` | The context of the method call. |

packages/typedoc-plugin-markdown/test/specs/__snapshots__/sources.spec.ts.snap

@@ -3,7 +3,7 @@
 exports[`Sources: should display implementation of sources' 1`] = `
 "#### Implementation of
 
-[SomeInterface](someinterface.md).[prop](someinterface.md#prop)
+[SomeInterface](SomeInterface.md).[prop](SomeInterface.md#prop)
 
 #### Defined in
 
@@ -14,7 +14,7 @@ sources.ts:6
 exports[`Sources: should display inherited sources' 1`] = `
 "#### Inherited from
 
-[SomeClass](../classes/someclass.md).[prop](../classes/someclass.md#prop)
+[SomeClass](../classes/SomeClass.md).[prop](../classes/SomeClass.md#prop)
 
 #### Defined in
 
@@ -25,7 +25,7 @@ sources.ts:2
 exports[`Sources: should display overide sources' 1`] = `
 "#### Overrides
 
-[SomeClass](../classes/someclass.md).[prop](../classes/someclass.md#prop)
+[SomeClass](../classes/SomeClass.md).[prop](../classes/SomeClass.md#prop)
 
 #### Defined in