typedoc 0.26.0-beta.2 → 0.26.0-beta.3

package/README.md

@@ -2,8 +2,6 @@
 
 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.js

@@ -259,6 +259,11 @@ let Application = (() => {
                         .join("\n\t")));
                 this.logger.info("You can define/override local locales with the `locales` option, or contribute them to TypeDoc!");
             }
+            if (this.options.getValue("useHostedBaseUrlForAbsoluteLinks") &&
+                !this.options.getValue("hostedBaseUrl")) {
+                this.logger.warn(this.i18n.useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl());
+                this.options.setValue("useHostedBaseUrlForAbsoluteLinks", false);
+            }
         }
         setOptions(options, reportErrors = true) {
             for (const [key, val] of Object.entries(options)) {

package/dist/lib/cli.js

@@ -83,6 +83,7 @@ async function run(app) {
     }
     if (app.options.getValue("watch")) {
         app.convertAndWatch(async (project) => {
+            app.validate(project);
             const json = app.options.getValue("json");
             if (!json || app.options.isSet("out")) {
                 await app.generateDocs(project, app.options.getValue("out"));

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

@@ -284,7 +284,6 @@ function getRootModuleDeclaration(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

@@ -11,7 +11,7 @@ export interface CommentParserConfig {
 }
 export declare function clearCommentCache(): void;
 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 getNodeComment(node: ts.Node, moduleComment: boolean, 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

@@ -97,8 +97,8 @@ function getComment(symbol, kind, config, logger, commentStyle, checker, files)
     }
     return comment;
 }
-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 getNodeComment(node, moduleComment, config, logger, commentStyle, checker, files) {
+    return getCommentImpl((0, discovery_1.discoverNodeComment)(node, commentStyle), config, logger, moduleComment, checker, files);
 }
 function getFileComment(file, config, logger, commentStyle, checker, files) {
     for (const commentSource of (0, discovery_1.discoverFileComments)(file, commentStyle)) {

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

@@ -12,8 +12,5 @@ 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

@@ -4,15 +4,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.textContent = textContent;
+const html_1 = require("../../utils/html");
 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;
@@ -56,6 +54,11 @@ function textContent(sourcePath, token, i18n, warning, outContent, files, atNewL
             addRef(reference);
             continue;
         }
+        const tagLink = checkTagLink(data);
+        if (tagLink) {
+            addRef(tagLink);
+            continue;
+        }
         ++data.pos;
     }
     if (lastPartEnd !== token.text.length) {
@@ -138,6 +141,39 @@ function checkReference(data) {
         }
     }
 }
+/**
+ * Looks for `<a href="./relative">` and `<img src="./relative">`
+ */
+function checkTagLink(data) {
+    const { pos, token } = data;
+    if (token.text.startsWith("<img ", pos)) {
+        data.pos += 4;
+        return checkAttribute(data, "src");
+    }
+    if (token.text.startsWith("<a ", pos)) {
+        data.pos += 3;
+        return checkAttribute(data, "href");
+    }
+}
+function checkAttribute(data, attr) {
+    const parser = new html_1.HtmlAttributeParser(data.token.text, data.pos);
+    while (parser.state !== html_1.ParserState.END) {
+        if (parser.state === html_1.ParserState.BeforeAttributeValue &&
+            parser.currentAttributeName === attr) {
+            parser.step();
+            if (isRelativeLink(parser.currentAttributeValue)) {
+                data.pos = parser.pos;
+                return {
+                    pos: parser.currentAttributeValueStart,
+                    end: parser.currentAttributeValueEnd,
+                    target: data.files.register(data.sourcePath, parser.currentAttributeValue),
+                };
+            }
+            return;
+        }
+        parser.step();
+    }
+}
 function isRelativeLink(link) {
     return !/^[a-z]+:\/\/|^\/|^[a-z]:\\/i.test(link);
 }

package/dist/lib/converter/context.d.ts

@@ -1,5 +1,5 @@
 import ts from "typescript";
-import { type Reflection, type ProjectReflection, DeclarationReflection, ReflectionKind, type DocumentReflection } from "../models/index";
+import { type Reflection, type ProjectReflection, DeclarationReflection, type DocumentReflection, ReflectionKind } from "../models/index";
 import type { Converter } from "./converter";
 import type { TranslationProxy } from "../internationalization/internationalization";
 /**
@@ -84,7 +84,7 @@ export declare class Context {
     /** @internal */
     setActiveProgram(program: ts.Program | undefined): void;
     getComment(symbol: ts.Symbol, kind: ReflectionKind): import("../models/index").Comment | undefined;
-    getNodeComment(node: ts.Node, kind: ReflectionKind): import("../models/index").Comment | undefined;
+    getNodeComment(node: ts.Node, moduleComment: boolean): import("../models/index").Comment | undefined;
     getFileComment(node: ts.SourceFile): import("../models/index").Comment | undefined;
     getJsDocComment(declaration: ts.JSDocPropertyLikeTag | ts.JSDocCallbackTag | ts.JSDocTypedefTag | ts.JSDocTemplateTag | ts.JSDocEnumTag): import("../models/index").Comment | undefined;
     getSignatureComment(declaration: ts.SignatureDeclaration | ts.JSDocSignature): import("../models/index").Comment | undefined;

package/dist/lib/converter/context.js

@@ -73,12 +73,10 @@ class Context {
             if (node.symbol) {
                 nodeType = this.checker.getDeclaredTypeOfSymbol(node.symbol);
                 // The TS types lie due to ts.SourceFile
-                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             }
             else if (node.parent?.symbol) {
                 nodeType = this.checker.getDeclaredTypeOfSymbol(node.parent.symbol);
                 // The TS types lie due to ts.SourceFile
-                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             }
             else if (node.parent?.parent?.symbol) {
                 nodeType = this.checker.getDeclaredTypeOfSymbol(node.parent.parent.symbol);
@@ -190,8 +188,8 @@ class Context {
     getComment(symbol, kind) {
         return (0, comments_1.getComment)(symbol, kind, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
     }
-    getNodeComment(node, kind) {
-        return (0, comments_1.getNodeComment)(node, kind, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
+    getNodeComment(node, moduleComment) {
+        return (0, comments_1.getNodeComment)(node, moduleComment, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);
     }
     getFileComment(node) {
         return (0, comments_1.getFileComment)(node, this.converter.config, this.logger, this.converter.commentStyle, this.converter.useTsLinkResolution ? this.checker : undefined, this.project.files);

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

@@ -177,5 +177,6 @@ export declare class Converter extends ChildableComponent<Application, Converter
     /** @internal */
     isExternal(symbol: ts.Symbol): boolean;
     processDocumentTags(reflection: Reflection, parent: ContainerReflection): void;
+    private addDocument;
     private _buildCommentParserConfig;
 }

package/dist/lib/converter/converter.js

@@ -221,11 +221,15 @@ let Converter = (() => {
         addProjectDocuments(project) {
             const projectDocuments = (0, utils_1.getDocumentEntryPoints)(this.application.logger, this.application.options);
             for (const { displayName, path } of projectDocuments) {
-                const file = new utils_1.MinimalSourceFile((0, utils_1.readFile)(path), path);
-                const { content, frontmatter } = this.parseRawComment(file, project.files);
-                const docRefl = new index_1.DocumentReflection(displayName, project, content, frontmatter);
-                project.addChild(docRefl);
-                project.registerReflection(docRefl, undefined, path);
+                let file;
+                try {
+                    file = new utils_1.MinimalSourceFile((0, utils_1.readFile)(path), path);
+                }
+                catch (error) {
+                    this.application.logger.error(this.application.logger.i18n.failed_to_read_0_when_processing_project_document(path));
+                    continue;
+                }
+                this.addDocument(project, file, displayName);
             }
         }
         /** @internal */
@@ -407,11 +411,56 @@ let Converter = (() => {
                         this.application.logger.warn(this.application.logger.i18n.failed_to_read_0_when_processing_document_tag_in_1((0, paths_1.nicePath)(path), (0, paths_1.nicePath)(reflection.comment.sourcePath)));
                         continue;
                     }
-                    const { content, frontmatter } = this.parseRawComment(file, reflection.project.files);
-                    const docRefl = new index_1.DocumentReflection((0, path_1.basename)(file.fileName).replace(/\.[^.]+$/, ""), parent, content, frontmatter);
-                    parent.addChild(docRefl);
-                    parent.project.registerReflection(docRefl, undefined, file.fileName);
+                    this.addDocument(parent, file, (0, path_1.basename)(file.fileName).replace(/\.[^.]+$/, ""));
+                }
+            }
+        }
+        addDocument(parent, file, displayName) {
+            const { content, frontmatter } = this.parseRawComment(file, parent.project.files);
+            const children = frontmatter["children"];
+            delete frontmatter["children"];
+            const docRefl = new index_1.DocumentReflection(displayName, parent, content, frontmatter);
+            parent.addChild(docRefl);
+            parent.project.registerReflection(docRefl, undefined, file.fileName);
+            const childrenToAdd = [];
+            if (children && typeof children === "object") {
+                if (Array.isArray(children)) {
+                    for (const child of children) {
+                        if (typeof child === "string") {
+                            childrenToAdd.push([
+                                (0, path_1.basename)(child).replace(/\.[^.]+$/, ""),
+                                child,
+                            ]);
+                        }
+                        else {
+                            this.application.logger.error(this.application.i18n.frontmatter_children_0_should_be_an_array_of_strings_or_object_with_string_values((0, paths_1.nicePath)(file.fileName)));
+                            return;
+                        }
+                    }
+                }
+                else {
+                    for (const [name, path] of Object.entries(children)) {
+                        if (typeof path === "string") {
+                            childrenToAdd.push([name, path]);
+                        }
+                        else {
+                            this.application.logger.error(this.application.i18n.frontmatter_children_0_should_be_an_array_of_strings_or_object_with_string_values((0, paths_1.nicePath)(file.fileName)));
+                            return;
+                        }
+                    }
+                }
+            }
+            for (const [displayName, path] of childrenToAdd) {
+                const absPath = (0, path_1.resolve)((0, path_1.dirname)(file.fileName), path);
+                let childFile;
+                try {
+                    childFile = new utils_1.MinimalSourceFile((0, utils_1.readFile)(absPath), absPath);
+                }
+                catch (error) {
+                    this.application.logger.error(this.application.logger.i18n.failed_to_read_0_when_processing_document_child_in_1(path, (0, paths_1.nicePath)(file.fileName)));
+                    continue;
                 }
+                this.addDocument(docRefl, childFile, displayName);
             }
         }
         _buildCommentParserConfig() {

package/dist/lib/converter/factories/index-signature.js

@@ -18,7 +18,7 @@ function convertIndexSignatures(context, symbol) {
         const param = indexDeclaration.parameters[0];
         (0, assert_1.default)(param && typescript_1.default.isParameter(param));
         const index = new models_1.SignatureReflection("__index", models_1.ReflectionKind.IndexSignature, context.scope);
-        index.comment = context.getNodeComment(indexDeclaration, index.kind);
+        index.comment = context.getNodeComment(indexDeclaration, false);
         index.parameters = [
             new models_1.ParameterReflection(param.name.getText(), models_1.ReflectionKind.Parameter, index),
         ];

package/dist/lib/converter/symbols.js

@@ -198,6 +198,9 @@ function convertTypeAlias(context, symbol, exportSymbol) {
         }
         const reflection = context.createDeclarationReflection(models_1.ReflectionKind.TypeAlias, symbol, exportSymbol);
         reflection.type = context.converter.convertType(context.withScope(reflection), declaration.type);
+        if (reflection.type.type === "union") {
+            attachUnionComments(context, declaration, reflection.type);
+        }
         context.finalizeDeclarationReflection(reflection);
         // Do this after finalization so that the CommentPlugin can get @typeParam tags
         // from the parent comment. Ugly, but works for now. Should be cleaned up eventually.
@@ -211,6 +214,25 @@ function convertTypeAlias(context, symbol, exportSymbol) {
         (0, jsdoc_1.convertJsDocCallback)(context, symbol, declaration, exportSymbol);
     }
 }
+function attachUnionComments(context, declaration, union) {
+    const list = declaration.type.getChildAt(0);
+    if (list.kind !== typescript_1.default.SyntaxKind.SyntaxList)
+        return;
+    let unionIndex = 0;
+    for (const child of list.getChildren()) {
+        const comment = context.getNodeComment(child, false);
+        if (comment?.modifierTags.size || comment?.blockTags.length) {
+            context.logger.warn(context.logger.i18n.comment_for_0_should_not_contain_block_or_modifier_tags(`${context.scope.getFriendlyFullName()}.${unionIndex}`), child);
+        }
+        if (comment) {
+            union.elementSummaries ||= Array.from({ length: union.types.length }, () => []);
+            union.elementSummaries[unionIndex] = comment.summary;
+        }
+        if (child.kind !== typescript_1.default.SyntaxKind.BarToken) {
+            ++unionIndex;
+        }
+    }
+}
 function convertTypeAliasAsInterface(context, symbol, exportSymbol, declaration) {
     const reflection = context.createDeclarationReflection(models_1.ReflectionKind.Interface, symbol, exportSymbol);
     context.finalizeDeclarationReflection(reflection);

package/dist/lib/converter/types.js

@@ -53,7 +53,6 @@ function loadConverters() {
         jsDocNonNullableTypeConverter,
     ]) {
         for (const key of actor.kind) {
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             if (key === undefined) {
                 // Might happen if running on an older TS version.
                 continue;
@@ -672,6 +671,7 @@ const unionConverter = {
     },
     convertType(context, type) {
         const types = type.types.map((type) => convertType(context, type));
+        normalizeUnion(types);
         sortLiteralUnion(types);
         return new models_1.UnionType(types);
     },
@@ -735,3 +735,22 @@ function sortLiteralUnion(types) {
         return aLit.value - bLit.value;
     });
 }
+function normalizeUnion(types) {
+    let trueIndex = -1;
+    let falseIndex = -1;
+    for (let i = 0; i < types.length && (trueIndex === -1 || falseIndex === -1); i++) {
+        const t = types[i];
+        if (t instanceof models_1.LiteralType) {
+            if (t.value === true) {
+                trueIndex = i;
+            }
+            if (t.value === false) {
+                falseIndex = i;
+            }
+        }
+    }
+    if (trueIndex !== -1 && falseIndex !== -1) {
+        types.splice(Math.max(trueIndex, falseIndex), 1);
+        types.splice(Math.min(trueIndex, falseIndex), 1, new models_1.IntrinsicType("boolean"));
+    }
+}

package/dist/lib/converter/utils/base-path.js

@@ -101,12 +101,17 @@ class BasePath {
      * @returns Normalized version of the given path.
      */
     static normalize(path) {
-        // Ensure forward slashes
-        path = path.replace(/\\/g, "/");
-        // Remove all surrounding quotes
-        path = path.replace(/^["']+|["']+$/g, "");
-        // Make Windows drive letters upper case
-        return path.replace(/^([^:]+):\//, (_m, m1) => m1.toUpperCase() + ":/");
+        if (process.platform === "win32") {
+            // Ensure forward slashes
+            path = path.replace(/\\/g, "/");
+            // Msys2 git on windows will give paths which use unix-style
+            // absolute paths, like /c/users/you. Since the rest of TypeDoc
+            // expects drive letters, convert it to that here.
+            path = path.replace(/^\/([a-zA-Z])\//, (_m, m1) => `${m1}:/`);
+            // Make Windows drive letters upper case
+            path = path.replace(/^([^:]+):\//, (_m, m1) => m1.toUpperCase() + ":/");
+        }
+        return path;
     }
 }
 exports.BasePath = BasePath;

package/dist/lib/converter/utils/repository.js

@@ -52,9 +52,9 @@ class GitRepository {
         this.path = path;
         this.gitRevision = gitRevision;
         this.urlTemplate = urlTemplate;
-        const out = git("-C", path, "ls-files");
+        const out = git("-C", path, "ls-files", "-z");
         if (out.status === 0) {
-            out.stdout.split("\n").forEach((file) => {
+            out.stdout.split("\0").forEach((file) => {
                 if (file !== "") {
                     this.files.add(base_path_1.BasePath.normalize(path + "/" + file));
                 }

package/dist/lib/internationalization/internationalization.js

@@ -9,7 +9,6 @@ const path_1 = require("path");
 const kind_1 = require("../models/reflections/kind");
 // If we're running in ts-node, then we need the TS source rather than
 // the compiled file.
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
 const ext = process[Symbol.for("ts-node.register.instance")]
     ? "cts"
     : "cjs";

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

@@ -21,9 +21,13 @@ export declare const translatable: {
     readonly entrypoint_did_not_match_files_0: "The entrypoint glob {0} did not match any files.";
     readonly failed_to_parse_json_0: "Failed to parse file at {0} as json.";
     readonly failed_to_read_0_when_processing_document_tag_in_1: "Failed to read file {0} when processing @document tag for comment in {1}";
+    readonly failed_to_read_0_when_processing_project_document: "Failed to read file {0} when adding project document";
+    readonly failed_to_read_0_when_processing_document_child_in_1: "Failed to read file {0} when processing document children in {1}";
+    readonly frontmatter_children_0_should_be_an_array_of_strings_or_object_with_string_values: "Frontmatter children in {0} should be an array of strings or an object with string values.";
     readonly converting_union_as_interface: "Using @interface on a union type will discard properties not present on all branches of the union. TypeDoc's output may not accurately describe your source code.";
     readonly converting_0_as_class_requires_value_declaration: "Converting {0} as a class requires a declaration which represents a non-type value.";
     readonly converting_0_as_class_without_construct_signatures: "{0} is being converted as a class, but does not have any construct signatures";
+    readonly comment_for_0_should_not_contain_block_or_modifier_tags: "The comment for {0} should not contain any block or modifier tags.";
     readonly symbol_0_has_multiple_declarations_with_comment: "{0} has multiple declarations with a comment. An arbitrary comment will be used.";
     readonly comments_for_0_are_declared_at_1: "The comments for {0} are declared at:\n\t{1}";
     readonly multiple_type_parameters_on_template_tag_unsupported: "TypeDoc does not support multiple type parameters defined in a single @template tag with a comment.";
@@ -150,6 +154,7 @@ export declare const translatable: {
     readonly help_sourceLinkExternal: "Specifies that source links should be treated as external links to be opened in a new tab.";
     readonly help_githubPages: "Generate a .nojekyll file to prevent 404 errors in GitHub Pages. Defaults to `true`.";
     readonly help_hostedBaseUrl: "Specify a base URL to be used in generating a sitemap.xml in our output folder and canonical links. If not specified, no sitemap will be generated.";
+    readonly help_useHostedBaseUrlForAbsoluteLinks: "If set, TypeDoc will produce absolute links to pages on your site using the hostedBaseUrl option.";
     readonly help_gaID: "Set the Google Analytics tracking ID and activate tracking code.";
     readonly help_hideGenerator: "Do not print the TypeDoc link at the end of the page.";
     readonly help_customFooterHtml: "Custom footer after the TypeDoc link.";
@@ -208,6 +213,7 @@ export declare const translatable: {
     readonly highlight_theme_0_must_be_one_of_1: "{0} must be one of the following: {1}";
     readonly highlightLanguages_contains_invalid_languages_0: "highlightLanguages contains invalid languages: {0}, run typedoc --help for a list of supported languages.";
     readonly hostedBaseUrl_must_start_with_http: "hostedBaseUrl must start with http:// or https://";
+    readonly useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: "The useHostedBaseUrlForAbsoluteLinks option requires that hostedBaseUrl be set";
     readonly option_0_must_be_an_object: "The '{0}' option must be a non-array object.";
     readonly option_0_must_be_a_function: "The '{0}' option must be a function.";
     readonly option_0_must_be_object_with_urls: "{0} must be an object with string labels as keys and URL values.";

package/dist/lib/internationalization/translatable.js

@@ -30,9 +30,13 @@ exports.translatable = {
     entrypoint_did_not_match_files_0: "The entrypoint glob {0} did not match any files.",
     failed_to_parse_json_0: `Failed to parse file at {0} as json.`,
     failed_to_read_0_when_processing_document_tag_in_1: `Failed to read file {0} when processing @document tag for comment in {1}`,
+    failed_to_read_0_when_processing_project_document: `Failed to read file {0} when adding project document`,
+    failed_to_read_0_when_processing_document_child_in_1: `Failed to read file {0} when processing document children in {1}`,
+    frontmatter_children_0_should_be_an_array_of_strings_or_object_with_string_values: "Frontmatter children in {0} should be an array of strings or an object with string values.",
     converting_union_as_interface: `Using @interface on a union type will discard properties not present on all branches of the union. TypeDoc's output may not accurately describe your source code.`,
     converting_0_as_class_requires_value_declaration: `Converting {0} as a class requires a declaration which represents a non-type value.`,
     converting_0_as_class_without_construct_signatures: `{0} is being converted as a class, but does not have any construct signatures`,
+    comment_for_0_should_not_contain_block_or_modifier_tags: `The comment for {0} should not contain any block or modifier tags.`,
     symbol_0_has_multiple_declarations_with_comment: `{0} has multiple declarations with a comment. An arbitrary comment will be used.`,
     comments_for_0_are_declared_at_1: `The comments for {0} are declared at:\n\t{1}`,
     // comments/parser.ts
@@ -169,6 +173,7 @@ exports.translatable = {
     help_sourceLinkExternal: "Specifies that source links should be treated as external links to be opened in a new tab.",
     help_githubPages: "Generate a .nojekyll file to prevent 404 errors in GitHub Pages. Defaults to `true`.",
     help_hostedBaseUrl: "Specify a base URL to be used in generating a sitemap.xml in our output folder and canonical links. If not specified, no sitemap will be generated.",
+    help_useHostedBaseUrlForAbsoluteLinks: "If set, TypeDoc will produce absolute links to pages on your site using the hostedBaseUrl option.",
     help_gaID: "Set the Google Analytics tracking ID and activate tracking code.",
     help_hideGenerator: "Do not print the TypeDoc link at the end of the page.",
     help_customFooterHtml: "Custom footer after the TypeDoc link.",
@@ -230,6 +235,7 @@ exports.translatable = {
     highlight_theme_0_must_be_one_of_1: "{0} must be one of the following: {1}",
     highlightLanguages_contains_invalid_languages_0: "highlightLanguages contains invalid languages: {0}, run typedoc --help for a list of supported languages.",
     hostedBaseUrl_must_start_with_http: "hostedBaseUrl must start with http:// or https://",
+    useHostedBaseUrlForAbsoluteLinks_requires_hostedBaseUrl: "The useHostedBaseUrlForAbsoluteLinks option requires that hostedBaseUrl be set",
     option_0_must_be_an_object: "The '{0}' option must be a non-array object.",
     option_0_must_be_a_function: "The '{0}' option must be a function.",
     option_0_must_be_object_with_urls: `{0} must be an object with string labels as keys and URL values.`,

package/dist/lib/models/comments/comment.d.ts

@@ -4,14 +4,33 @@ import type { Serializer, Deserializer, JSONOutput } from "../../serialization";
 /**
  * Represents a parsed piece of a comment.
  * @category Comments
+ * @see {@link JSONOutput.CommentDisplayPart}
  */
-export type CommentDisplayPart = {
+export type CommentDisplayPart = 
+/**
+ * Represents a plain text portion of the comment, may contain markdown
+ */
+{
     kind: "text";
     text: string;
-} | {
+}
+/**
+ * Represents a code block separated out form the plain text entry so
+ * that TypeDoc knows to skip it when parsing relative links and inline tags.
+ **/
+ | {
     kind: "code";
     text: string;
-} | InlineTagDisplayPart | RelativeLinkDisplayPart;
+}
+/**
+ * Represents an inline tag like `{@link Foo}`
+ */
+ | InlineTagDisplayPart
+/**
+ * Represents a reference to a path relative to where the comment resides.
+ * This is used to detect and copy relative image links.
+ */
+ | RelativeLinkDisplayPart;
 /**
  * The `@link`, `@linkcode`, and `@linkplain` tags may have a `target`
  * property set indicating which reflection/url they link to. They may also
@@ -63,6 +82,12 @@ export declare class CommentTag {
      * The actual body text of this tag.
      */
     content: CommentDisplayPart[];
+    /**
+     * A flag which may be set by plugins to prevent TypeDoc from rendering this tag, if the plugin provides
+     * custom rendering. Note: This flag is **not** serialized, it is expected to be set just before the comment
+     * is rendered.
+     */
+    skipRendering: boolean;
     /**
      * Create a new CommentTag instance.
      */

package/dist/lib/models/comments/comment.js

@@ -49,6 +49,12 @@ class CommentTag {
      * Create a new CommentTag instance.
      */
     constructor(tag, text) {
+        /**
+         * A flag which may be set by plugins to prevent TypeDoc from rendering this tag, if the plugin provides
+         * custom rendering. Note: This flag is **not** serialized, it is expected to be set just before the comment
+         * is rendered.
+         */
+        this.skipRendering = false;
         this.tag = tag;
         this.content = text;
     }

package/dist/lib/models/reflections/document.d.ts

@@ -19,9 +19,14 @@ export declare class DocumentReflection extends Reflection {
      * boosting search relevance scores at runtime. May be modified by plugins.
      */
     relevanceBoost?: number;
+    /**
+     * Child documents, if any are present.
+     */
+    children?: DocumentReflection[];
     constructor(name: string, parent: Reflection, content: CommentDisplayPart[], frontmatter: Record<string, unknown>);
+    addChild(child: DocumentReflection): void;
     isDocument(): this is DocumentReflection;
-    traverse(_callback: TraverseCallback): void;
+    traverse(callback: TraverseCallback): void;
     toObject(serializer: Serializer): JSONOutput.DocumentReflection;
     fromObject(de: Deserializer, obj: JSONOutput.DocumentReflection): void;
 }

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

@@ -18,11 +18,19 @@ class DocumentReflection extends abstract_1.Reflection {
             delete frontmatter["title"];
         }
     }
+    addChild(child) {
+        this.children ||= [];
+        this.children.push(child);
+    }
     isDocument() {
         return true;
     }
-    traverse(_callback) {
-        // Nothing to do here, we have no children.
+    traverse(callback) {
+        for (const child of this.children || []) {
+            if (callback(child, abstract_1.TraverseProperty.Documents) === false) {
+                return;
+            }
+        }
     }
     toObject(serializer) {
         return {
@@ -31,6 +39,7 @@ class DocumentReflection extends abstract_1.Reflection {
             content: comments_1.Comment.serializeDisplayParts(serializer, this.content),
             frontmatter: this.frontmatter,
             relevanceBoost: this.relevanceBoost,
+            children: serializer.toObjectsOptional(this.children),
         };
     }
     fromObject(de, obj) {
@@ -38,6 +47,7 @@ class DocumentReflection extends abstract_1.Reflection {
         this.content = comments_1.Comment.deserializeDisplayParts(de, obj.content);
         this.frontmatter = obj.frontmatter;
         this.relevanceBoost = obj.relevanceBoost;
+        this.children = de.reviveMany(obj.children, (obj) => de.reflectionBuilders.document(this, obj));
     }
 }
 exports.DocumentReflection = DocumentReflection;

package/dist/lib/models/reflections/kind.d.ts

@@ -35,6 +35,7 @@ export declare enum ReflectionKind {
 /** @category Reflections */
 export declare namespace ReflectionKind {
     type KindString = EnumKeys<typeof ReflectionKind>;
+    /** @internal */
     const All: number;
     /** @internal */
     const ClassOrInterface: number;
@@ -56,6 +57,7 @@ export declare namespace ReflectionKind {
     const SomeMember: number;
     /** @internal */
     const SomeExport: number;
+    /** @internal */
     const MayContainDocuments: number;
     /** @internal */
     const ExportContainer: number;

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

@@ -37,6 +37,7 @@ var ReflectionKind;
 })(ReflectionKind || (exports.ReflectionKind = ReflectionKind = {}));
 /** @category Reflections */
 (function (ReflectionKind) {
+    /** @internal */
     ReflectionKind.All = ReflectionKind.Reference * 2 - 1;
     /** @internal */
     ReflectionKind.ClassOrInterface = ReflectionKind.Class | ReflectionKind.Interface;
@@ -79,7 +80,8 @@ var ReflectionKind;
         ReflectionKind.Interface |
         ReflectionKind.TypeAlias |
         ReflectionKind.Reference;
-    ReflectionKind.MayContainDocuments = ReflectionKind.SomeExport | ReflectionKind.Project;
+    /** @internal */
+    ReflectionKind.MayContainDocuments = ReflectionKind.SomeExport | ReflectionKind.Project | ReflectionKind.Document;
     /** @internal */
     ReflectionKind.ExportContainer = ReflectionKind.SomeModule | ReflectionKind.Project;
     /** @internal */

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

@@ -298,6 +298,7 @@ class ProjectReflection extends container_1.ContainerReflection {
         }
         this.files.fromObject(de, obj.files);
         de.defer(() => {
+            // Unnecessary conditional in release
             for (const [id, sid] of Object.entries(obj.symbolIdMap || {})) {
                 const refl = this.getReflectionById(de.oldIdToNewId[+id] ?? -1);
                 if (refl) {