Merge remote-tracking branch 'origin/master' into beta

Author: Gerrit0

CHANGELOG.md

@@ -52,6 +52,47 @@ TODO:
 
 # Unreleased
 
+## v0.26.11 (2024-11-01)
+
+### Features
+
+-   If `hostedBaseUrl` is set to the root page on a website, TypeDoc will now include `WebSite` structured data, #2760.
+
+### Bug Fixes
+
+-   Fix support for ESM config files with Node 23, #2752.
+-   Fix type errors when using `"module": "ESNext"` and importing TypeDoc, #2747.
+-   Inherited comments on overloaded methods now consider the overload position when inheriting a comment, #2755.
+
+## v0.26.10 (2024-10-16)
+
+### Bug Fixes
+
+-   Fixed missing space on page headers, #2748.
+
+## v0.26.9 (2024-10-11)
+
+### Features
+
+-   Added `headings` option to control optional headings, #2729.
+-   Updated Chinese translations, #2739.
+-   Added a folder icon to page navigation elements which are not links, #2741.
+
+### Bug Fixes
+
+-   `externalSymbolLinkMappings` now uses the TypeScript reported link target if available, #2725.
+-   TypeDoc will no longer omit the modules page if a project contains only modules/documents, #2730.
+-   Fixed missing breadcrumbs on project page, #2728.
+-   TypeDoc will no longer render an empty readme page if no readme was found.
+
+### Thanks!
+
+-   @lriggle-strib
+-   @mrfigg
+-   @XeroAlpha
+
+## v0.26.8 (2024-10-04)
+
 ### Features
 
 -   Updated Chinese translations, #2706.

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "typedoc",
   "description": "Create api documentation for TypeScript projects.",
-  "version": "0.26.8",
+  "version": "0.26.11",
   "homepage": "https://typedoc.org",
   "type": "module",
   "exports": {
@@ -50,8 +50,8 @@
     "semver": "^7.6.3",
     "ts-node": "^10.9.2",
     "tsx": "^4.15.7",
-    "typescript-eslint": "^8.4.0",
-    "typescript": "5.6.1-rc"
+    "typescript": "5.6.3",
+    "typescript-eslint": "^8.4.0"
   },
   "files": [
     "/bin",

package.json

@@ -1,21 +1,48 @@
 // @ts-check
 import esbuild from "esbuild";
+import fs from "node:fs";
 
-const context = await esbuild.context({
-    entryPoints: ["src/lib/output/themes/default/assets/bootstrap.ts"],
-    bundle: true,
-    minify: true,
-    outfile: "static/main.js",
-    banner: {
-        js: '"use strict";',
+const watch = process.argv.slice(2).some((t) => t == "--watch" || t == "-w");
+
+// It's convenient to be able to build the themes in watch mode without rebuilding the whole docs
+// to test some change to the frontend JS.
+/** @type {esbuild.Plugin} */
+const copyToDocsPlugin = {
+    name: "copyToDocs",
+    setup(build) {
+        if (watch) {
+            build.onEnd((result) => {
+                if (
+                    !result.errors.length &&
+                    fs.existsSync("docs/assets/main.js")
+                ) {
+                    fs.copyFileSync("static/main.js", "docs/assets/main.js");
+                }
+            });
+        }
     },
-    logLevel: "info",
-});
+};
+
+async function main() {
+    const context = await esbuild.context({
+        entryPoints: ["src/lib/output/themes/default/assets/bootstrap.ts"],
+        bundle: true,
+        minify: true,
+        outfile: "static/main.js",
+        logLevel: "info",
+        plugins: [copyToDocsPlugin],
+    });
 
-await context.rebuild();
+    await context.rebuild();
 
-if (process.argv.slice(2).includes("--watch")) {
-    await context.watch();
-} else {
-    await context.dispose();
+    if (watch) {
+        await context.watch();
+    } else {
+        await context.dispose();
+    }
 }
+
+main().catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+});

scripts/build_themes.js

@@ -502,13 +502,33 @@ function declarationToCommentNodes(
             },
         ];
 
