.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/CONTRIBUTING.md

@@ -93,12 +93,7 @@ If you don't already have [Git] installed, install it first. You will need it to
     ```bash
     npm run build
     ```
-1. Set up a baseline for visual theme testing:
-    ```bash
-    npm run test:visual
-    npm run test:visual:accept
-    ```
-1. Open the typedoc folder in your favorite editor. If you don't have one, try [Visual Studio Code][vscode] or [Atom]
+1. Open the typedoc folder in your favorite editor. If you don't have one, try [Visual Studio Code][vscode]
 
 ## Linting, Building, and Testing
 
@@ -119,14 +114,16 @@ To compile the TypeDoc source, run `npm run build`. This will start the TypeScri
 TypeDoc includes an extensive set of tests that describe its output. To validate any changes you have made run `npm test`.
 This will run a subset of TypeDoc's tests intended for quick development checks.
 Tests which take more than half a second are located in `src/test/slow`, and will only be run if you run `npm run test:full`.
-These tests will also run the visual regression tests, failing if there are any changes.
-TypeDoc also contains visual regression tests for comparing changes made to the themes. To test this, run `npm run test:visual`. If there are changes that you expect, run `npm run test:visual:accept` to save the new baseline.
 
 If you have changed the TypeDoc output, it will cause tests to fail. Once you have validated that the introduced changes were intended, run `npm run rebuild_specs` to update the spec files for the new output.
 
 Additional tests are contained within the `converter2` directory that look for specific issues with previous
 builds and may be more appropriate for adding a test for a bugfix.
 
+#### Visual Regression Testing
+
+There is also a script to visually compare the differences between changes. To set this up, build the code, then run `node scripts/visual_regression.js`. This will create a baseline which future runs will be compared against after making changes, compiling, and running the visual regression script again.
+
 ## Pull Requests
 
 Once you have finished working on an issue, you can submit a pull request to have your changes merged into the TypeDoc repository and included in the next release.
@@ -150,4 +147,3 @@ If the TypeDoc repository has changed since you originally forked it, you will n
 [git]: https://git-scm.com
 [node]: https://nodejs.org/en/
 [vscode]: https://code.visualstudio.com/
-[atom]: https://atom.io/

.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

.github/workflows/ci.yml

@@ -57,7 +57,7 @@ jobs:
               with:
                   node-version: 18
             - name: Upgrade npm
-              run: npm i -g npm@latest
+              run: npm i -g npm@10
             - name: Install
               run: npm ci
             - name: Build

CHANGELOG.md

@@ -4,6 +4,79 @@ title: Changelog
 
 ## Unreleased
 
+## v0.27.6 (2024-12-26)
+
+### Features
+
+-   Added `ignoredHighlightLanguages` option to specify languages which will be
+    allowed in code blocks but not highlighted, #2819.
+
+### Bug Fixes
+
+-   `@include` and `@includeCode` now work in the readme file, #2814.
+-   TypeDoc will now avoid making references to references, #2811.
+-   Fixed output specific option specification, #2818.
+-   Improved type reference conversion to avoid including defaulted type arguments, #2820.
+-   Fixed parsing of declaration references which include a module and a local reference, #2810.
+-   Improved link resolution logic to prioritize type alias properties with the
+    same symbol over type literal properties within function parameters.
+
+## 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/src/documents/syntax-highlighting.md

@@ -8,7 +8,8 @@ TypeDoc supports code blocks in Markdown and uses
 
 TypeDoc supports all languages supported by Shiki, but does not load all of
 them by default. The `highlightLanguages` option can be used to customize
-which languages are loaded for highlighting.
+which languages are loaded for highlighting. The `ignoredHighlightLanguages`
+option can be used to specify languages which should not be highlighted.
 
 If no language is specified, the code block is assumed to be TypeScript:
 

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.6",
   "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.
@@ -47,6 +48,11 @@ The deliminator is used to determine how to navigate the project tree.
 | `#` | Indicates that the next component is a "member", including class instance properties, interface members, and enum members. |
 | `~` | Indicates that the next component is an export of a namespace/module. |
 
+> [!warning] The TSDoc specification says that `~` traverses via locals. This is
+> different than TypeDoc's behavior. TypeDoc will treat `~` as a stricter `.`
+> which only supports navigating to a namespace/module export. It should
+> generally be avoided in favor of `.` for improved compatibility with VSCode.
+
 ```ts
 // module.ts
 /**

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