typedoc 0.26.0-beta.0 → 0.26.0-beta.2

package/README.md

@@ -2,6 +2,8 @@
 
 Documentation generator for TypeScript projects.
 
+Plugins: [plugins](./internal-docs/plugins.md)
+
 [![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)
 

package/dist/lib/application.d.ts

@@ -8,6 +8,7 @@ import { Options } from "./utils";
 import type { TypeDocOptions } from "./utils/options/declaration";
 import { type DocumentationEntryPoint, EntryPointStrategy } from "./utils/entry-point";
 import { Internationalization } from "./internationalization/internationalization";
+import { FileRegistry } from "./models/FileRegistry";
 export declare function createAppForTesting(): Application;
 /**
  * The default TypeDoc main application class.
@@ -53,6 +54,7 @@ export declare class Application extends ChildableComponent<Application, Abstrac
      */
     i18n: import("./internationalization/internationalization").TranslationProxy;
     options: Options;
+    files: FileRegistry;
     /** @internal */
     accessor lang: string;
     /** @internal */

package/dist/lib/application.js

@@ -100,6 +100,7 @@ const abstract_1 = require("./models/reflections/abstract");
 const ReflectionSymbolId_1 = require("./models/reflections/ReflectionSymbolId");
 const internationalization_1 = require("./internationalization/internationalization");
 const highlighter_1 = require("./utils/highlighter");
+const FileRegistry_1 = require("./models/FileRegistry");
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const packageInfo = require("../../package.json");
 const supportedVersionMajorMinor = packageInfo.peerDependencies.typescript
@@ -108,7 +109,9 @@ const supportedVersionMajorMinor = packageInfo.peerDependencies.typescript
 const DETECTOR = Symbol();
 function createAppForTesting() {
     // @ts-expect-error private constructor
-    return new Application(DETECTOR);
+    const app = new Application(DETECTOR);
+    app.files = new FileRegistry_1.FileRegistry();
+    return app;
 }
 const DEFAULT_READERS = [
     new index_2.TypeDocReader(),
@@ -190,6 +193,7 @@ let Application = (() => {
              */
             this.i18n = this.internationalization.proxy;
             this.options = new utils_1.Options(this.i18n);
+            this.files = new FileRegistry_1.ValidatingFileRegistry();
             _Application_lang_accessor_storage.set(this, __runInitializers(this, _lang_initializers, void 0));
             _Application_skipErrorChecking_accessor_storage.set(this, (__runInitializers(this, _lang_extraInitializers), __runInitializers(this, _skipErrorChecking_initializers, void 0)));
             _Application_entryPointStrategy_accessor_storage.set(this, (__runInitializers(this, _skipErrorChecking_extraInitializers), __runInitializers(this, _entryPointStrategy_initializers, void 0)));
@@ -488,7 +492,16 @@ let Application = (() => {
             // Generate a json file for each package
             for (const dir of packageDirs) {
                 this.logger.verbose(`Reading project at ${(0, paths_1.nicePath)(dir)}`);
-                const opts = origOptions.copyForPackage(dir);
+                let opts;
+                try {
+                    opts = origOptions.copyForPackage(dir);
+                }
+                catch (error) {
+                    (0, assert_1.ok)(error instanceof Error);
+                    this.logger.error(error.message);
+                    this.logger.info(this.i18n.previous_error_occurred_when_reading_options_for_0((0, paths_1.nicePath)(dir)));
+                    continue;
+                }
                 await opts.read(this.logger, dir);
                 // Invalid links should only be reported after everything has been merged.
                 opts.setValue("validation", { invalidLink: false });
@@ -516,7 +529,7 @@ let Application = (() => {
                 return;
             }
             this.logger.info(this.i18n.merging_converted_projects());
-            const result = this.deserializer.reviveProjects(this.options.getValue("name") || "Documentation", projects);
+            const result = this.deserializer.reviveProjects(this.options.getValue("name") || "Documentation", projects, process.cwd(), this.files);
             this.trigger(application_events_1.ApplicationEvents.REVIVE, result);
             return result;
         }
@@ -550,7 +563,7 @@ let Application = (() => {
             });
             if (this.logger.hasErrors())
                 return;
-            const result = this.deserializer.reviveProjects(this.options.getValue("name"), jsonProjects);
+            const result = this.deserializer.reviveProjects(this.options.getValue("name"), jsonProjects, process.cwd(), this.files);
             this.logger.verbose(`Reviving projects took ${Date.now() - start}ms`);
             // If we only revived one project, the project documents were set for
             // it when it was created. If we revived more than one project then

package/dist/lib/converter/comments/declarationReference.d.ts

@@ -17,6 +17,7 @@ export interface Meaning {
     label?: string;
     index?: number;
 }
+export declare function meaningToString(meaning: Meaning): string;
 export interface SymbolReference {
     path?: ComponentPath[];
     meaning?: Meaning;

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

@@ -8,6 +8,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MeaningKeywords = void 0;
+exports.meaningToString = meaningToString;
 exports.parseString = parseString;
 exports.parseModuleSource = parseModuleSource;
 exports.parseSymbolReference = parseSymbolReference;
@@ -34,6 +35,19 @@ exports.MeaningKeywords = [
     "getter",
     "setter",
 ];
+function meaningToString(meaning) {
+    let result = "";
+    if (meaning.keyword) {
+        result += meaning.keyword;
+    }
+    else if (meaning.label) {
+        result += meaning.label;
+    }
+    if (typeof meaning.index === "number") {
+        result += `(${meaning.index})`;
+    }
+    return result;
+}
 // <TAB> <VT> <FF> <SP> <NBSP> <ZWNBSP> <USP>
 const WhiteSpace = /[\t\u2B7F\u240C \u00A0\uFEFF\p{White_Space}]/u;
 const LineTerminator = "\r\n\u2028\u2029";

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

@@ -22,7 +22,9 @@ function resolveDeclarationReference(reflection, ref) {
         high.push(reflection.project);
     }
     else {
-        (0, assert_1.ok)(ref.resolutionStart === "local");
+        // Work around no-unnecessary-condition, should be unnecessary... want a trap if it ever becomes false.
+        (0, assert_1.ok)(ref.resolutionStart.startsWith("local") &&
+            ref.resolutionStart.length === 5);
         // TypeScript's behavior is to first try to resolve links via variable scope, and then
         // if the link still hasn't been found, check either siblings (if comment belongs to a member)
         // or otherwise children.
@@ -128,7 +130,7 @@ function resolveKeyword(refl, kw) {
             if (refl.kindOf(models_1.ReflectionKind.ClassOrInterface |
                 models_1.ReflectionKind.TypeLiteral)) {
                 const ctor = refl.children?.find((c) => c.kindOf(models_1.ReflectionKind.Constructor));
-                return ctor?.signatures;
+                return ctor.signatures;
             }
             break;
         case "member":

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

@@ -18,6 +18,7 @@ const variablePropertyKinds = [
     typescript_1.default.SyntaxKind.PropertySignature,
     typescript_1.default.SyntaxKind.BinaryExpression,
     typescript_1.default.SyntaxKind.PropertyAssignment,
+    typescript_1.default.SyntaxKind.ShorthandPropertyAssignment,
     // class X { constructor(/** Comment */ readonly z: string) }
     typescript_1.default.SyntaxKind.Parameter,
     // Variable values
@@ -50,6 +51,9 @@ const wantedKinds = {
         typescript_1.default.SyntaxKind.BindingElement,
         typescript_1.default.SyntaxKind.ExportAssignment,
         typescript_1.default.SyntaxKind.PropertyAccessExpression,
+        typescript_1.default.SyntaxKind.PropertyDeclaration,
+        typescript_1.default.SyntaxKind.PropertyAssignment,
+        typescript_1.default.SyntaxKind.ShorthandPropertyAssignment,
     ],
     [models_1.ReflectionKind.Enum]: [
         typescript_1.default.SyntaxKind.EnumDeclaration,
@@ -68,6 +72,9 @@ const wantedKinds = {
         typescript_1.default.SyntaxKind.VariableDeclaration,
         typescript_1.default.SyntaxKind.ExportAssignment,
         typescript_1.default.SyntaxKind.PropertyAccessExpression,
+        typescript_1.default.SyntaxKind.PropertyDeclaration,
+        typescript_1.default.SyntaxKind.PropertyAssignment,
+        typescript_1.default.SyntaxKind.ShorthandPropertyAssignment,
     ],
     [models_1.ReflectionKind.Class]: [
         typescript_1.default.SyntaxKind.ClassDeclaration,
@@ -264,8 +271,7 @@ function isTopmostModuleDeclaration(node) {
  * ```
  */
 function getRootModuleDeclaration(node) {
-    while (node.parent &&
-        node.parent.kind === typescript_1.default.SyntaxKind.ModuleDeclaration) {
+    while (node.parent.kind === typescript_1.default.SyntaxKind.ModuleDeclaration) {
         const parent = node.parent;
         if (node.name.pos === parent.name.end + 1) {
             node = parent;
@@ -277,6 +283,8 @@ function getRootModuleDeclaration(node) {
     return node;
 }
 function declarationToCommentNode(node) {
+    // ts.SourceFile is a counterexample
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     if (!node.parent)
         return node;
     // const abc = 123

package/dist/lib/converter/comments/index.d.ts

@@ -2,6 +2,7 @@ import ts from "typescript";
 import { Comment, ReflectionKind } from "../../models";
 import { type Logger } from "../../utils";
 import type { CommentStyle, JsDocCompatibility } from "../../utils/options/declaration";
+import type { FileRegistry } from "../../models/FileRegistry";
 export interface CommentParserConfig {
     blockTags: Set<string>;
     inlineTags: Set<string>;
@@ -9,8 +10,8 @@ export interface CommentParserConfig {
     jsDocCompatibility: JsDocCompatibility;
 }
 export declare function clearCommentCache(): void;
-export declare function getComment(symbol: ts.Symbol, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined): Comment | undefined;
-export declare function getNodeComment(node: ts.Node, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined): Comment | undefined;
-export declare function getFileComment(file: ts.SourceFile, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined): Comment | undefined;
-export declare function getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined): Comment | undefined;
-export declare function getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag, config: CommentParserConfig, logger: Logger, checker: ts.TypeChecker | undefined): Comment | undefined;
+export declare function getComment(symbol: ts.Symbol, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
+export declare function getNodeComment(node: ts.Node, kind: ReflectionKind, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
+export declare function getFileComment(file: ts.SourceFile, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
+export declare function getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature, config: CommentParserConfig, logger: Logger, commentStyle: CommentStyle, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;
+export declare function getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag, config: CommentParserConfig, logger: Logger, checker: ts.TypeChecker | undefined, files: FileRegistry): Comment | undefined;

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

@@ -32,21 +32,21 @@ function clearCommentCache() {
     commentCache = new WeakMap();
     commentDiscoveryId = 0;
 }
-function getCommentWithCache(discovered, config, logger, checker) {
+function getCommentWithCache(discovered, config, logger, checker, files) {
     if (!discovered)
         return;
     const { file, ranges, jsDoc } = discovered;
     const cache = commentCache.get(file) || new Map();
-    if (cache?.has(ranges[0].pos)) {
+    if (cache.has(ranges[0].pos)) {
         return cache.get(ranges[0].pos).clone();
     }
     let comment;
     switch (ranges[0].kind) {
         case typescript_1.default.SyntaxKind.MultiLineCommentTrivia:
-            comment = (0, parser_1.parseComment)((0, blockLexer_1.lexBlockComment)(file.text, ranges[0].pos, ranges[0].end, jsDoc, checker), config, file, logger);
+            comment = (0, parser_1.parseComment)((0, blockLexer_1.lexBlockComment)(file.text, ranges[0].pos, ranges[0].end, jsDoc, checker), config, file, logger, files);
             break;
         case typescript_1.default.SyntaxKind.SingleLineCommentTrivia:
-            comment = (0, parser_1.parseComment)((0, lineLexer_1.lexLineComments)(file.text, ranges), config, file, logger);
+            comment = (0, parser_1.parseComment)((0, lineLexer_1.lexLineComments)(file.text, ranges), config, file, logger, files);
             break;
         default:
             (0, utils_1.assertNever)(ranges[0].kind);
@@ -56,8 +56,8 @@ function getCommentWithCache(discovered, config, logger, checker) {
     commentCache.set(file, cache);
     return comment.clone();
 }
-function getCommentImpl(commentSource, config, logger, moduleComment, checker) {
-    const comment = getCommentWithCache(commentSource, config, logger, checker);
+function getCommentImpl(commentSource, config, logger, moduleComment, checker, files) {
+    const comment = getCommentWithCache(commentSource, config, logger, checker, files);
     if (moduleComment && comment) {
         // Module comment, make sure it is tagged with @packageDocumentation or @module.
         // If it isn't then the comment applies to the first statement in the file, so throw it away.
@@ -75,15 +75,15 @@ function getCommentImpl(commentSource, config, logger, moduleComment, checker) {
     }
     return comment;
 }
-function getComment(symbol, kind, config, logger, commentStyle, checker) {
+function getComment(symbol, kind, config, logger, commentStyle, checker, files) {
     const declarations = symbol.declarations || [];
     if (declarations.length &&
         declarations.every((d) => jsDocCommentKinds.includes(d.kind))) {
-        return getJsDocComment(declarations[0], config, logger, checker);
+        return getJsDocComment(declarations[0], config, logger, checker, files);
     }
     const sf = declarations.find(typescript_1.default.isSourceFile);
     if (sf) {
-        return getFileComment(sf, config, logger, commentStyle, checker);
+        return getFileComment(sf, config, logger, commentStyle, checker, files);
     }
     const isModule = declarations.some((decl) => {
         if (typescript_1.default.isModuleDeclaration(decl) && typescript_1.default.isStringLiteral(decl.name)) {
@@ -91,18 +91,18 @@ function getComment(symbol, kind, config, logger, commentStyle, checker) {
         }
         return false;
     });
-    const comment = getCommentImpl((0, discovery_1.discoverComment)(symbol, kind, logger, commentStyle), config, logger, isModule, checker);
+    const comment = getCommentImpl((0, discovery_1.discoverComment)(symbol, kind, logger, commentStyle), config, logger, isModule, checker, files);
     if (!comment && kind === models_1.ReflectionKind.Property) {
-        return getConstructorParamPropertyComment(symbol, config, logger, commentStyle, checker);
+        return getConstructorParamPropertyComment(symbol, config, logger, commentStyle, checker, files);
     }
     return comment;
 }
-function getNodeComment(node, kind, config, logger, commentStyle, checker) {
-    return getCommentImpl((0, discovery_1.discoverNodeComment)(node, commentStyle), config, logger, kind === models_1.ReflectionKind.Module, checker);
+function getNodeComment(node, kind, config, logger, commentStyle, checker, files) {
+    return getCommentImpl((0, discovery_1.discoverNodeComment)(node, commentStyle), config, logger, kind === models_1.ReflectionKind.Module, checker, files);
 }
-function getFileComment(file, config, logger, commentStyle, checker) {
+function getFileComment(file, config, logger, commentStyle, checker, files) {
     for (const commentSource of (0, discovery_1.discoverFileComments)(file, commentStyle)) {
-        const comment = getCommentWithCache(commentSource, config, logger, checker);
+        const comment = getCommentWithCache(commentSource, config, logger, checker, files);
         if (comment?.getTag("@license") || comment?.getTag("@import")) {
             continue;
         }
@@ -113,12 +113,12 @@ function getFileComment(file, config, logger, commentStyle, checker) {
         return;
     }
 }
-function getConstructorParamPropertyComment(symbol, config, logger, commentStyle, checker) {
+function getConstructorParamPropertyComment(symbol, config, logger, commentStyle, checker, files) {
     const decl = symbol.declarations?.find(typescript_1.default.isParameter);
     if (!decl)
         return;
     const ctor = decl.parent;
-    const comment = getSignatureComment(ctor, config, logger, commentStyle, checker);
+    const comment = getSignatureComment(ctor, config, logger, commentStyle, checker, files);
     const paramTag = comment?.getIdentifiedTag(symbol.name, "@param");
     if (paramTag) {
         const result = new models_1.Comment(paramTag.content);
@@ -126,10 +126,10 @@ function getConstructorParamPropertyComment(symbol, config, logger, commentStyle
         return result;
     }
 }
-function getSignatureComment(declaration, config, logger, commentStyle, checker) {
-    return getCommentImpl((0, discovery_1.discoverSignatureComment)(declaration, commentStyle), config, logger, false, checker);
+function getSignatureComment(declaration, config, logger, commentStyle, checker, files) {
+    return getCommentImpl((0, discovery_1.discoverSignatureComment)(declaration, commentStyle), config, logger, false, checker, files);
 }
-function getJsDocComment(declaration, config, logger, checker) {
+function getJsDocComment(declaration, config, logger, checker, files) {
     const file = declaration.getSourceFile();
     // First, get the whole comment. We know we'll need all of it.
     let parent = declaration.parent;
@@ -147,7 +147,7 @@ function getJsDocComment(declaration, config, logger, checker) {
             },
         ],
         jsDoc: parent,
-    }, config, logger, checker);
+    }, config, logger, checker, files);
     // And pull out the tag we actually care about.
     if (typescript_1.default.isJSDocEnumTag(declaration)) {
         const result = new models_1.Comment(comment.getTag("@enum")?.content);

package/dist/lib/converter/comments/parser.d.ts

@@ -3,7 +3,8 @@ import { Comment, type CommentDisplayPart } from "../../models";
 import { type Logger } from "../../utils";
 import type { MinimalSourceFile } from "../../utils/minimalSourceFile";
 import { type Token } from "./lexer";
-export declare function parseComment(tokens: Generator<Token, undefined, undefined>, config: CommentParserConfig, file: MinimalSourceFile, logger: Logger): Comment;
+import { FileRegistry } from "../../models/FileRegistry";
+export declare function parseComment(tokens: Generator<Token, undefined, undefined>, config: CommentParserConfig, file: MinimalSourceFile, logger: Logger, files: FileRegistry): Comment;
 /**
  * Intended for parsing markdown documents. This only parses code blocks and
  * inline tags outside of code blocks, everything else is text.
@@ -11,7 +12,7 @@ export declare function parseComment(tokens: Generator<Token, undefined, undefin
  * If you change this, also look at blockContent, as it likely needs similar
  * modifications to ensure parsing is consistent.
  */
-export declare function parseCommentString(tokens: Generator<Token, undefined, undefined>, config: CommentParserConfig, file: MinimalSourceFile, logger: Logger): {
+export declare function parseCommentString(tokens: Generator<Token, undefined, undefined>, config: CommentParserConfig, file: MinimalSourceFile, logger: Logger, files: FileRegistry): {
     content: CommentDisplayPart[];
     frontmatter: Record<string, unknown>;
 };

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

@@ -32,6 +32,8 @@ const utils_1 = require("../../utils");
 const paths_1 = require("../../utils/paths");
 const lexer_1 = require("./lexer");
 const tagName_1 = require("./tagName");
+const FileRegistry_1 = require("../../models/FileRegistry");
+const textParser_1 = require("./textParser");
 function makeLookaheadGenerator(gen) {
     let trackHistory = false;
     const history = [];
@@ -64,14 +66,14 @@ function makeLookaheadGenerator(gen) {
         },
     };
 }
-function parseComment(tokens, config, file, logger) {
+function parseComment(tokens, config, file, logger, files) {
     const lexer = makeLookaheadGenerator(tokens);
     const tok = lexer.done() || lexer.peek();
     const comment = new models_1.Comment();
     comment.sourcePath = file.fileName;
-    comment.summary = blockContent(comment, lexer, config, logger.i18n, warningImpl);
+    comment.summary = blockContent(comment, lexer, config, logger.i18n, warningImpl, files);
     while (!lexer.done()) {
-        comment.blockTags.push(blockTag(comment, lexer, config, logger.i18n, warningImpl));
+        comment.blockTags.push(blockTag(comment, lexer, config, logger.i18n, warningImpl, files));
     }
     const tok2 = tok;
     postProcessComment(comment, logger.i18n, () => `${(0, paths_1.nicePath)(file.fileName)}:${file.getLineAndCharacterOfPosition(tok2.pos).line + 1}`, (message) => logger.warn(message));
@@ -87,7 +89,7 @@ function parseComment(tokens, config, file, logger) {
  * If you change this, also look at blockContent, as it likely needs similar
  * modifications to ensure parsing is consistent.
  */
-function parseCommentString(tokens, config, file, logger) {
+function parseCommentString(tokens, config, file, logger, files) {
     const suppressWarningsConfig = {
         ...config,
         jsDocCompatibility: {
@@ -99,6 +101,7 @@ function parseCommentString(tokens, config, file, logger) {
     };
     const content = [];
     const lexer = makeLookaheadGenerator(tokens);
+    let atNewLine = false;
     while (!lexer.done()) {
         let consume = true;
         const next = lexer.peek();
@@ -111,7 +114,7 @@ function parseCommentString(tokens, config, file, logger) {
             case lexer_1.TokenSyntaxKind.Text:
             case lexer_1.TokenSyntaxKind.Tag:
             case lexer_1.TokenSyntaxKind.CloseBrace:
-                content.push({ kind: "text", text: next.text });
+                (0, textParser_1.textContent)(file.fileName, next, logger.i18n, (msg, token) => logger.warn(msg, token.pos, file), content, files, atNewLine);
                 break;
             case lexer_1.TokenSyntaxKind.Code:
                 content.push({ kind: "code", text: next.text });
@@ -123,6 +126,7 @@ function parseCommentString(tokens, config, file, logger) {
             default:
                 (0, utils_1.assertNever)(next.kind);
         }
+        atNewLine = next.kind === lexer_1.TokenSyntaxKind.NewLine;
         if (consume) {
             lexer.take();
         }
@@ -223,20 +227,23 @@ function postProcessComment(comment, i18n, getPosition, warning) {
     }
 }
 const aliasedTags = new Map([["@return", "@returns"]]);
-function blockTag(comment, lexer, config, i18n, warning) {
+function blockTag(comment, lexer, config, i18n, warning, files) {
     const blockTag = lexer.take();
     (0, assert_1.ok)(blockTag.kind === lexer_1.TokenSyntaxKind.Tag, "blockTag called not at the start of a block tag."); // blockContent is broken if this fails.
+    if (!config.blockTags.has(blockTag.text)) {
+        warning(i18n.unknown_block_tag_0(blockTag.text), blockTag);
+    }
     const tagName = aliasedTags.get(blockTag.text) || blockTag.text;
     let content;
     if (tagName === "@example") {
-        return exampleBlock(comment, lexer, config, i18n, warning);
+        return exampleBlock(comment, lexer, config, i18n, warning, files);
     }
     else if (["@default", "@defaultValue"].includes(tagName) &&
         config.jsDocCompatibility.defaultTag) {
-        content = defaultBlockContent(comment, lexer, config, i18n, warning);
+        content = defaultBlockContent(comment, lexer, config, i18n, warning, files);
     }
     else {
-        content = blockContent(comment, lexer, config, i18n, warning);
+        content = blockContent(comment, lexer, config, i18n, warning, files);
     }
     return new models_1.CommentTag(tagName, content);
 }
@@ -244,13 +251,14 @@ function blockTag(comment, lexer, config, i18n, warning) {
  * The `@default` tag gets a special case because otherwise we will produce many warnings
  * about unescaped/mismatched/missing braces in legacy JSDoc comments
  */
-function defaultBlockContent(comment, lexer, config, i18n, warning) {
+function defaultBlockContent(comment, lexer, config, i18n, warning, files) {
     lexer.mark();
-    const content = blockContent(comment, lexer, config, i18n, () => { });
+    const tempRegistry = new FileRegistry_1.FileRegistry();
+    const content = blockContent(comment, lexer, config, i18n, () => { }, tempRegistry);
     const end = lexer.done() || lexer.peek();
     lexer.release();
     if (content.some((part) => part.kind === "code")) {
-        return blockContent(comment, lexer, config, i18n, warning);
+        return blockContent(comment, lexer, config, i18n, warning, files);
     }
     const tokens = [];
     while ((lexer.done() || lexer.peek()) !== end) {
@@ -273,9 +281,10 @@ function defaultBlockContent(comment, lexer, config, i18n, warning) {
  *
  * In TSDoc, we also want to treat the first line of the block as the example name.
  */
-function exampleBlock(comment, lexer, config, i18n, warning) {
+function exampleBlock(comment, lexer, config, i18n, warning, files) {
     lexer.mark();
-    const content = blockContent(comment, lexer, config, i18n, () => { });
+    const tempRegistry = new FileRegistry_1.FileRegistry();
+    const content = blockContent(comment, lexer, config, i18n, () => { }, tempRegistry);
     const end = lexer.done() || lexer.peek();
     lexer.release();
     if (!config.jsDocCompatibility.exampleTag ||
@@ -316,7 +325,7 @@ function exampleBlock(comment, lexer, config, i18n, warning) {
                     (0, utils_1.assertNever)(next.kind);
             }
         }
-        const content = blockContent(comment, lexer, config, i18n, warning);
+        const content = blockContent(comment, lexer, config, i18n, warning, files);
         const tag = new models_1.CommentTag("@example", content);
         if (exampleName.trim()) {
             tag.name = exampleName.trim();
@@ -355,7 +364,7 @@ function exampleBlock(comment, lexer, config, i18n, warning) {
  * If you change this, also look at parseCommentString as it
  * likely needs similar modifications to ensure parsing is consistent.
  */
-function blockContent(comment, lexer, config, i18n, warning) {
+function blockContent(comment, lexer, config, i18n, warning, files) {
     const content = [];
     let atNewLine = true;
     loop: while (!lexer.done()) {
@@ -363,9 +372,12 @@ function blockContent(comment, lexer, config, i18n, warning) {
         let consume = true;
         switch (next.kind) {
             case lexer_1.TokenSyntaxKind.NewLine:
-            case lexer_1.TokenSyntaxKind.Text:
                 content.push({ kind: "text", text: next.text });
                 break;
+            case lexer_1.TokenSyntaxKind.Text:
+                (0, textParser_1.textContent)(comment.sourcePath, next, i18n, warning, 
+                /*out*/ content, files, atNewLine);
+                break;
             case lexer_1.TokenSyntaxKind.Code:
                 content.push({ kind: "code", text: next.text });
                 break;

package/dist/lib/converter/comments/textParser.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Parser to handle plain text markdown.
+ *
+ * Responsible for recognizing relative paths within the text and turning
+ * them into references.
+ * @module
+ */
+import type { TranslationProxy, TranslatedString } from "../../internationalization";
+import type { CommentDisplayPart } from "../../models";
+import type { FileRegistry } from "../../models/FileRegistry";
+import { type Token } from "./lexer";
+/**
+ * Look for relative links within a piece of text and add them to the {@link FileRegistry}
+ * so that they can be correctly resolved during rendering.
+ *
+ * TODO: We also handle `<a>` and `<img>` tags with relative targets here.
+ *
+ */
+export declare function textContent(sourcePath: string, token: Token, i18n: TranslationProxy, warning: (msg: TranslatedString, token: Token) => void, outContent: CommentDisplayPart[], files: FileRegistry, atNewLine: boolean): void;