fix: handle docusaurus relative link issues

typedoc2md · Apr 27, 2024 · 79d2cd2 · 79d2cd2
1 parent 83413ba
commit 79d2cd2
Show file tree

Hide file tree

Showing 6 changed files with 160 additions and 13 deletions.
diff --git a/devtools/examples/docusaurus/docusaurus.config.js b/devtools/examples/docusaurus/docusaurus.config.js
@@ -59,18 +59,12 @@ const config = {
           '../../../packages/typedoc-plugin-markdown/test/fixtures/tsconfig.json',
         ),
         entryPoints:
-          '../../../packages/typedoc-plugin-markdown/test/fixtures/src/reflections/index.ts',
-        typeDeclarationFormat: 'table',
+          '../../../packages/typedoc-plugin-markdown/test/fixtures/src/comments/index.ts',
         expandObjects: true,
         readme: 'none',
         sidebar: { pretty: true },
-        outputFileStrategy: 'members',
+        outputFileStrategy: 'modules',
         cleanOutputDir: true,
-        navigation: {
-          includeFolders: true,
-          includeGroups: true,
-          includeCategories: true,
-        },
       },
     ],
     [

diff --git a/packages/docusaurus-plugin-typedoc/docusaurus.config.js b/packages/docusaurus-plugin-typedoc/docusaurus.config.js
@@ -18,9 +18,9 @@ const config = {
         out: './test/out/default',
         readme: 'none',
         cleanOutputDir: true,
-        navigation: {
-          includeGroups: true,
-        },
+        disableSources: true,
+        hidePageHeader: true,
+        hideBreadcrumb: true,
       },
     ],
     [
@@ -34,6 +34,25 @@ const config = {
         readme: 'none',
         sidebar: { pretty: true },
         fileExtension: '.mdx',
+        disableSources: true,
+        hidePageHeader: true,
+        hideBreadcrumb: true,
+      },
+    ],
+    [
+      docusaurusPlugin,
+      {
+        id: 'api-3',
+        docsRoot: './test',
+        tsconfig: './test/stubs/tsconfig.json',
+        entryPoints: './test/stubs/src/links.ts',
+        out: './test/out/links',
+        readme: 'none',
+        sidebar: { pretty: true },
+        outputFileStrategy: 'modules',
+        disableSources: true,
+        hidePageHeader: true,
+        hideBreadcrumb: true,
       },
     ],
   ],

diff --git a/packages/docusaurus-plugin-typedoc/src/plugin.ts b/packages/docusaurus-plugin-typedoc/src/plugin.ts
@@ -1,6 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { Application, DeclarationOption } from 'typedoc';
+import { Application, DeclarationOption, PageEvent } from 'typedoc';
 import { MarkdownRendererEvent } from 'typedoc-plugin-markdown';
 import { PluginOptions } from '.';
 import { getPluginOptions } from './options';
@@ -59,6 +59,13 @@ async function generateTypedoc(context: any, opts: Partial<PluginOptions>) {
     } as DeclarationOption);
   });
 
