fix: Correctly define theme using TypeDoc defineTheme method

typedoc2md · Jan 9, 2022 · 5f2ef42 · 5f2ef42
1 parent ab5878d
commit 5f2ef42
Show file tree

Hide file tree

Showing 12 changed files with 196 additions and 260 deletions.
diff --git a/package.json b/package.json
@@ -21,25 +21,25 @@
   "devDependencies": {
     "@types/fs-extra": "^9.0.13",
     "@types/jest": "^26.0.24",
-    "@types/node": "^16.11.7",
+    "@types/node": "^17.0.8",
     "@types/progress": "^2.0.5",
-    "@types/tmp": "^0.2.2",
-    "@typescript-eslint/eslint-plugin": "^5.3.1",
-    "@typescript-eslint/parser": "^5.3.1",
+    "@types/tmp": "^0.2.3",
+    "@typescript-eslint/eslint-plugin": "^5.9.0",
+    "@typescript-eslint/parser": "^5.9.0",
     "copyfiles": "^2.4.1",
     "cuid": "^2.1.8",
-    "eslint": "^8.2.0",
+    "eslint": "^8.6.0",
     "fs-extra": "^10.0.0",
     "jest": "^26.6.3",
     "lerna": "^4.0.0",
-    "markdownlint": "^0.24.0",
-    "markdownlint-cli": "^0.29.0",
+    "markdownlint": "^0.25.0",
+    "markdownlint-cli": "^0.30.0",
     "npm-run-all": "^4.1.5",
-    "prettier": "^2.4.1",
+    "prettier": "^2.5.1",
     "tmp": "^0.2.1",
     "ts-jest": "^26.5.5",
-    "typedoc": "^0.22.9",
+    "typedoc": "^0.22.10",
     "typedoc-plugin-mdn-links": "^1.0.4",
-    "typescript": "^4.4.4"
+    "typescript": "^4.5.4"
   }
 }
