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

.config/typedoc.json

@@ -15,6 +15,8 @@
     ],
     "name": "TypeDoc API",
 
+    // Don't document the debug entry point
+    "entryPoints": ["../src/index.ts"],
     "outputs": [
         {
             "name": "html",
@@ -36,6 +38,7 @@
     "categorizeByGroup": false,
     "categoryOrder": ["Reflections", "Types", "Comments", "*"],
     "groupOrder": ["Common", "Namespaces", "*"],
+    "hostedBaseUrl": "https://typedoc.org/example/",
     "navigationLinks": {
         "Docs": "https://typedoc.org",
         "Example": "https://typedoc.org/example/index.html",

.github/ISSUE_TEMPLATE/bug_report.md

@@ -22,6 +22,8 @@ labels: bug
 Note: Turn off skipErrorChecks before reporting a crash. Bug reports for crashes with that option
 on are out of scope.
 
+Note: Please try to reproduce the issue WITHOUT any plugins enabled before reporting a bug.
+
 If possible, please create a *minimal* repo reproducing your problem.
 If it is more than a single small file, please submit a pull request to
 https://github.com/TypeStrong/typedoc-repros

.github/workflows/build-site.yml

@@ -1,5 +1,9 @@
 name: Build Site
-on: [push, pull_request]
+on:
+    push:
+    pull_request:
+    schedule:
+        - cron: "0 5 * * *"
 jobs:
     build:
         runs-on: ubuntu-latest

CHANGELOG.md

@@ -10,6 +10,62 @@ title: Changelog
 
 ## Unreleased
 
+## v0.27.5 (2024-12-14)
+
+### Bug Fixes
+
+-   Possibly Breaking: TypeDoc will no longer render anchors within the page for
+    deeply nested properties. This only affects links to properties of
+    properties of types, which did not have a clickable link exposed so are
+    unlikely to have been linked to. Furthermore, these links were not always
+    created by TypeDoc, only being created if all parent properties contained
+    comments, #2808.
+-   TypeDoc will now warn if a property which does not have a URL within the
+    rendered document and the parent property/page will be linked to instead,
+    #2808. These warnings can be disabled with the `validation.rewrittenLink`
+    option.
+-   Fix restoration of groups/categories including documents, #2801.
+-   Fixed missed relative paths within markdown link references in documents.
+-   Improved handling of incomplete inline code blocks within markdown.
+-   Direct `https://` links under the `hostedBaseUrl` option's URL will no
+    longer be treated as external, #2809.
+
+### Thanks!
+
+-   @SacDeNoeuds
+
+## v0.27.4 (2024-12-09)
+
+### Features
+
+-   API: Introduced new `Converter.EVENT_CREATE_PROJECT` event which fires when a project is created by the converter, #2800.
+
+### Bug Fixes
+
+-   Switch from gzip to deflate for compressing assets to make output consistent across different operating systems, #2796.
+-   `@include` and `@includeCode` now work for comments on the entry point for projects with a single entry point, #2800.
+-   Cascaded modifier tags will no longer be copied into type literals, #2802.
+-   `@summary` now works to describe functions within modules, #2803.
+-   Corrected navigation showing module link as current when not on module page, #2805.
+
+## v0.27.3 (2024-12-04)
+
+### Features
+
+-   Added support for PNG favicons, #2790.
+-   Improved support for hosting TypeDoc with strict Content Security Policy rules, #2794.
+
+### Bug Fixes
+
+-   Add special handling for import types with type errors discarded with ts-expect-error, #2792.
+-   Fixed low contrast in default colors for properties/accessors in light mode, #2795.
+-   The `highlightLanguages` option now permits Shiki aliases to be specified rather than just the language ID, #2798.
+
+### Thanks!
+
+-   @mikalai-snap
+-   @mistic100
+
 ## v0.27.2 (2024-11-29)
 
 ### Bug Fixes

README.md

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

eslint.config.mjs

@@ -140,6 +140,7 @@ export default tslint.config(
             "eslint.config.mjs",
             "src/test/renderer/specs",
             "site/typedoc-plugin-redirect.js",
+            "site/site-plugin.js",
             "dist",
             "docs",
             "docs2",

example/typedoc.json

@@ -11,6 +11,7 @@
     "searchGroupBoosts": {
         "Classes": 1.5
     },
+    "hostedBaseUrl": "https://typedoc.org/example/",
     "navigationLinks": {
         "Docs": "https://typedoc.org",
         "API": "https://typedoc.org/api/index.html",

package.json

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

scripts/capture_screenshots.mjs

@@ -93,6 +93,9 @@ export async function captureScreenshots(
     headless,
     theme,
 ) {
+    await fs.promises.rm(outputDirectory, { force: true, recursive: true });
+    await fs.promises.mkdir(outputDirectory, { recursive: true });
+
     const browser = await puppeteer.launch({
         args:
             platform() === "win32"

site/declaration-references.md

@@ -4,9 +4,10 @@ title: Declaration References
 
 # Declaration References
 
-Note: If [--useTsLinkResolution](options/comments.md#usetslinkresolution) is turned on (the default) this page likely
-**does not apply** for your links. Declaration references are used only if that option is off or TypeScript
-fails to resolve a link.
+> [!note]
+> If [--useTsLinkResolution](options/comments.md#usetslinkresolution) is turned on (the default) this page likely
+> **does not apply** for your links. Declaration references are used only if that option is off or TypeScript
+> fails to resolve a link.
 
 Some tags like [`{@link}`](tags/link.md) and [`{@inheritDoc}`](tags/inheritDoc.md) can refer to other
 members of the documentation. These tags use declaration references to name another declaration.

site/development/plugins.md

@@ -13,7 +13,8 @@ to. Plugins should assume that they may be loaded multiple times for different
 applications, and that a single load of an application class may be used to
 convert multiple projects.
 
-Plugins may be either ESM or CommonJS.
+Plugins may be either ESM or CommonJS, but TypeDoc ships with ESM, so they should
+generally published as ESM to avoid `require(esm)` experimental warnings.
 
 ```js
 // @ts-check

site/development/themes.md

@@ -102,4 +102,34 @@ export function load(app: Application) {
 }
 ```
 
+## Registering your own custom elements/attributes
+
+Custom JSX elements can be defined by merging with TypeDoc's `IntrinsicElements`
+interface. TypeScript will pick up properties of this interface as valid element
+names.
+
+```ts
+import { Application, JSX } from "typedoc";
+
+declare module "typedoc" {
+    // JSX.JSX is intentional due to TypeScript's strange JSX type discovery rules
+    namespace JSX.JSX {
+        interface IntrinsicElements {
+            "custom-button": IntrinsicAttributes & {
+                target: string;
+            };
+        }
+
+        // Generally shouldn't be necessary, TypeDoc contains an interface
+        // with all attributes documented on MDN. Properties added here will
+        // be permitted on all JSX elements.
+        interface IntrinsicAttributes {
+            customGlobalAttribute?: string;
+        }
+    }
+}
+
+export function load(app: Application) {}
+```
+
 [RendererHooks]: https://typedoc.org/api/interfaces/RendererHooks.html

site/options.md

@@ -13,148 +13,43 @@ children:
 Any command line arguments that are passed without a flag will be parsed as entry points.
 Any options passed on the command line will override options set in a configuration file.
 
-<!--
-Updating these lists can be easily done by going to each page and running the
-following JS to copy what they should be to your clipboard. Ideally, someday this
-becomes automated...
-
-copy($$(".tsd-page-navigation > .tsd-accordion-details > a").map(a => [a.textContent, a.href.substring(a.href.lastIndexOf("/") + "/Options.".length).replace(/^./, x => x[0].toLowerCase()).replace(".html", ".md").replace("md:", "")]).map(l => `-   [${l[0]}](options/${l[1]})`).join("\n"))
--->
-
 ## Configuration Options
 
 Options which control what files TypeDoc reads.
 
--   [options](options/configuration.md#options)
--   [tsconfig](options/configuration.md#tsconfig)
--   [compilerOptions](options/configuration.md#compileroptions)
--   [plugin](options/configuration.md#plugin)
+{@listOptions options/configuration.md}
 
 ## Input Options
 
 Options which control how input is converted into a project that can be rendered
 to HTML or JSON.
 
--   [entryPoints](options/input.md#entrypoints)
--   [entryPointStrategy](options/input.md#entrypointstrategy)
--   [packageOptions](options/input.md#packageoptions)
--   [alwaysCreateEntryPointModule](options/input.md#alwayscreateentrypointmodule)
--   [projectDocuments](options/input.md#projectdocuments)
--   [exclude](options/input.md#exclude)
--   [externalPattern](options/input.md#externalpattern)
--   [excludeExternals](options/input.md#excludeexternals)
--   [excludeNotDocumented](options/input.md#excludenotdocumented)
--   [excludeNotDocumentedKinds](options/input.md#excludenotdocumentedkinds)
--   [excludeInternal](options/input.md#excludeinternal)
--   [excludePrivate](options/input.md#excludeprivate)
--   [excludeProtected](options/input.md#excludeprotected)
--   [excludeReferences](options/input.md#excludereferences)
--   [excludeCategories](options/input.md#excludecategories)
--   [maxTypeConversionDepth](options/input.md#maxtypeconversiondepth)
--   [name](options/input.md#name)
--   [includeVersion](options/input.md#includeversion)
--   [disableSources](options/input.md#disablesources)
--   [sourceLinkTemplate](options/input.md#sourcelinktemplate)
--   [gitRevision](options/input.md#gitrevision)
--   [gitRemote](options/input.md#gitremote)
--   [disableGit](options/input.md#disablegit)
--   [readme](options/input.md#readme)
--   [includeHierarchySummary](options/input.md#includehierarchysummary)
+{@listOptions options/input.md}
 
 ## Output Options
 
 Options which control TypeDoc's HTML output.
 
--   [outputs](options/output.md#outputs)
--   [out](options/output.md#out)
--   [html](options/output.md#html)
--   [json](options/output.md#json)
--   [pretty](options/output.md#pretty)
--   [emit](options/output.md#emit)
--   [theme](options/output.md#theme)
--   [lightHighlightTheme](options/output.md#lighthighlighttheme)
--   [darkHighlightTheme](options/output.md#darkhighlighttheme)
--   [highlightLanguages](options/output.md#highlightlanguages)
--   [typePrintWidth](options/output.md#typeprintwidth)
--   [customCss](options/output.md#customcss)
--   [customJs](options/output.md#customjs)
--   [customFooterHtml](options/output.md#customfooterhtml)
--   [customFooterHtmlDisableWrapper](options/output.md#customfooterhtmldisablewrapper)
--   [markdownItOptions](options/output.md#markdownitoptions)
--   [markdownItLoader](options/output.md#markdownitloader)
--   [basePath](options/output.md#basepath)
--   [cname](options/output.md#cname)
--   [favicon](options/output.md#favicon)
--   [sourceLinkExternal](options/output.md#sourcelinkexternal)
--   [markdownLinkExternal](options/output.md#markdownlinkexternal)
--   [lang](options/output.md#lang)
--   [locales](options/output.md#locales)
--   [githubPages](options/output.md#githubpages)
--   [cacheBust](options/output.md#cachebust)
--   [hideGenerator](options/output.md#hidegenerator)
--   [searchInComments](options/output.md#searchincomments)
--   [searchInDocuments](options/output.md#searchindocuments)
--   [cleanOutputDir](options/output.md#cleanoutputdir)
--   [titleLink](options/output.md#titlelink)
--   [navigationLinks](options/output.md#navigationlinks)
--   [sidebarLinks](options/output.md#sidebarlinks)
--   [navigation](options/output.md#navigation)
--   [headings](options/output.md#headings)
--   [sluggerConfiguration](options/output.md#sluggerconfiguration)
--   [navigationLeaves](options/output.md#navigationleaves)
--   [visibilityFilters](options/output.md#visibilityfilters)
--   [searchCategoryBoosts](options/output.md#searchcategoryboosts)
--   [searchGroupBoosts](options/output.md#searchgroupboosts)
--   [hostedBaseUrl](options/output.md#hostedbaseurl)
--   [useHostedBaseUrlForAbsoluteLinks](options/output.md#usehostedbaseurlforabsolutelinks)
--   [useFirstParagraphOfCommentAsSummary](options/output.md#usefirstparagraphofcommentassummary)
+{@listOptions options/output.md}
 
 ## Comment Options
 
 Options which control how TypeDoc parses comments.
 
--   [commentStyle](options/comments.md#commentstyle)
--   [useTsLinkResolution](options/comments.md#usetslinkresolution)
--   [preserveLinkText](options/comments.md#preservelinktext)
--   [jsDocCompatibility](options/comments.md#jsdoccompatibility)
--   [suppressCommentWarningsInDeclarationFiles](options/comments.md#suppresscommentwarningsindeclarationfiles)
--   [blockTags](options/comments.md#blocktags)
--   [inlineTags](options/comments.md#inlinetags)
--   [modifierTags](options/comments.md#modifiertags)
--   [cascadedModifierTags](options/comments.md#cascadedmodifiertags)
--   [excludeTags](options/comments.md#excludetags)
--   [notRenderedTags](options/comments.md#notrenderedtags)
--   [externalSymbolLinkMappings](options/comments.md#externalsymbollinkmappings)
+{@listOptions options/comments.md}
 
 ## Organization Options
 
 Controls how TypeDoc organizes content within a converted project.
 
--   [groupReferencesByType](options/organization.md#groupreferencesbytype)
--   [categorizeByGroup](options/organization.md#categorizebygroup)
--   [defaultCategory](options/organization.md#defaultcategory)
--   [categoryOrder](options/organization.md#categoryorder)
--   [groupOrder](options/organization.md#grouporder)
--   [sort](options/organization.md#sort)
--   [sortEntryPoints](options/organization.md#sortentrypoints)
--   [kindSortOrder](options/organization.md#kindsortorder)
+{@listOptions options/organization.md}
 
 ## Validation Options
 
 Configures the validation performed by TypeDoc on a converted project.
 
--   [validation](options/validation.md#validation)
--   [treatWarningsAsErrors](options/validation.md#treatwarningsaserrors)
--   [treatValidationWarningsAsErrors](options/validation.md#treatvalidationwarningsaserrors)
--   [intentionallyNotExported](options/validation.md#intentionallynotexported)
--   [requiredToBeDocumented](options/validation.md#requiredtobedocumented)
+{@listOptions options/validation.md}
 
 ## Other Options
 
--   [watch](options/other.md#watch)
--   [preserveWatchOutput](options/other.md#preservewatchoutput)
--   [help](options/other.md#help)
--   [version](options/other.md#version)
--   [showConfig](options/other.md#showconfig)
--   [logLevel](options/other.md#loglevel)
--   [skipErrorChecking](options/other.md#skiperrorchecking)
+{@listOptions options/other.md}

site/options/input.md

@@ -90,7 +90,7 @@ Expects all entry points to be `.json` files generated with a previous run of Ty
 Options to set be set within each package when entryPointStrategy is set to
 packages. Unlike most options in TypeDoc, paths within this object are
 interpreted relative to the package directory. This option has no effect if
-[entryPointStrategy](#entrypointstrategy) is not set to `packages.
+[entryPointStrategy](#entrypointstrategy) is not set to `packages`.
 
 ## alwaysCreateEntryPointModule