fix: catch all external references

typedoc2md · Nov 14, 2021 · 003cb96 · 003cb96
1 parent dfd16a8
commit 003cb96
Show file tree

Hide file tree

Showing 7 changed files with 53 additions and 12 deletions.
diff --git a/package.json b/package.json
@@ -38,7 +38,8 @@
     "prettier": "^2.4.1",
     "tmp": "^0.2.1",
     "ts-jest": "^26.5.5",
-    "typedoc": "^0.22.8",
+    "typedoc": "^0.22.9",
+    "typedoc-plugin-mdn-links": "^1.0.4",
     "typescript": "^4.4.4"
   }
 }
diff --git a/packages/typedoc-plugin-markdown/package.json b/packages/typedoc-plugin-markdown/package.json
@@ -15,8 +15,8 @@
     "build-and-test": "yarn run build && yarn run test",
     "fixtures": "node ./tasks/fixtures.js",
     "demos": "yarn run build && yarn run demo:md && yarn run demo:html",
-    "demo:md": "typedoc --options ./demo.options.json --out ./demo/md",
-    "demo:html": "typedoc --options ./demo.options.json --plugin none --out ./demo/html"
+    "demo:md": "typedoc --plugin typedoc-plugin-markdown --plugin typedoc-plugin-mdn-links --options ./demo.options.json --out ./demo/md",
+    "demo:html": "typedoc --options ./demo.options.json --plugin typedoc-plugin-mdn-links --out ./demo/html"
   },
   "author": "Thomas Grey",
   "license": "MIT",

diff --git a/packages/typedoc-plugin-markdown/src/resources/helpers/type.ts b/packages/typedoc-plugin-markdown/src/resources/helpers/type.ts
@@ -192,21 +192,22 @@ export function getFunctionType(modelSignatures: SignatureReflection[]) {
 }
 
 function getReferenceType(model: ReferenceType, emphasis) {
+  const externalUrl = Handlebars.helpers.attemptExternalResolution(
+    model.getSymbol(),
+  );
   if (model.reflection || (model.name && model.typeArguments)) {
     const reflection: string[] = [];
+
     if (model.reflection?.url) {
       reflection.push(
         `[${`\`${model.reflection.name}\``}](${Handlebars.helpers.relativeURL(
           model.reflection.url,
         )})`,
       );
     } else {
-      const externalUrl = Handlebars.helpers.attemptExternalResolution(
-        model.getSymbol(),
-      );
       reflection.push(
         externalUrl
-          ? `[${`\`${model.name}\``}](${externalUrl})`
+          ? `[${`\`${model.name}\``}]( ${externalUrl} )`
           : `\`${model.name}\``,
       );
     }
@@ -221,7 +222,11 @@ function getReferenceType(model: ReferenceType, emphasis) {
     }
     return reflection.join('');
   }
-  return emphasis ? `\`${model.name}\`` : escapeChars(model.name);
+  return emphasis
+    ? externalUrl
+      ? `[${`\`${model.name}\``}]( ${externalUrl} )`
+      : `\`${model.name}\``
+    : escapeChars(model.name);
 }
 
 function getArrayType(model: ArrayType, emphasis: boolean) {

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/types.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/types.spec.ts.snap
@@ -43,3 +43,7 @@ exports[`Types: should compile expanded 'objectLiteralType' type' 1`] = `"{}"`;
 exports[`Types: should compile intrinsic type' 1`] = `"\`string\`"`;
 
 exports[`Types: should compile unionType with object literal type ' 1`] = `"\`string\` \\\\| { \`z\`: \`string\`  }"`;
+
+exports[`Types: should resolve external refs with type params' 1`] = `"\`ClassWithTypeParams\`<[\`HTMLElement\`]( https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement ), [\`Error\`]( https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error )\\\\>"`;
+
+exports[`Types: should resolve external refs' 1`] = `"[\`HTMLElement\`]( https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement )"`;
diff --git a/packages/typedoc-plugin-markdown/test/specs/types.spec.ts b/packages/typedoc-plugin-markdown/test/specs/types.spec.ts
@@ -136,4 +136,20 @@ describe(`Types:`, () => {
       ),
     ).toMatchSnapshot();
   });
+
+  test(`should resolve external refs'`, () => {
+    expect(
+      Handlebars.helpers.type.call(
+        testApp.findReflection('externalReference').type,
+      ),
+    ).toMatchSnapshot();
+  });
+
+  test(`should resolve external refs with type params'`, () => {
+    expect(
+      Handlebars.helpers.type.call(
+        testApp.findReflection('externalReferenceInsideTypeParams').type,
+      ),
+    ).toMatchSnapshot();
+  });
 });
diff --git a/packages/typedoc-plugin-markdown/test/stubs/src/types.ts b/packages/typedoc-plugin-markdown/test/stubs/src/types.ts
@@ -1,5 +1,15 @@
+import { ClassWithTypeParams } from './generics';
 import { _someCallback_ } from './signatures';
 
+export let htmlElement: HTMLElement;
+
+export let externalReference: HTMLElement;
+
+export const externalReferenceInsideTypeParams = new ClassWithTypeParams<
+  HTMLElement,
+  Error
+>();
+
 export let stringType: string;
 
 export const stringLiteralType = 'blue';

diff --git a/yarn.lock b/yarn.lock
@@ -7783,10 +7783,15 @@ typedarray@^0.0.6:
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
   integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=
 
-typedoc@^0.22.8:
-  version "0.22.8"
-  resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.22.8.tgz#cd488290bd31d2cd4099004e1104807895d4eb17"
-  integrity sha512-92S+YzyhospdXN5rnkYUTgirdTYqNWY7NP9vco+IqQQoiSXzVSUsawVro+tMyEEsWUS7EMaJ2YOjB9uE0CBi6A==
+typedoc-plugin-mdn-links@^1.0.4:
+  version "1.0.4"
+  resolved "https://registry.yarnpkg.com/typedoc-plugin-mdn-links/-/typedoc-plugin-mdn-links-1.0.4.tgz#be1f1797a46af33d2428833ea6c2dc26572031b7"
+  integrity sha512-mw5IISaKRq8w1hJwp05vkFD9Ijtlv9j7uuM68zlp1zVdzQr4JRYQBTtde4cnSdYatFmLVjQpuFYwoGREJxlHlw==
+
+typedoc@^0.22.9:
+  version "0.22.9"
+  resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.22.9.tgz#7e3f4f72586bbef4c2382f0afcea8e0f9270b712"
+  integrity sha512-84PjudoXVcap6bwdZFbYIUWlgdz/iLV09ZHwrCzhtHWXaDQG6mlosJ8te6DSThuRkRvQjp46HO+qY/P7Gpm78g==
   dependencies:
     glob "^7.2.0"
     lunr "^2.3.9"