+  // attempt to handle docusaurus linkify bug https://github.com/facebook/docusaurus/issues/9048
+  app.renderer.on(PageEvent.END, (event: PageEvent) => {
+    event.contents = event.contents
+      ?.replace(/\)\.\[/g, ') . [')
+      .replace(/\\<\[/g, ' \\<[');
+  });
+
   const outputDir = app.options.getValue('out');
 
   if (sidebar?.autoConfiguration) {

diff --git a/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap b/packages/docusaurus-plugin-typedoc/test/specs/__snapshots__/docusaurus.spec.ts.snap
@@ -5,6 +5,7 @@ exports[`Docusaurus: Defaults should render docs 1`] = `
 
 ## Modules
 
+- [links](links/index.md)
 - [module-1](module-1/index.md)
 - [module-2](module-2/index.md)
 "
@@ -13,7 +14,7 @@ exports[`Docusaurus: Defaults should render docs 1`] = `
 exports[`Docusaurus: Defaults should render sidebar 1`] = `
 "// @ts-check
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
-const typedocSidebar = { items: [{"type":"category","label":"module-1","items":[{"type":"category","label":"Classes","items":[{"type":"doc","id":"out/default/module-1/classes/ClassA","label":"ClassA"},{"type":"doc","id":"out/default/module-1/classes/ClassB","label":"ClassB"}]},{"type":"category","label":"Interfaces","items":[{"type":"doc","id":"out/default/module-1/interfaces/InterfaceA","label":"InterfaceA"},{"type":"doc","id":"out/default/module-1/interfaces/InterfaceB","label":"InterfaceB"}]}],"link":{"type":"doc","id":"out/default/module-1/index"}},{"type":"category","label":"module-2","items":[{"type":"category","label":"Classes","items":[{"type":"doc","id":"out/default/module-2/classes/ClassA","label":"ClassA"},{"type":"doc","id":"out/default/module-2/classes/ClassB","label":"ClassB"}]},{"type":"category","label":"Interfaces","items":[{"type":"doc","id":"out/default/module-2/interfaces/InterfaceA","label":"InterfaceA"},{"type":"doc","id":"out/default/module-2/interfaces/InterfaceB","label":"InterfaceB"}]}],"link":{"type":"doc","id":"out/default/module-2/index"}}]};
+const typedocSidebar = { items: [{"type":"category","label":"links","items":[{"type":"category","label":"Enumerations","items":[{"type":"doc","id":"out/default/links/enumerations/CommentEnum","label":"CommentEnum"}]},{"type":"category","label":"Interfaces","items":[{"type":"doc","id":"out/default/links/interfaces/CommentInterface","label":"CommentInterface"},{"type":"doc","id":"out/default/links/interfaces/CommentInterfaceExtended","label":"CommentInterfaceExtended"}]}],"link":{"type":"doc","id":"out/default/links/index"}},{"type":"category","label":"module-1","items":[{"type":"category","label":"Classes","items":[{"type":"doc","id":"out/default/module-1/classes/ClassA","label":"ClassA"},{"type":"doc","id":"out/default/module-1/classes/ClassB","label":"ClassB"}]},{"type":"category","label":"Interfaces","items":[{"type":"doc","id":"out/default/module-1/interfaces/InterfaceA","label":"InterfaceA"},{"type":"doc","id":"out/default/module-1/interfaces/InterfaceB","label":"InterfaceB"}]}],"link":{"type":"doc","id":"out/default/module-1/index"}},{"type":"category","label":"module-2","items":[{"type":"category","label":"Classes","items":[{"type":"doc","id":"out/default/module-2/classes/ClassA","label":"ClassA"},{"type":"doc","id":"out/default/module-2/classes/ClassB","label":"ClassB"}]},{"type":"category","label":"Interfaces","items":[{"type":"doc","id":"out/default/module-2/interfaces/InterfaceA","label":"InterfaceA"},{"type":"doc","id":"out/default/module-2/interfaces/InterfaceB","label":"InterfaceB"}]}],"link":{"type":"doc","id":"out/default/module-2/index"}}]};
 module.exports = typedocSidebar.items;"
 `;
 
@@ -32,6 +33,97 @@ exports[`Docusaurus: Global Members should render docs 1`] = `
 "
 `;
 
+exports[`Docusaurus: Global Members should render links 1`] = `
+"# docusaurus-plugin-typedoc
+
+## Enumerations
+
+### CommentEnum
+
+#### Enumeration Members
+
+##### Member
+
+> **Member**: \`0\`
+
+##### MemberB
+
+> **MemberB**: \`1\`
+
+## Interfaces
+
+### CommentInterface\\<T\\>
+
+Comments form module comments
+
+#### Links
+
+Links using \`{@link}\` inline tags.
+
+- [CommentInterface](index.md#commentinterfacet) - Links to CommentInterface
+- [Links to CommentInterface.prop](index.md#prop)
+- [Links to CommentInterface.propb](index.md#propb)
+
+#### Extended by
+
+- [\`CommentInterfaceExtended\`](index.md#commentinterfaceextended)
+
+#### Type parameters
+
+• **T**
+
+#### Properties
+
+##### prop
+
+> **prop**: \`string\`
+
+##### propb
+
+> **propb**: \`T\`
+
+***
+
+### CommentInterfaceExtended
+
+Comments form module comments
+
+#### Links
+
+Links using \`{@link}\` inline tags.
+
+- [CommentInterface](index.md#commentinterfacet) - Links to CommentInterface
+- [Links to CommentInterface.prop](index.md#prop)
+- [Links to CommentInterface.propb](index.md#propb)
+
+#### Extends
+
+- [\`CommentInterface\`](index.md#commentinterfacet) \\<[\`CommentEnum\`](index.md#commentenum)\\>
+
+#### Properties
+
+##### prop
+
+> **prop**: \`string\`
+
+###### Inherited from
+
+[\`CommentInterface\`](index.md#commentinterfacet) . [\`prop\`](index.md#prop)
+
+##### propb
+
+> **propb**: [\`CommentEnum\`](index.md#commentenum)
+
+###### Inherited from
+
+[\`CommentInterface\`](index.md#commentinterfacet) . [\`propb\`](index.md#propb)
+
+##### propc
+
+> **propc**: \`string\`
+"
+`;
+
 exports[`Docusaurus: Global Members should render sidebar 1`] = `
 "// @ts-check
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */

diff --git a/packages/docusaurus-plugin-typedoc/test/specs/docusaurus.spec.ts b/packages/docusaurus-plugin-typedoc/test/specs/docusaurus.spec.ts
@@ -36,5 +36,12 @@ describe(`Docusaurus:`, () => {
         .toString();
       expect(contents).toMatchSnapshot();
     });
+
+    test(`should render links`, () => {
+      const contents = fs
+        .readFileSync(path.join(__dirname, '../out/links/index.md'))
+        .toString();
+      expect(contents).toMatchSnapshot();
+    });
   });
 });
diff --git a/packages/docusaurus-plugin-typedoc/test/stubs/src/links.ts b/packages/docusaurus-plugin-typedoc/test/stubs/src/links.ts
@@ -0,0 +1,28 @@
+/**
+ *
+ * Comments form module comments
+ *
+ * @links
+ *
+ * Links using `{@link}` inline tags.
+ *
+ * - {@link CommentInterface} - Links to CommentInterface
+ * - {@link CommentInterface.prop | Links to CommentInterface.prop}
+ * - {@link CommentInterface.propb | Links to CommentInterface.propb}
+ *
+ */
+
+export interface CommentInterface<T> {
+  prop: string;
+  propb: T;
+}
+
+export interface CommentInterfaceExtended
+  extends CommentInterface<CommentEnum> {
+  propc: string;
+}
+
+export enum CommentEnum {
+  Member,
+  MemberB,
+}