typedoc 0.27.4 → 0.27.5

package/README.md

@@ -2,9 +2,6 @@
 
 Documentation generator for TypeScript projects.
 
-[![CI](https://github.com/TypeStrong/typedoc/workflows/CI/badge.svg)](https://github.com/TypeStrong/typedoc/actions)
-[![NPM Version](https://img.shields.io/npm/v/typedoc?color=33cd56&logo=npm)](https://www.npmjs.com/package/typedoc)
-
 ## Documentation
 
 For more detailed documentation, the changelog, and TypeDoc documentation rendered with TypeDoc, see https://typedoc.org.

package/dist/index.d.ts

@@ -1,5 +1,10 @@
 /**
  * @module TypeDoc API
+ *
+ * In addition to the members documented here, TypeDoc exports a `typedoc/debug`
+ * entry point which exports some functions which may be useful during plugin
+ * development or debugging. Exports from that entry point are **not stable**
+ * and may change or be removed at any time.
  */
 export { Application, type ApplicationEvents } from "./lib/application.js";
 export { EventDispatcher } from "./lib/utils/events.js";

package/dist/index.js

@@ -1,5 +1,10 @@
 /**
  * @module TypeDoc API
+ *
+ * In addition to the members documented here, TypeDoc exports a `typedoc/debug`
+ * entry point which exports some functions which may be useful during plugin
+ * development or debugging. Exports from that entry point are **not stable**
+ * and may change or be removed at any time.
  */
 export { Application } from "./lib/application.js";
 export { EventDispatcher } from "./lib/utils/events.js";

package/dist/lib/converter/comments/blockLexer.js

@@ -107,17 +107,29 @@ function* lexBlockComment2(file, pos, end, linkTags, checker) {
                 break;
             case "`": {
                 // Markdown's code rules are a royal pain. This could be one of several things.
-                // 1. Inline code: <1-n ticks><text><same number of ticks>
-                // 2. Code block: <3 ticks><language, no ticks>\n<text>\n<3 ticks>\n
+                // 1. Inline code: <1-n ticks><text without multiple consecutive newlines or ticks at start of line><same number of ticks>
+                // 2. Code block: <newline><3+ ticks><language, no ticks>\n<text>\n<3 ticks>\n
                 // 3. Unmatched tick(s), not code, but part of some text.
                 // We don't quite handle #2 correctly yet. PR welcome!
                 braceStartsType = false;
                 let tickCount = 1;
-                let lookahead = pos;
+                let lookahead = pos - 1;
+                let atNewline = true;
+                while (lookahead > 0 && file[lookahead] !== "\n") {
+                    if (/\S/.test(file[lookahead])) {
+                        if (!commentHasStars || file[lookahead] !== "*") {
+                            atNewline = false;
+                            break;
+                        }
+                    }
+                    --lookahead;
+                }
+                lookahead = pos;
                 while (lookahead + 1 < end && file[lookahead + 1] === "`") {
                     tickCount++;
                     lookahead++;
                 }
+                const isCodeBlock = atNewline && tickCount >= 3;
                 let lookaheadStart = pos;
                 const codeText = [];
                 lookahead++;
@@ -125,12 +137,18 @@ function* lexBlockComment2(file, pos, end, linkTags, checker) {
                     if (lookaheadExactlyNTicks(lookahead, tickCount)) {
                         lookahead += tickCount;
                         codeText.push(file.substring(lookaheadStart, lookahead));
-                        yield {
-                            kind: TokenSyntaxKind.Code,
-                            text: codeText.join(""),
-                            pos,
-                        };
-                        pos = lookahead;
+                        const codeTextStr = codeText.join("");
+                        if (isCodeBlock || !/\n\s*\n/.test(codeTextStr)) {
+                            yield {
+                                kind: TokenSyntaxKind.Code,
+                                text: codeTextStr,
+                                pos,
+                            };
+                            pos = lookahead;
+                        }
+                        else {
+                            yield makeToken(TokenSyntaxKind.Text, tickCount);
+                        }
                         break;
                     }
                     else if (file[lookahead] === "`") {
@@ -167,7 +185,7 @@ function* lexBlockComment2(file, pos, end, linkTags, checker) {
                     }
                 }
                 if (lookahead >= end && pos !== lookahead) {
-                    if (tickCount === 3 &&
+                    if (isCodeBlock &&
                         file.substring(pos, end).includes("\n")) {
                         codeText.push(file.substring(lookaheadStart, end));
                         yield {

package/dist/lib/converter/comments/declarationReferenceResolver.js

@@ -174,8 +174,14 @@ function resolveKeyword(refl, kw) {
 function resolveSymbolReferencePart(refl, path) {
     let high = [];
     let low = [];
-    if (!(refl instanceof ContainerReflection) ||
-        !refl.childrenIncludingDocuments) {
+    let children;
+    if (refl instanceof ContainerReflection) {
+        children = refl.childrenIncludingDocuments;
+    }
+    if (!children && refl.isDeclaration() && refl.type?.type === "reflection") {
+        children = refl.type.declaration.childrenIncludingDocuments;
+    }
+    if (!children) {
         return { high, low };
     }
     switch (path.navigation) {
@@ -184,16 +190,16 @@ function resolveSymbolReferencePart(refl, path) {
         // so that resolution doesn't behave very poorly with projects using JSDoc style resolution.
         // Also is more consistent with how TypeScript resolves link tags.
         case ".":
-            high = refl.childrenIncludingDocuments.filter((r) => r.name === path.path &&
+            high = children.filter((r) => r.name === path.path &&
                 (r.kindOf(ReflectionKind.SomeExport) || r.flags.isStatic));
-            low = refl.childrenIncludingDocuments.filter((r) => r.name === path.path &&
+            low = children.filter((r) => r.name === path.path &&
                 (!r.kindOf(ReflectionKind.SomeExport) || !r.flags.isStatic));
             break;
         // Resolve via "members", interface children, class instance properties/accessors/methods,
         // enum members, type literal properties
         case "#":
             high =
-                refl.children?.filter((r) => {
+                children?.filter((r) => {
                     return (r.name === path.path &&
                         r.kindOf(ReflectionKind.SomeMember) &&
                         !r.flags.isStatic);
@@ -203,7 +209,7 @@ function resolveSymbolReferencePart(refl, path) {
         // module/namespace exports since TypeDoc doesn't support documenting locals.
         case "~":
             if (refl.kindOf(ReflectionKind.SomeModule | ReflectionKind.Project)) {
-                high = refl.children?.filter((r) => r.name === path.path) || [];
+                high = children?.filter((r) => r.name === path.path) || [];
             }
             break;
     }

package/dist/lib/converter/comments/lineLexer.js

@@ -65,11 +65,21 @@ function* lexLineComments2(file, pos, end) {
                 // We don't quite handle #2 correctly yet. PR welcome!
                 braceStartsType = false;
                 let tickCount = 1;
-                let lookahead = pos;
+                let lookahead = pos - 1;
+                let atNewline = true;
+                while (lookahead > 0 && file[lookahead] !== "\n") {
+                    if (/\S/.test(file[lookahead])) {
+                        atNewline = false;
+                        break;
+                    }
+                    --lookahead;
+                }
+                lookahead = pos;
                 while (lookahead + 1 < end && file[lookahead + 1] === "`") {
                     tickCount++;
                     lookahead++;
                 }
+                const isCodeBlock = atNewline && tickCount >= 3;
                 let lookaheadStart = pos;
                 const codeText = [];
                 lookahead++;
@@ -77,12 +87,18 @@ function* lexLineComments2(file, pos, end) {
                     if (lookaheadExactlyNTicks(lookahead, tickCount)) {
                         lookahead += tickCount;
                         codeText.push(file.substring(lookaheadStart, lookahead));
-                        yield {
-                            kind: TokenSyntaxKind.Code,
-                            text: codeText.join(""),
-                            pos,
-                        };
-                        pos = lookahead;
+                        const codeTextStr = codeText.join("");
+                        if (isCodeBlock || !/\n\s*\n/.test(codeTextStr)) {
+                            yield {
+                                kind: TokenSyntaxKind.Code,
+                                text: codeTextStr,
+                                pos,
+                            };
+                            pos = lookahead;
+                        }
+                        else {
+                            yield makeToken(TokenSyntaxKind.Text, tickCount);
+                        }
                         break;
                     }
                     else if (file[lookahead] === "`") {

package/dist/lib/converter/comments/linkResolver.js

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import { DeclarationReflection, Reflection, ReflectionSymbolId, } from "../../models/index.js";
+import { DeclarationReflection, Reflection, ReflectionKind, ReflectionSymbolId, } from "../../models/index.js";
 import { parseDeclarationReference, } from "./declarationReference.js";
 import { resolveDeclarationReference } from "./declarationReferenceResolver.js";
 const urlPrefix = /^(http|ftp)s?:\/\//;
@@ -45,9 +45,14 @@ function resolveLinkTag(reflection, part, externalResolver, options) {
     const declRef = parseDeclarationReference(part.text, pos, end);
     // Might already know where it should go if useTsLinkResolution is turned on
     if (part.target instanceof ReflectionSymbolId) {
-        const tsTarget = reflection.project.getReflectionFromSymbolId(part.target);
-        if (tsTarget) {
-            target = tsTarget;
+        const tsTargets = reflection.project.getReflectionsFromSymbolId(part.target);
+        if (tsTargets.length) {
+            // Find the target most likely to have a real url in the generated documentation
+            target =
+                tsTargets.find((r) => r.kindOf(ReflectionKind.SomeExport)) ||
+                    tsTargets.find((r) => r.kindOf(ReflectionKind.SomeMember) &&
+                        r.parent?.kindOf(ReflectionKind.SomeExport)) ||
+                    tsTargets[0];
             pos = end;
             defaultDisplayText =
                 part.tsLinkText ||

package/dist/lib/converter/comments/rawLexer.js

@@ -43,19 +43,14 @@ function* lexCommentString2(file) {
     while (pos < end && /\s/.test(file[end - 1])) {
         end--;
     }
-    let lineStart = true;
     let expectingTag = false;
     for (;;) {
         if (pos >= end) {
             return;
         }
-        if (lineStart) {
-            lineStart = false;
-        }
         switch (file[pos]) {
             case "\n":
                 yield makeToken(TokenSyntaxKind.NewLine, 1);
-                lineStart = true;
                 expectingTag = false;
                 break;
             case "{":
@@ -68,16 +63,26 @@ function* lexCommentString2(file) {
                 break;
             case "`": {
                 // Markdown's code rules are a royal pain. This could be one of several things.
-                // 1. Inline code: <1-n ticks><text><same number of ticks>
-                // 2. Code block: <3 ticks><language, no ticks>\n<text>\n<3 ticks>\n
+                // 1. Inline code: <1-n ticks><text without multiple consecutive newlines or ticks at start of line><same number of ticks>
+                // 2. Code block: <newline><3+ ticks><language, no ticks>\n<text>\n<3 ticks>\n
                 // 3. Unmatched tick(s), not code, but part of some text.
                 // We don't quite handle #2 correctly yet. PR welcome!
                 let tickCount = 1;
-                let lookahead = pos;
+                let lookahead = pos - 1;
+                let atNewline = true;
+                while (lookahead > 0 && file[lookahead] !== "\n") {
+                    if (/\S/.test(file[lookahead])) {
+                        atNewline = false;
+                        break;
+                    }
+                    --lookahead;
+                }
+                lookahead = pos;
                 while (lookahead + 1 < end && file[lookahead + 1] === "`") {
                     tickCount++;
                     lookahead++;
                 }
+                const isCodeBlock = atNewline && tickCount >= 3;
                 let lookaheadStart = pos;
                 const codeText = [];
                 lookahead++;
@@ -85,13 +90,20 @@ function* lexCommentString2(file) {
                     if (lookaheadExactlyNTicks(lookahead, tickCount)) {
                         lookahead += tickCount;
                         codeText.push(file.substring(lookaheadStart, lookahead));
-                        yield {
-                            kind: TokenSyntaxKind.Code,
-                            text: codeText.join(""),
-                            pos,
-                        };
-                        expectingTag = false;
-                        pos = lookahead;
+                        const codeTextStr = codeText.join("");
+                        if (isCodeBlock || !/\n\s*\n/.test(codeTextStr)) {
+                            yield {
+                                kind: TokenSyntaxKind.Code,
+                                text: codeTextStr,
+                                pos,
+                            };
+                            expectingTag = false;
+                            pos = lookahead;
+                        }
+                        else {
+                            yield makeToken(TokenSyntaxKind.Text, tickCount);
+                            expectingTag = false;
+                        }
                         break;
                     }
                     else if (file[lookahead] === "`") {
@@ -114,7 +126,7 @@ function* lexCommentString2(file) {
                     }
                 }
                 if (lookahead >= end && pos !== lookahead) {
-                    if (tickCount === 3 &&
+                    if (isCodeBlock &&
                         file.substring(pos, end).includes("\n")) {
                         codeText.push(file.substring(lookaheadStart, end));
                         yield {

package/dist/lib/converter/comments/textParser.js

@@ -81,6 +81,7 @@ export function textContent(sourcePath, token, i18n, warning, outContent, files,
             addRef(tagLink);
             continue;
         }
+        data.atNewLine = token.text[data.pos] === "\n";
         ++data.pos;
     }
     if (lastPartEnd !== token.text.length) {

package/dist/lib/debug/debugReflectionLifetimes.d.ts

@@ -0,0 +1,2 @@
+import type { Application } from "../application.js";
+export declare function debugReflectionLifetimes(app: Application): void;

package/dist/lib/debug/debugReflectionLifetimes.js

@@ -0,0 +1,19 @@
+import { ConverterEvents } from "../converter/converter-events.js";
+export function debugReflectionLifetimes(app) {
+    app.converter.on(ConverterEvents.CREATE_PROJECT, logCreate);
+    app.converter.on(ConverterEvents.CREATE_SIGNATURE, logCreate);
+    app.converter.on(ConverterEvents.CREATE_TYPE_PARAMETER, logCreate);
+    app.converter.on(ConverterEvents.CREATE_DECLARATION, logCreate);
+    app.converter.on(ConverterEvents.CREATE_DOCUMENT, logCreate);
+    app.converter.on(ConverterEvents.CREATE_PARAMETER, logCreate);
+    app.converter.on(ConverterEvents.CREATE_PROJECT, (_context, project) => {
+        const oldRemove = project["_removeReflection"];
+        project["_removeReflection"] = function (reflection) {
+            console.log("Remove", reflection.id, reflection.getFullName());
+            return oldRemove.call(this, reflection);
+        };
+    });
+}
+function logCreate(_context, refl) {
+    console.log("Create", refl.variant, refl.id, refl.getFullName());
+}

package/dist/lib/debug/debugRendererUrls.d.ts

@@ -0,0 +1,5 @@
+import type { Application } from "../application.js";
+export declare function debugRendererUrls(app: Application, { json, logs }?: {
+    logs?: true;
+    json?: boolean | undefined;
+}): void;

package/dist/lib/debug/debugRendererUrls.js

@@ -0,0 +1,59 @@
+/* eslint-disable no-console */
+import { join } from "node:path";
+import { Reflection, ReflectionKind, } from "../models/index.js";
+const serializer = {
+    priority: 0,
+    supports(x) {
+        return x instanceof Reflection;
+    },
+    toObject(item, obj) {
+        obj.url = item.url;
+        obj.hasOwnDocument = item.hasOwnDocument;
+        // obj.anchor = item.anchor;
+        delete obj.sources;
+        delete obj.groups;
+        delete obj.categories;
+        delete obj.readme;
+        delete obj.content;
+        obj.kind = ReflectionKind[obj.kind];
+        delete obj.flags;
+        delete obj.defaultValue;
+        delete obj.symbolIdMap;
+        delete obj.files;
+        delete obj.packageName;
+        delete obj.variant;
+        delete obj.extendedTypes;
+        delete obj.inheritedFrom;
+        if (!["reflection", "reference"].includes(obj.type?.type)) {
+            delete obj.type;
+        }
+        if (obj.comment) {
+            obj.comment.summary = obj.comment.summary.filter((part) => part.kind === "inline-tag");
+            obj.comment.blockTags = obj.comment.blockTags?.filter((tag) => {
+                tag.content = tag.content.filter((part) => part.kind === "inline-tag");
+                return tag.content.length;
+            });
+            if (!obj.comment.summary.length &&
+                !obj.comment.blockTags?.length &&
+                !obj.comment.modifierTags) {
+                delete obj.comment;
+            }
+        }
+        return obj;
+    },
+};
+export function debugRendererUrls(app, { json = false, logs = false } = { logs: true }) {
+    app.renderer.postRenderAsyncJobs.push(async (evt) => {
+        if (json) {
+            app.serializer.addSerializer(serializer);
+            await app.generateJson(evt.project, join(evt.outputDirectory, "url_debug.json"));
+            app.serializer.removeSerializer(serializer);
+        }
+        if (logs) {
+            for (const id in evt.project.reflections) {
+                const refl = evt.project.reflections[id];
+                console.log(refl.id, refl.getFullName(), refl.url, refl.hasOwnDocument);
+            }
+        }
+    });
+}

package/dist/lib/debug/index.d.ts

@@ -0,0 +1,2 @@
+export { debugRendererUrls } from "./debugRendererUrls.js";
+export { debugReflectionLifetimes } from "./debugReflectionLifetimes.js";

package/dist/lib/debug/index.js

@@ -0,0 +1,2 @@
+export { debugRendererUrls } from "./debugRendererUrls.js";
+export { debugReflectionLifetimes } from "./debugReflectionLifetimes.js";

package/dist/lib/internationalization/internationalization.d.ts

@@ -2,7 +2,6 @@ import type { Application } from "../application.js";
 import { ReflectionKind } from "../models/reflections/kind.js";
 import { ReflectionFlag } from "../models/index.js";
 import { type BuiltinTranslatableStringArgs } from "./translatable.js";
-import translatable from "./locales/en.cjs";
 /**
  * ### What is translatable?
  * TypeDoc includes a lot of literal strings. By convention, messages which are displayed
@@ -75,7 +74,7 @@ export declare class Internationalization {
      * Get the translation of the specified key, replacing placeholders
      * with the arguments specified.
      */
-    translate<T extends keyof typeof translatable>(key: T, ...args: TranslatableStrings[T]): TranslatedString;
+    translate<T extends keyof TranslatableStrings>(key: T, ...args: TranslatableStrings[T]): TranslatedString;
     kindSingularString(kind: ReflectionKind): TranslatedString;
     kindPluralString(kind: ReflectionKind): TranslatedString;
     flagString(flag: ReflectionFlag): TranslatedString;

package/dist/lib/internationalization/locales/en.cjs

@@ -61,6 +61,7 @@ module.exports = {
     reflection_0_kind_1_defined_in_2_does_not_have_any_documentation: `{0} ({1}), defined in {2}, does not have any documentation`,
     invalid_intentionally_not_exported_symbols_0: "The following symbols were marked as intentionally not exported, but were either not referenced in the documentation, or were exported:\n\t{0}",
     reflection_0_has_unused_mergeModuleWith_tag: "{0} has a @mergeModuleWith tag which could not be resolved",
+    reflection_0_links_to_1_with_text_2_but_resolved_to_3: `"{0}" links to "{1}" with text "{2}" which exists but does not have a link in the documentation, will link to "{3}" instead.`,
     // conversion plugins
     not_all_search_category_boosts_used_0: `Not all categories specified in searchCategoryBoosts were used in the documentation. The unused categories were:\n\t{0}`,
     not_all_search_group_boosts_used_0: `Not all groups specified in searchGroupBoosts were used in the documentation. The unused groups were:\n\t{0}`,

package/dist/lib/internationalization/locales/en.d.cts

@@ -56,6 +56,7 @@ declare const _default: {
     readonly reflection_0_kind_1_defined_in_2_does_not_have_any_documentation: "{0} ({1}), defined in {2}, does not have any documentation";
     readonly invalid_intentionally_not_exported_symbols_0: "The following symbols were marked as intentionally not exported, but were either not referenced in the documentation, or were exported:\n\t{0}";
     readonly reflection_0_has_unused_mergeModuleWith_tag: "{0} has a @mergeModuleWith tag which could not be resolved";
+    readonly reflection_0_links_to_1_with_text_2_but_resolved_to_3: "\"{0}\" links to \"{1}\" with text \"{2}\" which exists but does not have a link in the documentation, will link to \"{3}\" instead.";
     readonly not_all_search_category_boosts_used_0: "Not all categories specified in searchCategoryBoosts were used in the documentation. The unused categories were:\n\t{0}";
     readonly not_all_search_group_boosts_used_0: "Not all groups specified in searchGroupBoosts were used in the documentation. The unused groups were:\n\t{0}";
     readonly comment_for_0_includes_categoryDescription_for_1_but_no_child_in_group: "Comment for {0} includes @categoryDescription for \"{1}\", but no child is placed in that category";

package/dist/lib/models/ReflectionCategory.js

@@ -52,7 +52,7 @@ export class ReflectionCategory {
             de.defer((project) => {
                 for (const childId of obj.children || []) {
                     const child = project.getReflectionById(de.oldIdToNewId[childId] ?? -1);
-                    if (child?.isDeclaration()) {
+                    if (child?.isDeclaration() || child?.isDocument()) {
                         this.children.push(child);
                     }
                 }

package/dist/lib/models/ReflectionGroup.js

@@ -68,7 +68,7 @@ export class ReflectionGroup {
             de.defer((project) => {
                 for (const childId of obj.children || []) {
                     const child = project.getReflectionById(de.oldIdToNewId[childId] ?? -1);
-                    if (child?.isDeclaration()) {
+                    if (child?.isDeclaration() || child?.isDocument()) {
                         this.children.push(child);
                     }
                 }

package/dist/lib/models/reflections/project.js

@@ -294,6 +294,7 @@ export class ProjectReflection extends ContainerReflection {
     }
     /** @internal */
     registerSymbolId(reflection, id) {
+        this.removedSymbolIds.delete(id);
         this.reflectionIdToSymbolIdMap.set(reflection.id, id);
         const previous = this.symbolToReflectionIdMap.get(id);
         if (previous) {

package/dist/lib/models/types.js

@@ -690,7 +690,11 @@ export class ReferenceType extends Type {
             : ReflectionKind.TypeReferenceTarget;
         const resolved = resolvePotential.find((refl) => refl.kindOf(kind)) ||
             resolvePotential.find((refl) => refl.kindOf(~kind));
-        this._target = resolved.id;
+        // Do not mark the type as resolved at this point so that if it
+        // points to a member which is removed (e.g. by typedoc-plugin-zod)
+        // and then replaced it still ends up pointing at the right reflection.
+        // We will lock type reference resolution when serializing to JSON.
+        // this._target = resolved.id;
         return resolved;
     }
     /**
@@ -820,6 +824,9 @@ export class ReferenceType extends Type {
         else if (this._project?.symbolIdHasBeenRemoved(this._target)) {
             target = -1;
         }
+        else if (this.reflection) {
+            target = this.reflection.id;
+        }
         else {
             target = this._target.toObject(serializer);
         }
@@ -837,7 +844,7 @@ export class ReferenceType extends Type {
         if (this.refersToTypeParameter) {
             result.refersToTypeParameter = true;
         }
-        if (typeof this._target !== "number" && this.preferValues) {
+        if (typeof target !== "number" && this.preferValues) {
             result.preferValues = true;
         }
         if (this.highlightedProperties) {

package/dist/lib/output/components.d.ts

@@ -27,7 +27,7 @@ export declare abstract class ContextAwareRendererComponent extends RendererComp
      * Regular expression to test if a string looks like an external url.
      */
     protected urlPrefix: RegExp;
-    private get hostedBaseUrl();
+    protected get hostedBaseUrl(): string;
     private accessor useHostedBaseUrlForAbsoluteLinks;
     constructor(owner: Renderer);
     private absoluteToRelativePathMap;

package/dist/lib/output/themes/MarkedPlugin.d.ts

@@ -1,5 +1,6 @@
 import { ContextAwareRendererComponent } from "../components.js";
 import { MarkdownEvent, RendererEvent, type PageEvent } from "../events.js";
+import { type ValidationOptions } from "../../utils/index.js";
 import type { BundledTheme } from "@gerrit0/mini-shiki";
 import type { DefaultThemeRenderContext, Renderer } from "../index.js";
 import { type CommentDisplayPart } from "../../models/index.js";
@@ -12,6 +13,7 @@ export declare class MarkedPlugin extends ContextAwareRendererComponent {
     accessor darkTheme: BundledTheme;
     accessor markdownItOptions: Record<string, unknown>;
     accessor markdownLinkExternal: boolean;
+    accessor validation: ValidationOptions;
     private parser?;
     private renderedRelativeLinks;
     /**

package/dist/lib/output/themes/MarkedPlugin.js

@@ -58,6 +58,9 @@ let MarkedPlugin = (() => {
     let _markdownLinkExternal_decorators;
     let _markdownLinkExternal_initializers = [];
     let _markdownLinkExternal_extraInitializers = [];
+    let _validation_decorators;
+    let _validation_initializers = [];
+    let _validation_extraInitializers = [];
     return class MarkedPlugin extends _classSuper {
         static {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
@@ -65,10 +68,12 @@ let MarkedPlugin = (() => {
             _darkTheme_decorators = [Option("darkHighlightTheme")];
             _markdownItOptions_decorators = [Option("markdownItOptions")];
             _markdownLinkExternal_decorators = [Option("markdownLinkExternal")];
+            _validation_decorators = [Option("validation")];
             __esDecorate(this, null, _lightTheme_decorators, { kind: "accessor", name: "lightTheme", static: false, private: false, access: { has: obj => "lightTheme" in obj, get: obj => obj.lightTheme, set: (obj, value) => { obj.lightTheme = value; } }, metadata: _metadata }, _lightTheme_initializers, _lightTheme_extraInitializers);
             __esDecorate(this, null, _darkTheme_decorators, { kind: "accessor", name: "darkTheme", static: false, private: false, access: { has: obj => "darkTheme" in obj, get: obj => obj.darkTheme, set: (obj, value) => { obj.darkTheme = value; } }, metadata: _metadata }, _darkTheme_initializers, _darkTheme_extraInitializers);
             __esDecorate(this, null, _markdownItOptions_decorators, { kind: "accessor", name: "markdownItOptions", static: false, private: false, access: { has: obj => "markdownItOptions" in obj, get: obj => obj.markdownItOptions, set: (obj, value) => { obj.markdownItOptions = value; } }, metadata: _metadata }, _markdownItOptions_initializers, _markdownItOptions_extraInitializers);
             __esDecorate(this, null, _markdownLinkExternal_decorators, { kind: "accessor", name: "markdownLinkExternal", static: false, private: false, access: { has: obj => "markdownLinkExternal" in obj, get: obj => obj.markdownLinkExternal, set: (obj, value) => { obj.markdownLinkExternal = value; } }, metadata: _metadata }, _markdownLinkExternal_initializers, _markdownLinkExternal_extraInitializers);
+            __esDecorate(this, null, _validation_decorators, { kind: "accessor", name: "validation", static: false, private: false, access: { has: obj => "validation" in obj, get: obj => obj.validation, set: (obj, value) => { obj.validation = value; } }, metadata: _metadata }, _validation_initializers, _validation_extraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
         #lightTheme_accessor_storage = __runInitializers(this, _lightTheme_initializers, void 0);
@@ -83,7 +88,10 @@ let MarkedPlugin = (() => {
         #markdownLinkExternal_accessor_storage = (__runInitializers(this, _markdownItOptions_extraInitializers), __runInitializers(this, _markdownLinkExternal_initializers, void 0));
         get markdownLinkExternal() { return this.#markdownLinkExternal_accessor_storage; }
         set markdownLinkExternal(value) { this.#markdownLinkExternal_accessor_storage = value; }
-        parser = __runInitializers(this, _markdownLinkExternal_extraInitializers);
+        #validation_accessor_storage = (__runInitializers(this, _markdownLinkExternal_extraInitializers), __runInitializers(this, _validation_initializers, void 0));
+        get validation() { return this.#validation_accessor_storage; }
+        set validation(value) { this.#validation_accessor_storage = value; }
+        parser = __runInitializers(this, _validation_extraInitializers);
         renderedRelativeLinks = [];
         /**
          * This needing to be here really feels hacky... probably some nicer way to do this.
@@ -158,19 +166,35 @@ let MarkedPlugin = (() => {
                                     }
                                     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.
+                                        // tried and failed during the resolution step. Warnings related to those broken links
+                                        // have already been emitted.
                                         url = context.urlTo(part.target);
                                         kindClass = ReflectionKind.classString(part.target.kind);
+                                        // If we don't have a URL the user probably linked to some deeply nested property
+                                        // which doesn't get an assigned URL. We'll walk upwards until we find a reflection
+                                        // which has a URL and link to that instead.
+                                        if (!url) {
+                                            // Walk upwards to find something we can link to.
+                                            let target = part.target.parent;
+                                            url = context.urlTo(target);
+                                            while (!url && target.parent) {
+                                                target = target.parent;
+                                                // We know we'll always end up with a URL here eventually as the
+                                                // project always has a URL.
+                                                url = context.urlTo(target);
+                                            }
+                                            if (this.validation.rewrittenLink) {
+                                                this.application.logger.warn(this.application.i18n.reflection_0_links_to_1_with_text_2_but_resolved_to_3(page.model.getFriendlyFullName(), part.target.getFriendlyFullName(), part.text, target.getFriendlyFullName()));
+                                            }
+                                        }
                                     }
                                     if (useHtml) {
                                         const text = part.tag === "@linkcode" ? `<code>${part.text}</code>` : part.text;
-                                        result.push(url
-                                            ? `<a href="${url}"${kindClass ? ` class="${kindClass}"` : ""}>${text}</a>`
-                                            : part.text);
+                                        result.push(`<a href="${url}"${kindClass ? ` class="${kindClass}"` : ""}>${text}</a>`);
                                     }
                                     else {
                                         const text = part.tag === "@linkcode" ? "`" + part.text + "`" : part.text;
-                                        result.push(url ? `[${text}](${url})` : text);
+                                        result.push(`[${text}](${url})`);
                                     }
                                 }
                                 else {
@@ -298,7 +322,9 @@ let MarkedPlugin = (() => {
                     // will be relative links. This will likely have to change with
                     // the introduction of support for customized routers whenever
                     // that becomes a real thing.
-                    if (this.markdownLinkExternal && /https?:\/\//i.test(href)) {
+                    if (this.markdownLinkExternal &&
+                        /https?:\/\//i.test(href) &&
+                        !(href + "/").startsWith(this.hostedBaseUrl)) {
                         token.attrSet("target", "_blank");
                         const classes = token.attrGet("class")?.split(" ") || [];
                         classes.push("external");

package/dist/lib/output/themes/default/DefaultTheme.js

@@ -394,12 +394,25 @@ let DefaultTheme = (() => {
                 !(reflection instanceof TypeParameterReflection)) {
                 return;
             }
-            if (!reflection.url || !DefaultTheme.URL_PREFIX.test(reflection.url)) {
+            // We support linking to reflections for types directly contained within an export
+            // but not any deeper. This is because TypeDoc may or may not render the type details
+            // for a property depending on whether or not it is deemed useful, and defining a link
+            // which might not be used may result in a link being generated which isn't valid. #2808.
+            // This should be kept in sync with the renderingChildIsUseful function.
+            if (reflection.kindOf(ReflectionKind.TypeLiteral) &&
+                (!reflection.parent?.kindOf(ReflectionKind.SomeExport) ||
+                    reflection.parent.type?.type !== "reflection")) {
+                return;
+            }
+            if ((!reflection.url || !DefaultTheme.URL_PREFIX.test(reflection.url)) &&
+                !reflection.kindOf(ReflectionKind.TypeLiteral)) {
                 let refl = reflection;
                 const parts = [refl.name];
                 while (refl.parent && refl.parent !== container && !(reflection.parent instanceof ProjectReflection)) {
                     refl = refl.parent;
                     // Avoid duplicate names for signatures
+                    // BREAKING: In 0.28, also add !refl.kindOf(ReflectionKind.TypeLiteral) to this check to improve anchor
+                    // generation by omitting useless __type prefixes.
                     if (parts[0] !== refl.name) {
                         parts.unshift(refl.name);
                     }

package/dist/lib/output/themes/default/partials/member.signatures.js

@@ -4,7 +4,7 @@ import { classNames } from "../../lib.js";
 export const memberSignatures = (context, props) => (JSX.createElement(JSX.Fragment, null,
     JSX.createElement("ul", { class: classNames({ "tsd-signatures": true }, context.getReflectionClasses(props)) }, props.signatures?.map((item) => (JSX.createElement(JSX.Fragment, null,
         JSX.createElement("li", { class: "tsd-signature tsd-anchor-link" },
-            JSX.createElement("a", { id: item.anchor, class: "tsd-anchor" }),
+            item.anchor && JSX.createElement("a", { id: item.anchor, class: "tsd-anchor" }),
             context.memberSignatureTitle(item),
             anchorIcon(context, item.anchor)),
         JSX.createElement("li", { class: "tsd-description" }, context.memberSignatureBody(item))))))));

package/dist/lib/output/themes/default/partials/typeDetails.js

@@ -133,7 +133,7 @@ function renderChild(context, child, renderAnchors, highlight) {
             JSX.createElement("h5", null,
                 !!child.flags.isRest && JSX.createElement("span", { class: "tsd-signature-symbol" }, "..."),
                 JSX.createElement("span", { class: getKindClass(child) }, child.name),
-                JSX.createElement("a", { id: child.anchor, class: "tsd-anchor" }),
+                child.anchor && JSX.createElement("a", { id: child.anchor, class: "tsd-anchor" }),
                 JSX.createElement("span", { class: "tsd-signature-symbol" },
                     !!child.flags.isOptional && "?",
                     ":"),
@@ -155,7 +155,7 @@ function renderChild(context, child, renderAnchors, highlight) {
                 context.reflectionFlags(child),
                 !!child.flags.isRest && JSX.createElement("span", { class: "tsd-signature-symbol" }, "..."),
                 JSX.createElement("span", { class: getKindClass(child) }, child.name),
-                JSX.createElement("a", { id: child.anchor, class: "tsd-anchor" }),
+                child.anchor && JSX.createElement("a", { id: child.anchor, class: "tsd-anchor" }),
                 JSX.createElement("span", { class: "tsd-signature-symbol" },
                     !!child.flags.isOptional && "?",
                     ": "),
@@ -170,7 +170,7 @@ function renderChild(context, child, renderAnchors, highlight) {
                 context.reflectionFlags(child.getSignature),
                 JSX.createElement("span", { class: "tsd-signature-keyword" }, "get "),
                 JSX.createElement("span", { class: getKindClass(child) }, child.name),
-                JSX.createElement("a", { id: child.anchor, class: "tsd-anchor" }),
+                child.anchor && JSX.createElement("a", { id: child.anchor, class: "tsd-anchor" }),
                 JSX.createElement("span", { class: "tsd-signature-symbol" }, "(): "),
                 context.type(child.getSignature.type)),
             highlightOrComment(child.getSignature))),
@@ -179,7 +179,7 @@ function renderChild(context, child, renderAnchors, highlight) {
                 context.reflectionFlags(child.setSignature),
                 JSX.createElement("span", { class: "tsd-signature-keyword" }, "set "),
                 JSX.createElement("span", { class: getKindClass(child) }, child.name),
-                !child.getSignature && JSX.createElement("a", { id: child.anchor, class: "tsd-anchor" }),
+                !child.getSignature && child.anchor && JSX.createElement("a", { id: child.anchor, class: "tsd-anchor" }),
                 JSX.createElement("span", { class: "tsd-signature-symbol" }, "("),
                 child.setSignature.parameters?.map((item) => (JSX.createElement(JSX.Fragment, null,
                     item.name,
@@ -205,6 +205,16 @@ function renderIndexSignature(context, index) {
         context.typeDeclaration(index.type)));
 }
 function renderingChildIsUseful(refl) {
+    // Object types directly under a variable/type alias will always be considered useful.
+    // This probably isn't ideal, but it is an easy thing to check when assigning URLs
+    // in the default theme, so we'll make the assumption that those properties ought to always
+    // be rendered.
+    // This should be kept in sync with the DefaultTheme.applyAnchorUrl function.
+    if (refl.kindOf(ReflectionKind.TypeLiteral) &&
+        refl.parent?.kindOf(ReflectionKind.SomeExport) &&
+        refl.parent.type?.type === "reflection") {
+        return true;
+    }
     if (renderingThisChildIsUseful(refl)) {
         return true;
     }

package/dist/lib/serialization/serializer.d.ts

@@ -34,6 +34,7 @@ export declare class Serializer extends EventDispatcher<SerializerEvents> {
      */
     project: ProjectReflection;
     addSerializer<T extends object>(serializer: SerializerComponent<T>): void;
+    removeSerializer(serializer: SerializerComponent<any>): void;
     toObject<T extends {
         toObject(serializer: Serializer): ModelToObject<T>;
     }>(value: T): ModelToObject<T>;

package/dist/lib/serialization/serializer.js

@@ -1,6 +1,6 @@
 import { EventDispatcher } from "../utils/index.js";
 import { SerializeEvent } from "./events.js";
-import { insertPrioritySorted } from "../utils/array.js";
+import { insertPrioritySorted, removeIfPresent } from "../utils/array.js";
 /**
  * Serializes TypeDoc's models to JSON
  *
@@ -30,6 +30,9 @@ export class Serializer extends EventDispatcher {
     addSerializer(serializer) {
         insertPrioritySorted(this.serializers, serializer);
     }
+    removeSerializer(serializer) {
+        removeIfPresent(this.serializers, serializer);
+    }
     toObject(value) {
         if (value === undefined) {
             return undefined;

package/dist/lib/utils/jsx.d.ts

@@ -13,7 +13,7 @@
  * @summary Custom JSX module designed specifically for TypeDoc's needs.
  * @module
  */
-import type { IntrinsicElements, JsxElement, JsxChildren, JsxComponent } from "./jsx.elements.js";
+import type { IntrinsicElements, JsxElement, JsxChildren, JsxComponent, JsxHtmlGlobalProps } from "./jsx.elements.js";
 export type { JsxElement as Element, JsxChildren as Children, JsxComponent, } from "./jsx.elements.js";
 export { JsxFragment as Fragment } from "./jsx.elements.js";
 /**
@@ -32,7 +32,7 @@ export declare function Raw(_props: {
  * @hidden
  */
 export declare namespace JSX {
-    export { IntrinsicElements, JsxElement as Element };
+    export { IntrinsicElements, JsxElement as Element, JsxHtmlGlobalProps as IntrinsicAttributes, };
 }
 /**
  * JSX factory function to create an "element" that can later be rendered with {@link renderElement}

package/dist/lib/utils/jsx.elements.d.ts

@@ -165,6 +165,17 @@ export interface JsxHtmlGlobalProps {
     tabIndex?: number;
     title?: string;
     translate?: boolean;
+    /**
+     * Default: 'auto'. true and 'auto' are equivalent
+     *
+     * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) for more details
+     */
+    popover?: boolean | "auto" | "manual";
+    /**
+     * It must be the popover element id, see [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+     */
+    popovertarget?: string;
+    popovertargetaction?: "hide" | "show" | "toggle";
 }
 /**
  * Properties permitted on the `<a>` element.

package/dist/lib/utils/options/declaration.d.ts

@@ -222,6 +222,10 @@ export type ValidationOptions = {
      * If set, TypeDoc will produce warnings about \{\@link\} tags which will produce broken links.
      */
     invalidLink: boolean;
+    /**
+     * If set, TypeDoc will produce warnings about \{\@link\} tags which do not link directly to their target.
+     */
+    rewrittenLink: boolean;
     /**
      * If set, TypeDoc will produce warnings about declarations that do not have doc comments
      */

package/dist/lib/utils/options/sources/typedoc.js

@@ -840,6 +840,7 @@ export function addTypeDocOptions(options) {
         defaults: {
             notExported: true,
             invalidLink: true,
+            rewrittenLink: true,
             notDocumented: false,
             unusedMergeModuleWith: true,
         },

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.27.4",
+  "version": "0.27.5",
   "homepage": "https://typedoc.org",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
     "./tsdoc.json": "./tsdoc.json",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./debug": "./dist/lib/debug/index.js"
   },
   "types": "./dist/index.d.ts",
   "bin": {