typedoc 0.26.0-beta.1 → 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)));
@@ -525,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;
         }
@@ -559,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,7 +227,7 @@ 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)) {
@@ -232,14 +236,14 @@ function blockTag(comment, lexer, config, i18n, warning) {
     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);
 }
@@ -247,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) {
@@ -276,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 ||
@@ -319,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();
@@ -358,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()) {
@@ -366,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;

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

@@ -0,0 +1,154 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.textContent = textContent;
+const lexer_1 = require("./lexer");
+const markdown_it_1 = __importDefault(require("markdown-it"));
+const MdHelpers = new markdown_it_1.default().helpers;
+/**
+ * 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.
+ *
+ */
+function textContent(sourcePath, token, i18n, warning, outContent, files, atNewLine) {
+    let lastPartEnd = 0;
+    const data = {
+        sourcePath,
+        token,
+        pos: 0,
+        i18n,
+        warning,
+        files: files,
+        atNewLine,
+    };
+    function addRef(ref) {
+        outContent.push({
+            kind: "text",
+            text: token.text.slice(lastPartEnd, ref.pos),
+        });
+        outContent.push({
+            kind: "relative-link",
+            text: token.text.slice(ref.pos, ref.end),
+            target: ref.target,
+        });
+        lastPartEnd = ref.end;
+        data.pos = ref.end;
+        if (!ref.target) {
+            warning(i18n.relative_path_0_does_not_exist(token.text.slice(ref.pos, ref.end)), {
+                kind: lexer_1.TokenSyntaxKind.Text,
+                pos: ref.pos,
+                text: token.text.slice(ref.pos, ref.end),
+            });
+        }
+    }
+    while (data.pos < token.text.length) {
+        const link = checkMarkdownLink(data);
+        if (link) {
+            addRef(link);
+            continue;
+        }
+        const reference = checkReference(data);
+        if (reference) {
+            addRef(reference);
+            continue;
+        }
+        ++data.pos;
+    }
+    if (lastPartEnd !== token.text.length) {
+        outContent.push({ kind: "text", text: token.text.slice(lastPartEnd) });
+    }
+}
+/**
+ * Links are inline text with the form `[ text ]( url title )`.
+ *
+ * Images are just links with a leading `!` and lack of support for `[ref]` referring to a path
+ * defined elsewhere, we don't care about that distinction here as we'll only replace the path
+ * piece of the image.
+ *
+ * Reference: https://github.com/markdown-it/markdown-it/blob/14.1.0/lib/rules_inline/link.mjs
+ * Reference: https://github.com/markdown-it/markdown-it/blob/14.1.0/lib/rules_inline/image.mjs
+ *
+ */
+function checkMarkdownLink(data) {
+    const { token, sourcePath, files } = data;
+    if (token.text[data.pos] === "[") {
+        const labelEnd = findLabelEnd(token.text, data.pos + 1);
+        if (labelEnd !== -1 &&
+            token.text[labelEnd] === "]" &&
+            token.text[labelEnd + 1] === "(") {
+            const link = MdHelpers.parseLinkDestination(token.text, labelEnd + 2, token.text.length);
+            if (link.ok) {
+                // Only make a relative-link display part if it's actually a relative link.
+                // Discard protocol:// links, unix style absolute paths, and windows style absolute paths.
+                if (isRelativeLink(link.str)) {
+                    return {
+                        pos: labelEnd + 2,
+                        end: link.pos,
+                        target: files.register(sourcePath, link.str),
+                    };
+                }
+                // This was a link, skip ahead to ensure we don't happen to parse
+                // something else as a link within the link.
+                data.pos = link.pos - 1;
+            }
+        }
+    }
+}
+/**
+ * Reference definitions are blocks with the form `[label]: link title`
+ * Reference: https://github.com/markdown-it/markdown-it/blob/14.1.0/lib/rules_block/reference.mjs
+ *
+ * Note: This may include false positives where TypeDoc recognizes a reference block that markdown
+ * does not if users start lines with something that looks like a reference block without fully
+ * separating it from an above paragraph. For a first cut, this is good enough.
+ */
+function checkReference(data) {
+    const { atNewLine, pos, token, files, sourcePath } = data;
+    if (atNewLine) {
+        let lookahead = pos;
+        while (/[ \t]/.test(token.text[lookahead])) {
+            ++lookahead;
+        }
+        if (token.text[lookahead] === "[") {
+            while (lookahead < token.text.length &&
+                /[^\n\]]/.test(token.text[lookahead])) {
+                ++lookahead;
+            }
+            if (token.text.startsWith("]:", lookahead)) {
+                lookahead += 2;
+                while (/[ \t]/.test(token.text[lookahead])) {
+                    ++lookahead;
+                }
+                const link = MdHelpers.parseLinkDestination(token.text, lookahead, token.text.length);
+                if (link.ok) {
+                    if (isRelativeLink(link.str)) {
+                        return {
+                            pos: lookahead,
+                            end: link.pos,
+                            target: files.register(sourcePath, link.str),
+                        };
+                    }
+                    data.pos = link.pos - 1;
+                }
+            }
+        }
+    }
+}
+function isRelativeLink(link) {
+    return !/^[a-z]+:\/\/|^\/|^[a-z]:\\/i.test(link);
+}
+function findLabelEnd(text, pos) {
+    while (pos < text.length) {
+        switch (text[pos]) {
+            case "\n":
+            case "]":
+                return pos;
+        }
+        ++pos;
+    }
+    return -1;
+}