Fix externalSymbolLinkMappings # urls

Resolves #2921

Author: Gerrit0

CHANGELOG.md

@@ -12,6 +12,7 @@ title: Changelog
   that function's type parameters as the class type parameters, #2914.
 - When printing entry point globs which fail to match any paths, TypeDoc will no longer normalize the glob, #2918.
 - Inlining types can now handle more type variants, #2920.
+- Fixed behavior of `externalSymbolLinkMappings` option when URL is set to `#`, #2921.
 - API: `toString` on types containing index signatures now behave correctly, #2917.
 
 ## v0.28.1 (2025-03-20)

scripts/rebuild_specs.js

@@ -4,26 +4,21 @@
 Error.stackTraceLimit = 50;
 import ts from "typescript";
 import fs from "fs";
-import { rm } from "fs/promises";
 import path, { basename, join } from "path";
 import * as td from "../dist/index.js";
 import { getExpandedEntryPointsForPaths } from "../dist/lib/utils/index.js";
 import { ok } from "assert";
 import { fileURLToPath } from "url";
 import { diagnostics } from "../dist/lib/utils/loggers.js";
-import { getConverter2App, getConverter2Project, getConverterApp } from "../dist/test/programs.js";
-import { TestRouter, TestTheme } from "../dist/test/renderer/testRendererUtils.js";
+import { getConverterApp } from "../dist/test/programs.js";
+import { buildRendererSpecs } from "../dist/test/renderer/testRendererUtils.js";
 
 const base = path.join(
     fileURLToPath(import.meta.url),
     "../../src/test/converter",
 );
 
 const app = getConverterApp();
