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);
+}