diff --git a/packages/docusaurus-plugin-typedoc/package.json b/packages/docusaurus-plugin-typedoc/package.json
@@ -16,8 +16,8 @@
   },
   "homepage": "https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/docusaurus-plugin-typedoc",
   "peerDependencies": {
-    "typedoc": ">=0.21.0",
-    "typedoc-plugin-markdown": ">=3.10.0"
+    "typedoc": ">=0.22.0",
+    "typedoc-plugin-markdown": ">=3.11.10"
   },
   "devDependencies": {
     "@docusaurus/types": "^2.0.0-beta.0"

diff --git a/packages/typedoc-bitbucket-theme/package.json b/packages/typedoc-bitbucket-theme/package.json
@@ -25,7 +25,7 @@
   "license": "MIT",
   "peerDependencies": {
     "typedoc": ">=0.22.9",
-    "typedoc-plugin-markdown": ">=3.12.0"
+    "typedoc-plugin-markdown": ">=3.11.10"
   },
   "keywords": [
     "typedoc-theme"

diff --git a/packages/typedoc-github-wiki-theme/package.json b/packages/typedoc-github-wiki-theme/package.json
@@ -27,7 +27,7 @@
   "license": "MIT",
   "peerDependencies": {
     "typedoc": ">=0.22.9",
-    "typedoc-plugin-markdown": ">=3.12.0"
+    "typedoc-plugin-markdown": ">=3.11.10"
   },
   "keywords": [
     "typedoc",

diff --git a/packages/typedoc-gitlab-wiki-theme/package.json b/packages/typedoc-gitlab-wiki-theme/package.json
@@ -27,7 +27,7 @@
   "license": "MIT",
   "peerDependencies": {
     "typedoc": ">=0.22.9",
-    "typedoc-plugin-markdown": ">=3.12.0"
+    "typedoc-plugin-markdown": ">=3.11.10"
   },
   "keywords": [
     "typedoc",

diff --git a/packages/typedoc-hugo-theme/package.json b/packages/typedoc-hugo-theme/package.json
@@ -27,7 +27,7 @@
   "license": "MIT",
   "peerDependencies": {
     "typedoc": ">=0.22.9",
-    "typedoc-plugin-markdown": ">=3.12.0"
+    "typedoc-plugin-markdown": ">=3.11.10"
   },
   "keywords": [
     "typedoc",

diff --git a/packages/typedoc-plugin-markdown/README.md b/packages/typedoc-plugin-markdown/README.md
@@ -23,17 +23,15 @@ npm install --save-dev typedoc typedoc-plugin-markdown
 Usage is the same as documented at [TypeDoc](https://typedoc.org/guides/installation/#command-line-interface).
 
 ```bash
-typedoc --out docs src/index.ts
+typedoc --plugin typedoc-plugin-markdown --out docs src/index.ts
 ```
 
-**Note:**
-
-- If using with the default HTML theme or other themes, use `--plugin none` to switch the plugin off.
-- The plugin should be executed in the same location as TypeDoc. Use `npx` if running command directly in shell.
+> The plugin switches the default html theme to the in-built markdown theme as default. If using with the default html theme, use `--plugin none` to switch the plugin off.
 
 ## Options
 
-The following options can be used in addition to relevant [TypeDoc options](https://typedoc.org/guides/options/).
+The following options can be used in addition to relevant [TypeDoc options](https://typedoc.org/guides/options/)
+(please note that TypeDoc options specific to the html theme will be ignored).
 
 - `--entryDocument<string>`<br>
   The file name of the entry document. Defaults to `README.md`.
@@ -46,9 +44,6 @@ The following options can be used in addition to relevant [TypeDoc options](http
 - `--namedAnchors<boolean>`<br>
   Use HTML named anchors tags for implementations that do not assign header ids. Defaults to `false`.
 
-
-
-
 ## License
 
 [MIT](https://github.com/tgreyuk/typedoc-plugin-markdown/blob/master/LICENSE)
diff --git a/packages/typedoc-plugin-markdown/src/index.ts b/packages/typedoc-plugin-markdown/src/index.ts
@@ -1,21 +1,11 @@
-import * as path from 'path';
-
-import {
-  Application,
-  ParameterType,
-  ProjectReflection,
-  RendererEvent,
-} from 'typedoc';
-
-import { CustomOptionsReader } from './options-reader';
+import { Application, ParameterType } from 'typedoc';
+import { MarkdownThemeOptionsReader } from './options-reader';
 import { MarkdownTheme } from './theme';
 
 export function load(app: Application) {
-  addDeclarations(app);
-  loadTheme(app);
-}
+  app.renderer.defineTheme('markdown', MarkdownTheme);
+  app.options.addReader(new MarkdownThemeOptionsReader());
 
-function addDeclarations(app: Application) {
   app.options.addDeclaration({
     help: '[Markdown Plugin] Do not render page title.',
     name: 'hidePageTitle',
@@ -78,55 +68,4 @@ function addDeclarations(app: Application) {
   });
 }
 
-function loadTheme(app: Application) {
-  const themeRef = app.options.getValue('theme');
-  if (['default', 'markdown'].includes(themeRef)) {
-    app.renderer.render = render;
-    app.renderer.theme = new MarkdownTheme(app.renderer);
-  } else {
-    const CustomTheme = getCustomTheme(
-      path.resolve(path.join(themeRef, 'theme.js')),
-    );
-    if (CustomTheme !== null) {
-      app.options.addReader(new CustomOptionsReader());
-      app.renderer.render = render;
-      app.renderer.theme = new CustomTheme(app.renderer);
-    } else {
-      app.logger.warn(
-        `[typedoc-plugin-markdown] '${themeRef}' is not a recognised markdown theme.`,
-      );
-    }
-  }
-}
-
-async function render(project: ProjectReflection, outputDirectory: string) {
-  const output = new RendererEvent(
-    RendererEvent.BEGIN,
-    outputDirectory,
-    project,
-  );
-  if (
-    !this.prepareTheme() ||
-    !(await this.prepareOutputDirectory(outputDirectory))
-  ) {
-    return;
-  }
-  output.urls = this.theme!.getUrls(project);
-  this.trigger(output);
-  if (!output.isDefaultPrevented) {
-    output?.urls?.forEach((mapping) => {
-      this.renderDocument(output.createPageEvent(mapping));
-    });
-    this.trigger(RendererEvent.END, output);
-  }
-}
-
-function getCustomTheme(themeFile: string) {
-  try {
-    const ThemeClass = require(themeFile);
-    const instance = ThemeClass[Object.keys(ThemeClass)[0]];
-    return instance.prototype instanceof MarkdownTheme ? instance : null;
-  } catch (e) {
-    return null;
-  }
-}
+export { MarkdownTheme };
diff --git a/packages/typedoc-plugin-markdown/src/options-reader.ts b/packages/typedoc-plugin-markdown/src/options-reader.ts
@@ -1,29 +1,11 @@
-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;
+export class MarkdownThemeOptionsReader implements OptionsReader {
+  priority = 1000;
+  name = 'markdown-theme-reader';
+  read(container: Options) {
+    if (container.getValue('theme') === 'default') {
+      container.setValue('theme', 'markdown');
     }
   }
 }
diff --git a/packages/typedoc-plugin-markdown/src/theme.ts b/packages/typedoc-plugin-markdown/src/theme.ts
@@ -1,6 +1,5 @@
 import * as path from 'path';
 import {
-  BindOption,
   ContainerReflection,
   DeclarationReflection,
   PageEvent,
@@ -26,57 +25,46 @@ import {
 import { formatContents } from './utils';
 
 export class MarkdownTheme extends Theme {
-  @BindOption('allReflectionsHaveOwnDocument')
   allReflectionsHaveOwnDocument!: boolean;
-
-  @BindOption('entryDocument')
   entryDocument: string;
-
-  @BindOption('entryPoints')
   entryPoints!: string[];
-
-  @BindOption('filenameSeparator')
   filenameSeparator!: string;
-
-  @BindOption('hideBreadcrumbs')
   hideBreadcrumbs!: boolean;
-
-  @BindOption('hideInPageTOC')
   hideInPageTOC!: boolean;
-
-  @BindOption('hidePageTitle')
   hidePageTitle!: boolean;
-
-  @BindOption('indexTitle')
+  includes!: string;
   indexTitle!: string;
-
-  @BindOption('namedAnchors')
+  mediaDirectory!: string;
   namedAnchors!: boolean;
-
-  @BindOption('readme')
   readme!: string;
-
-  @BindOption('out')
   out!: string;
-
-  @BindOption('publicPath')
   publicPath!: string;
 
-  @BindOption('includes')
-  includes!: string;
-
-  @BindOption('media')
-  mediaDirectory!: string;
-
-  static URL_PREFIX = /^(http|ftp)s?:\/\//;
-
   project?: ProjectReflection;
   reflection?: DeclarationReflection;
   location!: string;
 
+  static URL_PREFIX = /^(http|ftp)s?:\/\//;
+
   constructor(renderer: Renderer) {
     super(renderer);
 
+    // prettier-ignore
+    this.allReflectionsHaveOwnDocument = this.getOption('allReflectionsHaveOwnDocument',) as boolean;
+    this.entryDocument = this.getOption('entryDocument') as string;
+    this.entryPoints = this.getOption('entryPoints') as string[];
+    this.filenameSeparator = this.getOption('filenameSeparator') as string;
+    this.hideBreadcrumbs = this.getOption('hideBreadcrumbs') as boolean;
+    this.hideInPageTOC = this.getOption('hideInPageTOC') as boolean;
+    this.hidePageTitle = this.getOption('hidePageTitle') as boolean;
+    this.includes = this.getOption('includes') as string;
+    this.indexTitle = this.getOption('indexTitle') as string;
+    this.mediaDirectory = this.getOption('media') as string;
+    this.namedAnchors = this.getOption('namedAnchors') as boolean;
+    this.readme = this.getOption('readme') as string;
+    this.out = this.getOption('out') as string;
+    this.publicPath = this.getOption('publicPath') as string;
+
     this.listenTo(this.owner, {
       [RendererEvent.BEGIN]: this.onBeginRenderer,
       [PageEvent.BEGIN]: this.onBeginPage,
@@ -90,6 +78,10 @@ export class MarkdownTheme extends Theme {
     return formatContents(page.template(page) as string);
   }
 
+  getOption(key: string) {
+    return this.application.options.getValue(key);
+  }
+
   getUrls(project: ProjectReflection) {
     const urls: UrlMapping[] = [];
     const noReadmeFile = this.readme.endsWith('none');

diff --git a/packages/vuepress-plugin-typedoc/package.json b/packages/vuepress-plugin-typedoc/package.json
@@ -17,7 +17,7 @@
   "homepage": "https://github.com/tgreyuk/typedoc-plugin-markdown/tree/master/packages/vuepress-plugin-typedoc",
   "peerDependencies": {
     "typedoc": ">=0.22.0",
-    "typedoc-plugin-markdown": ">=3.11.0"
+    "typedoc-plugin-markdown": ">=3.11.10"
   },
   "scripts": {
     "lint": "eslint ./src --ext .ts",