diff --git a/package.json b/package.json index aee0f733c..314b3cd1c 100644 --- 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 index 13d9e305d..f6414e07c 100644 --- 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 index 86ca7d880..722ffa359 100644 --- a/packages/typedoc-plugin-markdown/src/resources/helpers/type.ts +++ b/packages/typedoc-plugin-markdown/src/resources/helpers/type.ts @@ -192,8 +192,12 @@ 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( @@ -201,12 +205,9 @@ function getReferenceType(model: ReferenceType, emphasis) { )})`, ); } 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 index 077389b3a..90b5949ab 100644 --- 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 index ec1da8513..39d5eed44 100644 --- 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 index 022a30b2a..b0caf365a 100644 --- 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 index 86d555adf..d1b5ce883 100644 --- 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"