fix(core): handle quoted symbol names (#611)

typedoc2md · May 11, 2024 · 5b412fb · 5b412fb
1 parent 7d8a703
commit 5b412fb
Show file tree

Hide file tree

Showing 8 changed files with 84 additions and 11 deletions.
diff --git a/packages/typedoc-plugin-markdown/src/libs/utils/index.ts b/packages/typedoc-plugin-markdown/src/libs/utils/index.ts
@@ -8,6 +8,7 @@ export { formatMarkdown } from './format-markdown';
 export { formatTableColumn } from './format-table-column';
 export { getFileNameWithExtension } from './get-file-name-with-extension';
 export { getFirstParagrph } from './get-first-paragraph';
+export { isQuoted } from './is-quoted';
 export { removeFirstScopedDirectory } from './remove-first-scoped-directory';
 export { removeLineBreaks } from './remove-line-breaks';
 export { sanitizeComments } from './sanitize-comments';

diff --git a/packages/typedoc-plugin-markdown/src/libs/utils/is-quoted.ts b/packages/typedoc-plugin-markdown/src/libs/utils/is-quoted.ts
@@ -0,0 +1,3 @@
+export function isQuoted(str: string) {
+  return str.startsWith('"') && str.endsWith('"');
+}
diff --git a/packages/typedoc-plugin-markdown/src/theme/core/navigation-builder.ts b/packages/typedoc-plugin-markdown/src/theme/core/navigation-builder.ts
@@ -1,4 +1,5 @@
 import { MarkdownRenderer } from '@plugin/app/application';
+import { isQuoted } from '@plugin/libs/utils';
 import { OutputFileStrategy, PLURAL_KIND_KEY_MAP } from '@plugin/options';
 import { MarkdownTheme, NavigationItem } from '@plugin/theme';
 import * as path from 'path';
@@ -262,7 +263,7 @@ export function buildNavigation(
     child: DeclarationReflection,
     children: NavigationItem[] | null,
   ) {
-    if (!navigationOptions.excludeFolders) {
+    if (!isQuoted(child.name) && !navigationOptions.excludeFolders) {
       const titleParts = child.name.split('/');
       if (!child.name.startsWith('@') && titleParts.length > 1) {
         let currentLevel = acc;

diff --git a/packages/typedoc-plugin-markdown/src/theme/core/url-builder.ts b/packages/typedoc-plugin-markdown/src/theme/core/url-builder.ts
@@ -1,6 +1,7 @@
 import { MarkdownRenderer } from '@plugin/app/application';
 import {
   getFileNameWithExtension,
+  isQuoted,
   removeFirstScopedDirectory,
   slugifyUrl,
 } from '@plugin/libs/utils';
@@ -313,10 +314,7 @@ export function buildUrls(theme: MarkdownTheme, project: ProjectReflection) {
   }
 
   function getUrlPath(reflection: DeclarationReflection, urlOption: UrlOption) {
-    const alias = reflection.name
-      .replace(/^_+|_+$/g, '')
-      .replace(/</, '-')
-      .replace(/>/, '-');
+    const alias = getAlias(reflection.name);
 
     const parentDir = urlOption.parentUrl
       ? path.dirname(urlOption.parentUrl)
@@ -364,6 +362,16 @@ export function buildUrls(theme: MarkdownTheme, project: ProjectReflection) {
     );
   }
 
+  function getAlias(name: string) {
+    if (isQuoted(name)) {
+      name = name.replace(/\//g, '_');
+    }
+    return name
+      .replace(/"/g, '')
+      .replace(/^_+|_+$/g, '')
+      .replace(/[<>]/g, '-');
+  }
+
   function applyAnchorUrl(
     reflection: DeclarationReflection,
     container: Reflection,
@@ -471,16 +479,18 @@ export function buildUrls(theme: MarkdownTheme, project: ProjectReflection) {
 
   function flattenFiles(urls: UrlMapping<Reflection>[]) {
     const getUrl = (reflection: Reflection) => {
-      const fullname = reflection.getFullName();
-      const fullnameParts = fullname.replace(/\//g, '.').split('.');
+      const fullName = reflection.getFullName();
+      const fullNameParts = fullName.replace(/\//g, '.').split('.');
       if (reflection.kind !== ReflectionKind.Module) {
-        fullnameParts.splice(
-          fullnameParts.length - 1,
+        fullNameParts.splice(
+          fullNameParts.length - 1,
           0,
           ReflectionKind.singularString(reflection.kind).split(' ')[0],
         );
       }
-      const url = `${fullnameParts.join('.')}.md`;
+      const url = `${fullNameParts.join('.')}${fileExtension}`
+        .replace(/"/g, '')
+        .replace(/^\./g, '');
       reflection.url = url;
       return url;
     };

diff --git a/packages/typedoc-plugin-markdown/test/fixtures/config.ts b/packages/typedoc-plugin-markdown/test/fixtures/config.ts
@@ -48,7 +48,11 @@ const config: Record<string, Fixture> = {
   },
   modules: {
     only: false,
-    entryPoints: ['/modules/module-1', '/modules/module-2'],
+    entryPoints: [
+      '/modules/module-1',
+      '/modules/module-2',
+      '/modules/module-3',
+    ],
     commonOptions: {
       plugin: [path.join(__dirname, 'custom-plugins', 'navigation-plugin.mjs')],
       readme: 'none',

diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/modules/module-3/index.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/modules/module-3/index.ts
@@ -0,0 +1,4 @@
+/**
+ * @module "/Test/Module/Name"
+ */
+export interface InterfaceA {}
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap
@@ -1032,6 +1032,23 @@ exports[`Navigation should gets Navigation Json for entry modules: (Output File
 
 exports[`Navigation should gets Navigation Json for modules with parts: (Output File Strategy "members") (Option Group "1") 1`] = `
 "[
+  {
+    "title": "\\"/Test/Module/Name\\"",
+    "kind": 2,
+    "path": "Test_Module_Name/README.md",
+    "children": [
+      {
+        "title": "Interfaces",
+        "children": [
+          {
+            "title": "InterfaceA",
+            "kind": 256,
+            "path": "Test_Module_Name/interfaces/InterfaceA.md"
+          }
+        ]
+      }
+    ]
+  },
   {
     "title": "@scope/namespace",
     "kind": 2,
@@ -1454,6 +1471,23 @@ exports[`Navigation should gets Navigation Json for modules with parts: (Output
 
 exports[`Navigation should gets Navigation Json for modules with parts: (Output File Strategy "members") (Option Group "2") 1`] = `
 "[
+  {
+    "title": "\\"/Test/Module/Name\\"",
+    "kind": 2,
+    "path": "Test.Module.Name.md",
+    "children": [
+      {
+        "title": "Interfaces",
+        "children": [
+          {
+            "title": "InterfaceA",
+            "kind": 256,
+            "path": "Test.Module.Name.Interface.InterfaceA.md"
+          }
+        ]
+      }
+    ]
+  },
   {
     "title": "@scope/namespace",
     "kind": 2,
@@ -1861,6 +1895,11 @@ exports[`Navigation should gets Navigation Json for modules with parts: (Output
 
 exports[`Navigation should gets Navigation Json for modules with parts: (Output File Strategy "modules") (Option Group "1") 1`] = `
 "[
+  {
+    "title": "\\"/Test/Module/Name\\"",
+    "kind": 2,
+    "path": "Test_Module_Name.md"
+  },
   {
     "title": "@scope/namespace",
     "kind": 2,
@@ -1911,6 +1950,11 @@ exports[`Navigation should gets Navigation Json for modules with parts: (Output
 
 exports[`Navigation should gets Navigation Json for modules with parts: (Output File Strategy "modules") (Option Group "2") 1`] = `
 "[
+  {
+    "title": "\\"/Test/Module/Name\\"",
+    "kind": 2,
+    "path": "Test.Module.Name.md"
+  },
   {
     "title": "@scope/namespace",
     "kind": 2,

diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap
@@ -43,6 +43,8 @@ exports[`Urls should gets Urls for entry module: outputFileStrategy: modules 2`]
 exports[`Urls should gets Urls for modules parts: outputFileStrategy: members 1`] = `
 [
   "README.md",
+  "Test_Module_Name/README.md",
+  "Test_Module_Name/interfaces/InterfaceA.md",
   "module-1/submodules/submodule-1/README.md",
   "module-1/submodules/submodule-1/classes/ClassA.md",
   "module-1/submodules/submodule-1/classes/ClassB.md",
@@ -112,6 +114,8 @@ exports[`Urls should gets Urls for modules parts: outputFileStrategy: members 2`
   "@scope.namespace.Type.TypeB.md",
   "@scope.namespace.md",
   "README.md",
+  "Test.Module.Name.Interface.InterfaceA.md",
+  "Test.Module.Name.md",
   "module-1.submodules.submodule-1.Class.ClassA.md",
   "module-1.submodules.submodule-1.Class.ClassB.md",
   "module-1.submodules.submodule-1.Enumeration.EnumA.md",
@@ -163,6 +167,7 @@ exports[`Urls should gets Urls for modules parts: outputFileStrategy: members 2`
 exports[`Urls should gets Urls for modules parts: outputFileStrategy: modules 1`] = `
 [
   "README.md",
+  "Test_Module_Name.md",
   "module-1/submodules/submodule-1.md",
   "module-1/submodules/submodule-2.md",
   "module-1/submodules/submodule-3-with-modules/nested-submodule-1.md",
@@ -176,6 +181,7 @@ exports[`Urls should gets Urls for modules parts: outputFileStrategy: modules 2`
 [
   "@scope.namespace.md",
   "README.md",
+  "Test.Module.Name.md",
   "module-1.submodules.submodule-1.md",
   "module-1.submodules.submodule-2.md",
   "module-1.submodules.submodule-3-with-modules.nested-submodule-1.md",