-const app2 = getConverter2App();
-
-app2.renderer.defineTheme("test-theme", TestTheme);
-app2.renderer.defineRouter("test-router", TestRouter);
 
 app.serializer.addSerializer({
     priority: -1,
@@ -128,19 +123,7 @@ function rebuildConverterTests(dirs) {
 /** @param {string} specPath */
 async function rebuildRendererTest(specPath) {
     console.log(specPath);
-    await rm(specPath, { recursive: true, force: true });
-
-    app2.options.setValue("theme", "test-theme");
-    app2.options.setValue("router", "test-router");
-    app2.options.setValue("disableGit", true);
-    app2.options.setValue("sourceLinkTemplate", "{path}");
-
-    td.resetReflectionID();
-    const project = getConverter2Project(["renderer"], ".");
-    project.readme = [{ kind: "text", text: "Readme text" }];
-    await app2.generateDocs(project, specPath);
-    await rm(`${specPath}/assets`, { recursive: true });
-    await rm(`${specPath}/.nojekyll`);
+    await buildRendererSpecs(specPath);
 }
 
 async function main() {

src/lib/output/renderer.ts

@@ -288,6 +288,11 @@ export class Renderer extends AbstractComponent<Application, RendererEvents> {
         this.themes.set(name, theme);
     }
 
+    /** @internal intended for test usage only */
+    removeTheme(name: string) {
+        this.themes.delete(name);
+    }
+
     /**
      * Define a new router that can be used to determine the output structure.
      * @param name
@@ -300,6 +305,11 @@ export class Renderer extends AbstractComponent<Application, RendererEvents> {
         this.routers.set(name, router);
     }
 
+    /** @internal intended for test usage only */
+    removeRouter(name: string) {
+        this.routers.delete(name);
+    }
+
     /**
      * Render the given project reflection to the specified output directory.
      *

src/lib/output/themes/MarkedPlugin.tsx

@@ -159,7 +159,7 @@ export class MarkedPlugin extends ContextAwareRendererComponent {
                                 let url: string | undefined;
                                 let kindClass: string | undefined;
                                 if (typeof part.target === "string") {
-                                    url = part.target;
+                                    url = part.target === "#" ? undefined : part.target;
                                 } else if ("id" in part.target) {
                                     // No point in trying to resolve a ReflectionSymbolId at this point, we've already
                                     // tried and failed during the resolution step. Warnings related to those broken links

src/test/converter2/typedoc.json

@@ -11,6 +11,12 @@
             "path": "../../../docs/docs.json"
         }
     ],
+    "disableGit": true,
+    "sourceLinkTemplate": "{path}",
+    "excludeExternals": true,
+    "tsconfig": "tsconfig.json",
+    "validation": true,
+    "skipErrorChecking": true,
     "externalSymbolLinkMappings": {
         // used by {@link !Promise}
         "global": {

src/test/output/output.test.ts

@@ -24,6 +24,9 @@ describe("Output", () => {
     });
 
     beforeEach(() => {
+        // Throw away output configuration for debug rendering of c2 projects
+        app.options.reset();
+
         outputs = new Outputs(app);
         outputs.addOutput("html", () => {
             htmlWritten = true;

src/test/programs.ts

@@ -15,6 +15,7 @@ import { createAppForTesting } from "../lib/application.js";
 import { existsSync } from "fs";
 import { clearCommentCache } from "../lib/converter/comments/index.js";
 import { diagnostics } from "../lib/utils/loggers.js";
+import { readFile } from "#node-utils";
 
 let converterApp: Application | undefined;
 let converterProgram: ts.Program | undefined;
@@ -112,18 +113,14 @@ export function getConverter2Base() {
 export function getConverter2App() {
     if (!converter2App) {
         converter2App = createAppForTesting();
-        for (
-            const [name, value] of Object.entries(
-                {
-                    excludeExternals: true,
-                    tsconfig: join(getConverter2Base(), "tsconfig.json"),
-                    validation: true,
-                    skipErrorChecking: true,
-                } satisfies TypeDocOptions,
-            )
-        ) {
-            converter2App.options.setValue(name as never, value as never);
+
+        // This is a base-bones version of the TypeDocReader's read method
+        // which doesn't handle a JS config, so can be done synchronously
+        const result = ts.readConfigFile(join(getConverter2Base(), "typedoc.json"), readFile);
+        for (const [name, value] of Object.entries(result.config)) {
+            converter2App.options.setValue(name as never, value as never, getConverter2Base());
         }
+
         new TSConfigReader().read(
             converter2App.options,
             converter2App.logger,

src/test/renderer/DefaultTheme.test.ts

@@ -1,37 +1,15 @@
-import { rm } from "fs/promises";
-import { getConverter2App, getConverter2Project } from "../programs.js";
-import { TestRouter, TestTheme } from "./testRendererUtils.js";
+import { buildRendererSpecs } from "./testRendererUtils.js";
 import { deepEqual as equal } from "assert/strict";
 import { glob, readFile } from "#node-utils";
 import type { GlobString, NormalizedPath } from "#utils";
 import { join, relative } from "path";
-import { resetReflectionID } from "#models";
-
-const app = getConverter2App();
-
-app.renderer.defineTheme("test-theme", TestTheme);
-app.renderer.defineRouter("test-router", TestRouter);
 
 describe("DefaultTheme", () => {
-    afterEach(() => {
-        app.options.reset();
-    });
-
     it("Matches render snapshot", async function () {
         const SPEC_PATH = "src/test/renderer/specs" as NormalizedPath;
         const outPath = "tmp/renderer" as NormalizedPath;
 
-        app.options.setValue("theme", "test-theme");
-        app.options.setValue("router", "test-router");
-        app.options.setValue("disableGit", true);
-        app.options.setValue("sourceLinkTemplate", "{path}");
-
-        resetReflectionID();
-        const project = getConverter2Project(["renderer"], ".");
-        project.readme = [{ kind: "text", text: "Readme text" }];
-        await app.generateDocs(project, outPath);
-        await rm(outPath + "/assets", { recursive: true });
-        await rm(outPath + "/.nojekyll");
+        await buildRendererSpecs(outPath);
 
         const expectedFiles = glob("**/*" as GlobString, SPEC_PATH);
         const actualFiles = glob("**/*" as GlobString, outPath);

src/test/renderer/testRendererUtils.ts

@@ -1,8 +1,10 @@
-import type { Reflection } from "#models";
+import { type Reflection, resetReflectionID } from "#models";
 import { loadTestHighlighter } from "#node-utils";
+import { rm } from "node:fs/promises";
 import { DefaultTheme, KindRouter, PageEvent, PageKind, type RenderTemplate } from "../../lib/output/index.js";
 import { type JsxChildren, type JsxElement, JsxFragment } from "../../lib/utils-common/jsx.elements.js";
 import { Raw } from "../../lib/utils-common/jsx.js";
+import { getConverter2App, getConverter2Project } from "../programs.js";
 
 function shouldIgnoreElement(el: JsxElement) {
     switch (el.tag) {
@@ -135,3 +137,30 @@ export class TestTheme extends DefaultTheme {
 export class TestRouter extends KindRouter {
     override extension = ".json";
 }
+
+export async function buildRendererSpecs(specPath: string) {
+    await rm(specPath, { recursive: true, force: true });
+
+    const app2 = getConverter2App();
+    app2.renderer.defineTheme("test-theme", TestTheme);
+    app2.renderer.defineRouter("test-router", TestRouter);
+
+    const snap = app2.options.snapshot();
+
+    app2.options.setValue("options", "src/test/converter2/typedoc.json");
+    await app2.options.read(app2.logger);
+
+    app2.options.setValue("theme", "test-theme");
+    app2.options.setValue("router", "test-router");
+
+    resetReflectionID();
+    const project = getConverter2Project(["renderer"], ".");
+    project.readme = [{ kind: "text", text: "Readme text" }];
+    await app2.generateDocs(project, specPath);
+    await rm(`${specPath}/assets`, { recursive: true });
+    await rm(`${specPath}/.nojekyll`);
+
+    app2.renderer.removeTheme("test-theme");
+    app2.renderer.removeRouter("test-router");
+    app2.options.restore(snap);
+}