+    let overloadIndex: number | undefined = undefined;
+    if (ts.isMethodDeclaration(node)) {
+        const symbol = checker.getSymbolAtLocation(node.name || node);
+        if (symbol) {
+            overloadIndex = symbol.declarations
+                ?.filter((d) => d.kind === node.kind)
+                .indexOf(node);
+            ok(overloadIndex !== -1, "Should always find declaration");
+        }
+    }
+
     const seenSymbols = new Set<ts.Symbol>();
     const bases = findBaseOfDeclaration(checker, node, (symbol) => {
         if (!seenSymbols.has(symbol)) {
             seenSymbols.add(symbol);
-            return symbol.declarations?.map(
-                (node) => declarationToCommentNodeIgnoringParents(node) || node,
-            );
+            if (overloadIndex === undefined) {
+                return symbol.declarations?.map(
+                    (node) =>
+                        declarationToCommentNodeIgnoringParents(node) || node,
+                );
+            } else if (symbol.declarations?.[overloadIndex]) {
+                const parentSigNode = symbol.declarations[overloadIndex];
+                return [
+                    declarationToCommentNodeIgnoringParents(parentSigNode) ||
+                        parentSigNode,
+                ];
+            }
         }
     });
 

src/lib/converter/comments/discovery.ts

@@ -234,7 +234,21 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
     constructor(owner: Application) {
         super(owner);
 
-        this.addUnknownSymbolResolver((ref) => {
+        const userConfiguredSymbolResolver: ExternalSymbolResolver = (
+            ref,
+            refl,
+            _part,
+            symbolId,
+        ) => {
+            if (symbolId) {
+                return userConfiguredSymbolResolver(
+                    symbolId.toDeclarationReference(),
+                    refl,
+                    undefined,
+                    undefined,
+                );
+            }
+
             // Require global links, matching local ones will likely hide mistakes where the
             // user meant to link to a local type.
             if (ref.resolutionStart !== "global" || !ref.symbolReference) {
@@ -261,7 +275,8 @@ export class Converter extends AbstractComponent<Application, ConverterEvents> {
             if (typeof modLinks["*"] === "string") {
                 return modLinks["*"];
             }
-        });
+        };
+        this.addUnknownSymbolResolver(userConfiguredSymbolResolver);
 
         new CategoryPlugin(this);
         new CommentPlugin(this);

src/lib/converter/converter.ts

@@ -291,6 +291,7 @@ export = {
     help_sidebarLinks: "Defines links to be included in the sidebar",
     help_navigationLeaves:
         "Branches of the navigation tree which should not be expanded",
+    help_headings: "Determines which optional headings are rendered",
     help_navigation: "Determines how the navigation sidebar is organized",
     help_visibilityFilters:
         "Specify the default visibility for builtin filters and additional filters according to modifier tags",

src/lib/internationalization/locales/en.cts

@@ -287,6 +287,7 @@ export = localeUtils.buildIncompleteTranslation({
     help_sidebarLinks: "定义要包含在侧边栏中的链接",
     help_navigationLeaves: "导航树中不应扩展的分支",
     help_navigation: "确定导航侧边栏的组织方式",
+    help_headings: "确定标题是否需要被渲染",
     help_visibilityFilters:
         "根据修饰符标签指定内置过滤器和附加过滤器的默认可见性",
     help_searchCategoryBoosts: "配置搜索以提高所选类别的相关性",

src/lib/internationalization/locales/zh.cts

@@ -12,7 +12,7 @@ const ICONS_JS = `
     function addIcons() {
         if (document.readyState === "loading") return document.addEventListener("DOMContentLoaded", addIcons);
         const svg = document.body.appendChild(document.createElementNS("http://www.w3.org/2000/svg", "svg"));
-        svg.innerHTML = \`"SVG_HTML"\`;
+        svg.innerHTML = \`SVG_HTML\`;
         svg.style.display = "none";
         if (location.protocol === "file:") updateUseElements();
     }
@@ -50,7 +50,11 @@ export class IconsPlugin extends RendererComponent {
         const icons = (this.owner.theme as DefaultTheme).icons;
 
         for (const [name, icon] of Object.entries(icons)) {
-            children.push(<g id={`icon-${name}`}>{icon.call(icons).children}</g>);
+            children.push(
+                <g id={`icon-${name}`} class="tsd-no-select">
+                    {icon.call(icons).children}
+                </g>,
+            );
         }
 
         const svg = renderElement(<svg xmlns="http://www.w3.org/2000/svg">{children}</svg>);

src/lib/output/plugins/IconsPlugin.tsx

@@ -169,14 +169,9 @@ export class DefaultTheme extends Theme {
         const urls: UrlMapping[] = [];
         this.sluggers.set(project, new Slugger());
 
-        if (!hasReadme(this.application.options.getValue("readme"))) {
+        if (!project.readme?.length) {
             project.url = "index.html";
             urls.push(new UrlMapping<ContainerReflection>("index.html", project, this.reflectionTemplate));
-        } else if (project.children?.every((child) => child.kindOf(ReflectionKind.Module))) {
-            // If there are no non-module children, then there's no point in having a modules page since there
-            // will be nothing on it besides the navigation, so redirect the module page to the readme page
-            project.url = "index.html";
-            urls.push(new UrlMapping("index.html", project, this.indexTemplate));
         } else {
             project.url = "modules.html";
             urls.push(new UrlMapping("modules.html", project, this.reflectionTemplate));
@@ -476,10 +471,6 @@ export class DefaultTheme extends Theme {
     }
 }
 
-function hasReadme(readme: string) {
-    return !readme.endsWith("none");
-}
-
 function getReflectionClasses(
     reflection: DeclarationReflection | DocumentReflection,
     filters: Record<string, boolean>,

src/lib/output/themes/default/DefaultTheme.tsx

@@ -103,7 +103,8 @@ function addNavText(
         }
         a.appendChild(document.createElement("span")).textContent = el.text;
     } else {
-        parent.appendChild(document.createElement("span")).textContent =
-            el.text;
+        const span = parent.appendChild(document.createElement("span"));
+        span.innerHTML = `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" class="tsd-kind-icon"><use href="#icon-folder"></use></svg>`;
+        span.appendChild(document.createElement("span")).textContent = el.text;
     }
 }

src/lib/output/themes/default/assets/typedoc/Navigation.ts

@@ -20,6 +20,34 @@ function favicon(context: DefaultThemeRenderContext) {
     }
 }
 
+// See #2760
+function buildSiteMetadata(context: DefaultThemeRenderContext) {
+    try {
+        // We have to know where we are hosted in order to generate this block
+        const url = new URL(context.options.getValue("hostedBaseUrl"));
+
+        // No point in generating this if we aren't the root page on the site
+        if (url.pathname !== "/") {
+            return null;
+        }
+
+        return (
+            <script type="application/ld+json">
+                <Raw
+                    html={JSON.stringify({
+                        "@context": "https://schema.org",
+                        "@type": "WebSite",
+                        name: context.page.project.name,
+                        url: url.toString(),
+                    })}
+                />
+            </script>
+        );
+    } catch {
+        return null;
+    }
+}
+
 export const defaultLayout = (
     context: DefaultThemeRenderContext,
     template: RenderTemplate<PageEvent<Reflection>>,
@@ -36,6 +64,7 @@ export const defaultLayout = (
                     : `${getDisplayName(props.model)} | ${getDisplayName(props.project)}`}
             </title>
             {favicon(context)}
+            {props.url === "index.html" && buildSiteMetadata(context)}
             <meta name="description" content={"Documentation for " + props.project.name} />
             <meta name="viewport" content="width=device-width, initial-scale=1" />