diff --git a/.config/.prettierignore b/.config/.prettierignore deleted file mode 100644 index 9245daa3e..000000000 --- a/.config/.prettierignore +++ /dev/null @@ -1,17 +0,0 @@ -../.nyc_output -../coverage -../dist -../docs -**/package-lock.json -../src/test/**/specs*.json -../src/test/packages/**/*.js -../src/test/renderer/specs -../src/test/renderer/testProject -../src/test/utils/options/readers/data/invalid2.json -../static/main.js -../example/docs/ -**/tmp -**/.vs - -# Remove once Prettier has support -../src/test/converter2/behavior/resolutionMode.ts diff --git a/.config/.prettierrc.json b/.config/.prettierrc.json deleted file mode 100644 index ff1608b53..000000000 --- a/.config/.prettierrc.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "overrides": [ - { - "files": "*.tsx", - "options": { - "printWidth": 120 - } - } - ] -} diff --git a/.config/mocha.fast.json b/.config/mocha.fast.json index bc6b6d20f..99beb0af4 100644 --- a/.config/mocha.fast.json +++ b/.config/mocha.fast.json @@ -1,9 +1,9 @@ { "$schema": "https://json.schemastore.org/mocharc.json", "exclude": ["src/test/packages/**", "src/test/slow/**"], - "extension": ["ts", "tsx"], - "require": ["ts-node/register"], + "extension": ["ts", "cts", "mts", "tsx"], "spec": ["src/test/**/*.test.ts", "src/test/**/*.test.tsx"], "timeout": 5000, - "watch-files": ["src/**/*.ts", "src/**/*.tsx"] + "watch-files": ["src/**/*.ts", "src/**/*.tsx"], + "node-option": ["import=tsx", "conditions=typedoc-ts"] } diff --git a/.config/mocha.full.json b/.config/mocha.full.json index 641407a28..fb770ed5e 100644 --- a/.config/mocha.full.json +++ b/.config/mocha.full.json @@ -3,5 +3,5 @@ "timeout": 0, "spec": ["src/test/**/*.test.ts", "src/test/**/*.test.tsx"], "exclude": ["src/test/packages/**"], - "require": ["ts-node/register"] + "node-option": ["import=tsx", "conditions=typedoc-ts"] } diff --git a/.config/mocha.test-explorer.json b/.config/mocha.test-explorer.json index 980a101b0..0e2ffebdc 100644 --- a/.config/mocha.test-explorer.json +++ b/.config/mocha.test-explorer.json @@ -1,9 +1,9 @@ { "$schema": "https://json.schemastore.org/mocharc.json", "extension": ["ts"], - "ignore": ["src/test/slow/**", "src/test/packages/**"], + "ignore": [], "package": "./package.json", - "require": "ts-node/register", + "node-option": ["import=tsx", "conditions=typedoc-ts"], "slow": 500, "spec": ["src/**/*.test.ts", "src/**/*.test.tsx"], "timeout": 0, diff --git a/.config/typedoc.json b/.config/typedoc.json index d0186774a..3f6a7766f 100644 --- a/.config/typedoc.json +++ b/.config/typedoc.json @@ -1,26 +1,50 @@ { "$schema": "https://typedoc.org/schema.json", "intentionallyNotExported": [ - "ComponentClass", - "AbstractComponent", - "ConverterComponent", - "RendererComponent", "SORT_STRATEGIES", "_ModelToObject", "EventHooksMomento", "MarkedPlugin", "MeaningKeywords" ], - "sort": ["kind", "instance-first", "required-first", "alphabetical"], + "sort": [ + "kind", + "instance-first", + "required-first", + "alphabetical-ignoring-documents" + ], + "name": "TypeDoc API", + + // Don't document the debug entry point "entryPoints": ["../src/index.ts"], + "outputs": [ + { + "name": "html", + "path": "../docs" + }, + { + "name": "json", + "path": "../docs/docs.json" + } + ], + "excludeExternals": true, + "externalPattern": ["**/node_modules/**", "../src/lib/types/**"], "excludeInternal": false, "excludePrivate": true, - "excludeReferences": true, + // "excludeReferences": true, + "groupReferencesByType": true, "jsDocCompatibility": false, "treatWarningsAsErrors": false, "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": "https://github.com/TypeStrong/typedoc" + }, "validation": { "notExported": true, "invalidLink": true, @@ -33,16 +57,27 @@ "external": false, "@internal": false }, + "searchInComments": true, + "searchInDocuments": true, "searchGroupBoosts": { - "Classes": 2.0, + "Classes": 5.0, "Interfaces": 2.0, "Enumerations": 2.0, "Type Aliases": 2.0 }, "navigation": { "includeCategories": true, - "includeGroups": false + "includeGroups": false, + "excludeReferences": true }, "includeVersion": true, - "logLevel": "Verbose" + "logLevel": "Verbose", + "externalSymbolLinkMappings": { + "@types/markdown-it": { + "MarkdownIt": "https://markdown-it.github.io/markdown-it/#MarkdownIt" + } + }, + + // Saves a couple seconds when generating docs + "skipErrorChecking": true } diff --git a/.editorconfig b/.editorconfig index 220e0298e..a8cde4620 100644 --- a/.editorconfig +++ b/.editorconfig @@ -12,3 +12,6 @@ trim_trailing_whitespace = true [package.json] indent_size = 2 + +[src/test/converter2/issues/gh2631/crlf.md] +end_of_line = crlf diff --git a/.eslintrc b/.eslintrc deleted file mode 100644 index b923486a1..000000000 --- a/.eslintrc +++ /dev/null @@ -1,88 +0,0 @@ -{ - "root": true, - "parser": "@typescript-eslint/parser", - "parserOptions": { - "project": "tsconfig.json" - }, - "env": { - "node": true, - "es6": true - }, - "plugins": ["@typescript-eslint"], - "extends": [ - "eslint:recommended", - "plugin:@typescript-eslint/eslint-recommended", - "plugin:@typescript-eslint/recommended" - ], - "ignorePatterns": [ - "src/test/renderer/specs", - "dist", - "docs", - "tmp", - "coverage", - "static/main.js", - "src/lib/output/themes/default/assets", - "node_modules", - // Would be nice to lint these, but they shouldn't be included in the project, - // so we need a second eslint config file. - "example", - "src/test/converter", - "src/test/converter2", - "src/test/module", - "src/test/packages", - "src/test/renderer", - "src/test/slow/entry-points", - "scripts", - "bin" - ], - "rules": { - "@typescript-eslint/no-floating-promises": "error", - "@typescript-eslint/await-thenable": "error", - - // This one is just annoying since it complains at incomplete code - "no-empty": "off", - - // This rule is factually incorrect. Interfaces which extend some type alias can be used to introduce - // new type names. This is useful particularly when dealing with mixins. - "@typescript-eslint/no-empty-interface": "off", - - // We still use `any` fairly frequently... - "@typescript-eslint/ban-types": "off", - "@typescript-eslint/no-explicit-any": "off", - - // Really annoying, doesn't provide any value. - "@typescript-eslint/no-empty-function": "off", - - // Declaration merging with a namespace is a necessary tool when working with enums. - "@typescript-eslint/no-namespace": "off", - - // Reported by TypeScript - "@typescript-eslint/no-unused-vars": "off", - - "no-console": "warn", - - // Feel free to turn one of these back on and submit a PR! - "@typescript-eslint/no-non-null-assertion": "off", - "@typescript-eslint/explicit-module-boundary-types": "off", - - "no-restricted-syntax": [ - "warn", - { - "selector": "ImportDeclaration[source.value=/.*perf$/]", - "message": "Benchmark calls must be removed before committing." - }, - { - "selector": "MemberExpression[object.name=type][property.name=symbol]", - "message": "Use type.getSymbol() instead, Type.symbol is not properly typed." - } - ] - }, - "overrides": [ - { - "files": ["src/test/**"], - "env": { - "mocha": true - } - } - ] -} diff --git a/.gitattributes b/.gitattributes index e77811b3a..06874f468 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,5 +1,6 @@ # Disable core.autocrlf's line ending conversion behavior to prevent test failures on Windows * text=auto eol=lf +src/test/converter2/issues/gh2631/crlf.md text=auto eol=crlf *.png binary *.psd binary diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md index 875b86d8a..cd70512f0 100644 --- a/.github/CODE_OF_CONDUCT.md +++ b/.github/CODE_OF_CONDUCT.md @@ -17,24 +17,24 @@ diverse, inclusive, and healthy community. Examples of behavior that contributes to a positive environment for our community include: -- Demonstrating empathy and kindness toward other people -- Being respectful of differing opinions, viewpoints, and experiences -- Giving and gracefully accepting constructive feedback -- Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -- Focusing on what is best not just for us as individuals, but for the - overall community +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +- Focusing on what is best not just for us as individuals, but for the + overall community Examples of unacceptable behavior include: -- The use of sexualized language or imagery, and sexual attention or - advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or email - address, without their explicit permission -- Other conduct which could reasonably be considered inappropriate in a - professional setting +- The use of sexualized language or imagery, and sexual attention or + advances of any kind +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or email + address, without their explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting ## Enforcement Responsibilities diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 42b0a110b..2eab4ad17 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -6,21 +6,21 @@ This document includes a set of guidelines for contributing to TypeDoc. These ar ## Table of Contents -- [Contributing to TypeDoc](#contributing-to-typedoc) - - [Table of Contents](#table-of-contents) - - [How Can I Contribute?](#how-can-i-contribute) - - [Bug Reports](#bug-reports) - - [Suggestions](#suggestions) - - [Documentation](#documentation) - - [Code](#code) - - [Setup - Git, GitHub, and Node](#setup---git-github-and-node) - - [Installation](#installation) - - [Linting, Building, and Testing](#linting-building-and-testing) - - [Linting](#linting) - - [Building](#building) - - [Testing](#testing) - - [Pull Requests](#pull-requests) - - [Updating Your Branch](#updating-your-branch) +- [Contributing to TypeDoc](#contributing-to-typedoc) + - [Table of Contents](#table-of-contents) + - [How Can I Contribute?](#how-can-i-contribute) + - [Bug Reports](#bug-reports) + - [Suggestions](#suggestions) + - [Documentation](#documentation) + - [Code](#code) + - [Setup - Git, GitHub, and Node](#setup---git-github-and-node) + - [Installation](#installation) + - [Linting, Building, and Testing](#linting-building-and-testing) + - [Linting](#linting) + - [Building](#building) + - [Testing](#testing) + - [Pull Requests](#pull-requests) + - [Updating Your Branch](#updating-your-branch) ## How Can I Contribute? @@ -32,9 +32,9 @@ Before creating a bug report please check [this list][bugs] to see if it has alr When creating a bug report, explain the problem and include as much additional information as necessary to help maintainers to reproduce it. Ideally, provide an example project which highlights the problem. -- **Use a clear and descriptive title** for the issue to identify the problem -- **Describe your project setup**. The easier it is for maintainers to reproduce your problem, the more likely it is to be quickly fixed. -- **Explain what you expected to see instead and why** +- **Use a clear and descriptive title** for the issue to identify the problem +- **Describe your project setup**. The easier it is for maintainers to reproduce your problem, the more likely it is to be quickly fixed. +- **Explain what you expected to see instead and why** ### Suggestions @@ -44,18 +44,18 @@ Before creating a feature request, please check [this list][suggestions] to see When creating an enhancement request, explain your use case and ultimate goal. This will make it possible for contributors to suggest existing alternatives which may already meet your requirements. -- **Use a clear and descriptive title** for the issue to identify the suggestion. -- **Provide an example where this enhancement would improve TypeDoc** -- **If possible, list another documentation generator where this feature exists** +- **Use a clear and descriptive title** for the issue to identify the suggestion. +- **Provide an example where this enhancement would improve TypeDoc** +- **If possible, list another documentation generator where this feature exists** ### Documentation TypeDoc is documented in 4 primary areas. -- This repo's [README.md](https://github.com/TypeStrong/typedoc/blob/master/README.md) -- The website guides hosted at [TypeStrong/typedoc-site](https://github.com/TypeStrong/typedoc-site/) -- Doc comments of source files which are rendered in the [api docs](https://typedoc.org/api/) -- The [option descriptions](https://github.com/TypeStrong/typedoc/blob/ce0654295698e2bb2badf5f93d388bd977da3c46/src/lib/application.ts#L66) used by the `--help` command +- This repo's [README.md](https://github.com/TypeStrong/typedoc/blob/master/README.md) +- The website guides hosted at [TypeStrong/typedoc-site](https://github.com/TypeStrong/typedoc-site/) +- Doc comments of source files which are rendered in the [api docs](https://typedoc.org/api/) +- The [option descriptions](https://github.com/TypeStrong/typedoc/blob/ce0654295698e2bb2badf5f93d388bd977da3c46/src/lib/application.ts#L66) used by the `--help` command If you would like to improve the documentation in any of these areas, please open an issue if there isn't one already to discuss what you would like to improve. Then submit a [Pull Request](#pull-requests) to this repo, (or to [TypeStrong/typedoc-site](https://github.com/TypeStrong/typedoc-site/) in the case of guides). @@ -70,7 +70,7 @@ If you have started work on an issue and get stuck or want a second opinion on y ## Setup - Git, GitHub, and Node -If you don't already have [Git] installed, install it first. You will need it to contribute to TypeDoc. You will also need to install [Node]. TypeDoc requires at least npm 4, so if you are running Node 7.3.0 or older you will need to upgrade npm using `npm install --global npm@^4`. +If you don't already have [Git] installed, install it first. You will need it to contribute to TypeDoc. You will also need to install [Node] and pnpm. #### Installation @@ -78,27 +78,22 @@ If you don't already have [Git] installed, install it first. You will need it to 1. Open a terminal, or "Git Bash" on Windows. 1. Use `cd` to move to the directory that you want to work in. 1. Clone your repository, replace USER with your GitHub username: - ```bash - git clone https://github.com/USER/typedoc - ``` + ```bash + git clone https://github.com/USER/typedoc + ``` 1. Add the TypeDoc repo as a remote repository - ```bash - git remote add typedoc https://github.com/TypeStrong/typedoc - ``` + ```bash + git remote add typedoc https://github.com/TypeStrong/typedoc + ``` 1. Install dependencies: - ```bash - npm install - ``` + ```bash + pnpm install + ``` 1. Build: - ```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] + ```bash + pnpm build + ``` +1. Open the typedoc folder in your favorite editor. If you don't have one, try [Visual Studio Code][vscode] ## Linting, Building, and Testing @@ -106,32 +101,34 @@ Once you have cloned TypeDoc, you can lint, build, and test the code from your t #### Linting -To lint the TypeDoc code, run `npm run lint`. This will start eslint and check all files for stylistic problems. You can also install an eslint plugin for your editor to show most style problems as you type. +To lint the TypeDoc code, run `pnpm run lint`. This will start eslint and check all files for stylistic problems. You can also install an eslint plugin for your editor to show most style problems as you type. -You can automatically fix some style problems by running `npm run lint -- --write`. +You can automatically fix some style problems by running `pnpx dprint fmt`. #### Building -To compile the TypeDoc source, run `npm run build`. This will start the TypeScript compiler and output the compiled JavaScript to the `dist` folder. +To compile the TypeDoc source, run `pnpm build`. This will start the TypeScript compiler and output the compiled JavaScript to the `dist` folder. #### Testing -TypeDoc includes an extensive set of tests that describe its output. To validate any changes you have made run `npm test`. +TypeDoc includes an extensive set of tests that describe its output. To validate any changes you have made run `pnpm 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. +Tests which take more than half a second are located in `src/test/slow`, and will only be run if you run `pnpm run test:full`. -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. +If you have changed the TypeDoc output, it will cause tests to fail. Once you have validated that the introduced changes were intended, run `pnpm 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. -Before submitting a pull request, make sure that there are no linting problems (`npm run lint`), all tests pass (`npm test`), and your branch is up to date. Its also a good idea to join the TypeScript [discord] and visit the `#typedoc` channel to discuss how best to implement changes. +Before submitting a pull request, make sure that there are no linting problems (`pnpm run lint`), all tests pass (`pnpm test`), and your branch is up to date. Its also a good idea to join the TypeScript [discord] and visit the `#typedoc` channel to discuss how best to implement changes. If your change is user facing, consider updating `CHANGELOG.md` to describe the change you have made. If you don't, the maintainer who merges your pull request will do it for you. @@ -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/ diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 000000000..d8e186beb --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1 @@ +github: gerrit0 diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index aa503e5d8..d6c7ab481 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,7 +1,7 @@ --- name: Bug Report about: Report a bug in TypeDoc -labels: bug +type: Bug --- ## Search terms @@ -22,8 +22,11 @@ labels: bug Note: Turn off skipErrorChecks before reporting a crash. Bug reports for crashes with that option on are out of scope. -If possible, please create a *minimal* repo reproducing your problem and link it. -You can easily do this by submitting a pull request to https://github.com/TypeStrong/typedoc-repros +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 which changes the files necessary to reproduce your bug. If this is not possible, include at least: @@ -35,7 +38,7 @@ If this is not possible, include at least: ## Environment -- Typedoc version: -- TypeScript version: -- Node.js version: -- OS: +- Typedoc version: +- TypeScript version: +- Node.js version: +- OS: diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..3d8c684fb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,4 @@ +contact_links: + - name: Discussions + url: https://github.com/TypeStrong/typedoc/discussions + about: Please ask questions here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 9ef03b93d..962d37220 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,7 +1,7 @@ --- name: Feature Request about: Suggest improvements or new features -labels: enhancement +type: Feature --- ## Search Terms diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md deleted file mode 100644 index 6aff1333c..000000000 --- a/.github/ISSUE_TEMPLATE/question.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: Question -about: Ask a question about TypeDoc -labels: question ---- - -## Search terms - - - -## Question diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 666567de6..3d252b19e 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -6,11 +6,7 @@ The TypeDoc team supports the latest minor version. For one minor version prior pull requests providing patches to fix security vulnerabilities will be accepted. Support for the previous minor version relies completely on community pull requests. -| Version | Status | -| ------- | ------------------ | -| 0.25.x | :white_check_mark: | -| 0.24.x | :warning: | -| < 0.24 | :x: | +See https://typedoc.org/documents/Overview.html for the current status. ## Patching LTS Versions diff --git a/.github/workflows/build-site.yml b/.github/workflows/build-site.yml new file mode 100644 index 000000000..4e70d05f8 --- /dev/null +++ b/.github/workflows/build-site.yml @@ -0,0 +1,48 @@ +name: Build Site +on: + push: + pull_request: + schedule: + - cron: "0 5 * * *" +jobs: + build: + runs-on: ubuntu-latest + name: Build Site + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: 20 + - name: Set up pnpm + run: npm i -g pnpm@10 + - name: Install + run: pnpm install + - name: Build + run: pnpm run build + - name: Build Site + run: ./scripts/build_site.sh + - name: Upload static files as artifact + id: deployment + uses: actions/upload-pages-artifact@v3 + with: + path: docs-site/ + deploy: + needs: build + if: github.ref == 'refs/heads/master' + name: Deploy + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f05ed0295..ccfbb7068 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,50 +5,72 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - node: ["18", "20", "21"] + node: ["18", "20", "22.4.1", "23"] name: Node ${{ matrix.node }} steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Set up Node - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: ${{ matrix.node }} + - name: Set up pnpm + run: npm i -g pnpm@10 - name: Install - run: npm ci + run: pnpm install - name: Build - run: npm run build + run: pnpm run build - name: Test - run: npm run test:full - env: - # For pull requests, this gets handled by the visual-regression workflow. - # For other test runs, skip so we don't have to go build the regression screenshots. - SKIP_VISUAL_TEST: true + run: | + if node -e "process.exit(Number(+process.versions.node.slice(0, 2) < 23))"; then + export NODE_OPTIONS="--no-experimental-strip-types" + fi + pnpm run test:full - name: Lint - run: npm run lint -- --max-warnings 0 + run: pnpm run lint - name: Circular dependency check - uses: gerrit0/circular-dependency-check@v2 + uses: gerrit0/circular-dependency-check@v2.0.2 with: entry: dist/index.js + build-release: + runs-on: ubuntu-latest + name: Node 22 Release + steps: + - name: Checkout repository + uses: actions/checkout@v4 + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: 22.4.1 + - name: Set up pnpm + run: npm i -g pnpm@10 + - name: Install + run: pnpm install + - name: Build + run: | + node scripts/set_strict.js false + pnpm run build + - name: Test + run: pnpm run test:full + - name: Lint + run: pnpm run lint build-windows: runs-on: windows-latest name: Node 18 Windows steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Set up Node - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: 18 - - name: Upgrade npm - run: npm i -g npm@latest + - name: Set up pnpm + run: npm i -g pnpm@10 - name: Install - run: npm ci + run: pnpm install - name: Build - run: npm run build + run: pnpm run build - name: Test - run: npm run test:full - env: - SKIP_VISUAL_TEST: true + run: pnpm run test:full - name: Lint - run: npm run lint -- --max-warnings 0 + run: pnpm run lint diff --git a/.github/workflows/publish-beta.yml b/.github/workflows/publish-beta.yml index 4a004bf39..ae77c4c9f 100644 --- a/.github/workflows/publish-beta.yml +++ b/.github/workflows/publish-beta.yml @@ -9,27 +9,29 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - id: check - uses: EndBug/version-check@v1 + uses: EndBug/version-check@v2.1.4 with: diff-search: true - name: Set up Node if: steps.check.outputs.changed == 'true' && contains(steps.check.outputs.version, 'beta') - uses: actions/setup-node@v1 + uses: actions/setup-node@v4 with: - node-version: "20" - - name: Upgrade npm + node-version: "18" + - name: Setup pnpm if: steps.check.outputs.changed == 'true' && contains(steps.check.outputs.version, 'beta') - run: npm i -g npm@latest + run: npm i -g pnpm@10 - name: Install if: steps.check.outputs.changed == 'true' && contains(steps.check.outputs.version, 'beta') - run: npm ci - - name: Setup publish token + run: pnpm install + - name: Test if: steps.check.outputs.changed == 'true' && contains(steps.check.outputs.version, 'beta') - run: echo "//registry.npmjs.org/:_authToken=${NPM_AUTH_TOKEN}" > .npmrc - env: - NPM_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }} + run: pnpm test - name: Publish if: steps.check.outputs.changed == 'true' && contains(steps.check.outputs.version, 'beta') - run: npm publish --tag beta + # We need --no-git-checks because we swap a boolean to allow more lax types + # in the published package. + run: pnpm publish --tag beta --no-git-checks + env: + npm_config_//registry.npmjs.org/:_authToken: ${{ secrets.NPM_AUTH_TOKEN }} diff --git a/.github/workflows/publish-lts.yml b/.github/workflows/publish-lts.yml index ccc9e894f..30c84047a 100644 --- a/.github/workflows/publish-lts.yml +++ b/.github/workflows/publish-lts.yml @@ -9,27 +9,29 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - id: check - uses: EndBug/version-check@v1 + uses: EndBug/version-check@v2.1.4 with: diff-search: true - name: Set up Node if: steps.check.outputs.changed == 'true' - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: - node-version: "20" - - name: Upgrade npm + node-version: "18" + - name: Set up pnpm if: steps.check.outputs.changed == 'true' - run: npm i -g npm@latest + run: npm i -g pnpm@10 - name: Install if: steps.check.outputs.changed == 'true' - run: npm ci - - name: Setup publish token + run: pnpm install + - name: Test if: steps.check.outputs.changed == 'true' - run: echo "//registry.npmjs.org/:_authToken=${NPM_AUTH_TOKEN}" > .npmrc - env: - NPM_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }} + run: pnpm test - name: Publish if: steps.check.outputs.changed == 'true' - run: npm publish --tag lts + # We need --no-git-checks because we swap a boolean to allow more lax types + # in the published package. + run: pnpm publish --tag lts --no-git-checks + env: + npm_config_//registry.npmjs.org/:_authToken: ${{ secrets.NPM_AUTH_TOKEN }} diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 627066b5a..55465d688 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -9,29 +9,34 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: fetch-depth: 0 - id: check - uses: EndBug/version-check@v2.1.0 + uses: EndBug/version-check@v2.1.4 with: diff-search: true - name: Set up Node if: steps.check.outputs.changed == 'true' - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: - node-version: "20" + node-version: "18" + - name: Set up pnpm + if: steps.check.outputs.changed == 'true' + run: npm i -g pnpm@10 - name: Install if: steps.check.outputs.changed == 'true' - run: npm ci - - name: Setup publish token + run: pnpm install + - name: Test if: steps.check.outputs.changed == 'true' - run: echo "//registry.npmjs.org/:_authToken=${NPM_AUTH_TOKEN}" > .npmrc - env: - NPM_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }} + run: pnpm test - name: Publish if: steps.check.outputs.changed == 'true' - run: npm publish + # We need --no-git-checks because we swap a boolean to allow more lax types + # in the published package. + run: pnpm publish --no-git-checks + env: + npm_config_//registry.npmjs.org/:_authToken: ${{ secrets.NPM_AUTH_TOKEN }} - name: Generate Release if: steps.check.outputs.changed == 'true' run: | diff --git a/.github/workflows/visual-regression.yml b/.github/workflows/visual-regression.yml deleted file mode 100644 index 734faeee5..000000000 --- a/.github/workflows/visual-regression.yml +++ /dev/null @@ -1,36 +0,0 @@ -name: Visual Regression Testing -on: [workflow_dispatch] -jobs: - build: - runs-on: ubuntu-latest - steps: - - name: Checkout repository - uses: actions/checkout@v3 - - name: Set up Node - uses: actions/setup-node@v3 - with: - node-version: 20 - - name: Upgrade npm - run: npm i -g npm@latest - - name: Get baseline screenshots - run: | - git fetch - git checkout origin/$GITHUB_BASE_REF - npm ci - npm run build - node dist/test/capture-screenshots.js - npm run test:visual:accept - - - name: Get current screenshots - run: | - git checkout $GITHUB_SHA - npm ci - npm run build - node dist/test/capture-screenshots.js - - name: Test - run: npx reg-suit run -c .config/regconfig.json --test - - name: Upload Results - uses: actions/upload-artifact@v3 - with: - name: visual-regression - path: dist/tmp/.reg diff --git a/.gitignore b/.gitignore index f8b415d1d..0ed4251ff 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,7 @@ yarn-error.log /coverage/ /dist/ /docs +/docs-site /docs2 /td*.json diff --git a/.npmrc b/.npmrc index 0683edb0a..38a20c41b 100644 --- a/.npmrc +++ b/.npmrc @@ -1,5 +1,8 @@ # If these were only for production, we'd care, but there's no -# way to ask npm to only report production audit findings when doing +# way to ask pnpm to only report production audit findings when doing # an install, so just turn it off. We can still check for findings -# with npm audit --production. +# with pnpm audit --production. audit = false + +# While we're on the TS beta, need this flag. +legacy-peer-deps = true diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 0a5ccb171..55157cd42 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,6 +1,7 @@ { "recommendations": [ "hbenl.vscode-test-explorer", - "hbenl.vscode-mocha-test-adapter" + "hbenl.vscode-mocha-test-adapter", + "dprint.dprint" ] } diff --git a/.vscode/launch.json b/.vscode/launch.json index 1e9ea1e36..10b8b3635 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -6,8 +6,7 @@ "configurations": [ { "args": [ - "-r", - "ts-node/register", + "--import=tsx", "--timeout", "0", "--config", diff --git a/.vscode/settings.json b/.vscode/settings.json index 6fd759eb7..f2c994728 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -8,48 +8,69 @@ // Automatically run the formatter when certain files are saved. "[javascript]": { - "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.defaultFormatter": "dprint.dprint", "editor.formatOnSave": true, "editor.tabSize": 4 }, "[typescript]": { - "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.defaultFormatter": "dprint.dprint", "editor.formatOnSave": true, "editor.tabSize": 4 }, "[typescriptreact]": { - "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.defaultFormatter": "dprint.dprint", "editor.formatOnSave": true, "editor.tabSize": 4 }, "[json]": { - "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.defaultFormatter": "dprint.dprint", "editor.formatOnSave": true, "editor.tabSize": 4 }, "[jsonc]": { - "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.defaultFormatter": "dprint.dprint", + "editor.formatOnSave": true, + "editor.tabSize": 4 + }, + "[css]": { + "editor.defaultFormatter": "dprint.dprint", "editor.formatOnSave": true, "editor.tabSize": 4 }, - "prettier.enable": true, - "prettier.configPath": ".config/.prettierrc.json", - "prettier.ignorePath": ".config/.prettierignore", + "mochaExplorer.nodeArgv": ["--import=tsx", "--conditions=typedoc-ts"], "eslint.workingDirectories": [".", "./example"], "mochaExplorer.configFile": ".config/mocha.test-explorer.json", + "cSpell.ignoreRegExpList": [ + // Ignore usernames in the Thanks sections of the changelog + "/^- +@[A-Z0-9_-]+/igm", + // Ignore combined hashes in JSON output for rendering testing + "/#[a-z0-9_]+\"/" + ], "cSpell.words": [ + "callouts", "cname", + "Combinatorially", + "deconfliction", "deserializers", + "dprint", + "frontmatter", "githubprivate", + "hideconstructor", "linkcode", + "linkify", "linkplain", + "momento", + "Msys", "nodoc", "shiki", "tsbuildinfo", "tsdoc", + "typedoc", + "typeof", "typestrong", - "uncategorized" + "uncategorized", + "WCAG" ] } diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 030f085c6..ef008eaba 100644 --- a/.vscode/tasks.json +++ b/.vscode/tasks.json @@ -34,7 +34,7 @@ { "label": "dev-build-tsc", "type": "shell", - "command": "npm run build:tsc -- --watch", + "command": "pnpm build:tsc --watch", "problemMatcher": ["$tsc-watch"], "detail": "Build TypeDoc w/ tsc in watch mode", "isBackground": true, @@ -49,7 +49,7 @@ { "label": "dev-build-themes", "type": "shell", - "command": "npm run build:themes -- --watch", + "command": "pnpm build:themes --watch", "problemMatcher": ["$esbuild-watch"], "detail": "Build TypeDoc themes in watch mode", "isBackground": true, diff --git a/CHANGELOG.md b/CHANGELOG.md index baf867a4f..a5d49fd7a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,2072 +1,2738 @@ -# Unreleased +--- +title: Changelog +--- + +## Unreleased + +## v0.28.2 (2025-04-07) + +### Features + +- `@group none` and `@category none` will now render their children without a section + heading in the default theme, #2922. +- Added `@disableGroups` tag to completely disable the grouping mechanism for a + given reflection, #2922. + +### Bug Fixes + +- Variables using `@class` now correctly handle `@category`, #2914. +- Variables using `@class` now include constructor parameters, #2914. +- Variables using `@class` with a generic first constructor function now adopt + that function's type parameters as the class type parameters, #2914. +- When printing entry point globs which fail to match any paths, TypeDoc will no longer normalize the glob, #2918. +- Inlining types can now handle more type variants, #2920. +- Fixed behavior of `externalSymbolLinkMappings` option when URL is set to `#`, #2921. +- Fixed broken links within module pages when structure-dir router was used, #2928. +- Type parameters on JS classes defined with `@typedef` now correctly handle the constraint, #2929. +- API: `toString` on types containing index signatures now behave correctly, #2917. +- Added `@inlineType` to the list of tags excluded by default. + +## v0.28.1 (2025-03-20) + +### Features + +- The `TypeDocOptions` interface now marks options as optional so it no longer has to be wrapped in `Partial` + for use in config files, #2901. +- API: Expose control methods for deferred conversion for plugin use (typedoc-plugin-missing-exports) +- API: Expose method to disable TypeDoc usage of `localStorage` without clearing it, #2908. + +### Bug Fixes + +- `--watch` can now infer entry points from `package.json` as supported in non-watch mode, #2899. +- `@include` with regions now works on files with CRLF line endings, #2902. +- Generated page names now correctly handles UTF-8 characters requiring more than 16 bits #2905. +- Fixed a crash when converting `module.exports = []`, #2909. +- Fixed URL generation which introduced a superfluous `./` in relative links, #2910. + +### Thanks! + +- @jsmith2-coveo +- @romainmnr + +## v0.28.0 (2025-03-15) + +### Breaking Changes + +- TypeDoc now expects all input globs paths to be specified with `/` path separators, #2825. +- TypeDoc's `--entryPointStrategy merge` mode now requires JSON from at least version 0.28.0. +- Removed `jp` translations from `lang`, to migrate switch to `ja`. +- File name references in `intentionallyNotExported` now use a package name/package relative path instead of an absolute path for matching. +- The `source-order` sort ordering now considers package names / package relative paths instead of using the absolute paths to a file. +- TypeDoc will only check for a project README file next to the discovered `package.json` file if `--readme` is not set + this change improves handling of monorepo setups where some packages have readme files and others do not, #2875. +- Function-like variable exports will now only be automatically converted as function types if + they are initialized with a function expression. TypeDoc can be instructed to convert them as functions + with the `@function` tag, #2881. +- Object literal type alias types will now be converted in a way which causes them to be rendered more similarly + to how interfaces are rendered, #2817. + +### API Breaking Changes + +- `ProjectReflection.getReflectionFromSymbol` and `ProjectReflection.getSymbolFromReflection` have been moved to `Context` +- `Path` and `PathArray` parameter types now always contain normalized paths. +- Introduced a `Router` which is used for URL creation. `Reflection.url`, + `Reflection.anchor`, and `Reflection.hasOwnDocument` have been removed. +- `Deserializer.reviveProject(s)` no longer accepts an option to add project documents. +- `Deserializer.reviveProjects` now requires an `alwaysCreateEntryPointModule` option. +- `Comment.serializeDisplayParts` no longer requires a serializer argument. +- `ReflectionSymbolId.fileName` is now optional, TypeDoc now stores a combination of a package name and package relative path instead. + The `fileName` property will be present when initially created, but is not serialized. +- Removed `DeclarationReflection.relevanceBoost` attribute which was added for plugins, but never used. +- `i18n` proxy is no longer passed to many functions, instead, reference `i18n` exported from the module directly. +- `ReflectionKind.singularString` and `ReflectionKind.pluralString` now returns translated strings. + The methods on `Internationalization` to do this previously have been removed. +- The HTML output structure for the search box has changed to support the new modal. +- `DefaultThemeRenderContext`'s `typeDeclaration` and `typeDetailsIfUseful` + methods now require both a reflection and a type in order to support + `@expandType` + +### Features + +- Add support for TypeScript 5.8.x +- The search modal in the HTML output has been rewritten to provide better mobile support +- Added a `--router` option which can be used to modify TypeDoc's output folder + structure. This can be extended with plugins, #2111. +- Introduced the `@primaryExport` modifier tag to provide more fine grained + control over export conversion order, #2856 +- Introduced `packagesRequiringDocumentation` option for `validation.notDocumented`, TypeDoc will expect comments to be present for symbols in the specified packages. +- TypeDoc now exports a `typedoc/browser` entrypoint for parsing and using serialized JSON files, #2528. +- Type `packageOptions` as `Partial`, #2878. +- TypeDoc will now warn if an option which should only be set at the root level is set in `packageOptions`, #2878. +- Introduced `@function` tag to force TypeDoc to convert variable declarations with a type annotation as functions, #2881. +- Exposed a `TypeDoc` global object in the HTML theme which can be used to prevent TypeDoc from using `localStorage`, #2872. +- Introduced `@preventInline` and `@inlineType` tags for further control extending the `@inline` tag, #2862. +- Introduced `@preventExpand` and `@expandType` tags for further control extending the `@expand` tag, #2862. +- API: Introduced `DefaultThemeRenderContext.reflectionIcon` for more granular control over displayed reflection icons. + +### Bug Fixes + +- TypeDoc will now only create references for symbols re-exported from modules. +- Variable-functions will now prefer placing the comment on the signature if there is only one signature present, #2824. +- User filter settings will no longer sometimes cause the search to have fewer visible results than expected. +- Fixed handling of expando functions which were also merged with a namespace, #2876. +- Fixed rendering of function types within arrays and union types, #2892. +- Fixed an issue where if the theme JS didn't load, the page wouldn't be shown, #2894. + +### Thanks! + +- @crimx +- @jsmith2-coveo +- @phoneticallySAARTHaK +- @XeroAlpha + +## v0.27.9 (2025-02-25) + +This will be the last v0.27.x release, see #2868 for discussion on the 0.28 beta. + +### Features + +- Added support for TypeScript 5.8 + +## v0.27.8 (2025-02-21) + +### Features + +- The `visibilityFilter` option now supports individual signatures, #2846. +- The `favicon` option may now be given a link starting with `https?://` instead of a path, #2851. +- TypeDoc now supports specifying `#` as the link in `externalSymbolLinkMappings` to indicate the type should not be linked to, #2853. + +### Bug Fixes + +- Fixed an issue where unrecognized languages would incorrectly be listed in the list of languages with translations, #2852. +- Unresolved external type references will no longer incorrectly linked to `undefined`, #2854. + +### Thanks! + +- @pjeby +- @XeroAlpha + +## v0.27.7 (2025-02-09) + +### Features + +- `@includeCode` and `@inline` can now inject parts of files using region + names or line numbers, #2816. +- Introduced `ja` translation options, deprecated `jp` in favor of `ja`, #2843. +- Improved TypeDoc's `--watch` option to support watching files not caught by + TypeScript's watch mode, #2675. +- The `@inline` tag now works in more places for generic types. +- Visibility filters now consider individual signatures, #2846. + +### Bug Fixes + +- Fixed an issue where TypeDoc would incorrectly ignore type arguments in references, #2823. +- Improved narrator support for labeling icons, #2832. +- Fixed an issue with `@class` incorrectly handling mapped types, #2842. +- TypeDoc will now consider symbols to be external only if all of their declarations are external + so that declaration merged members with global symbols can be documented, #2844. +- Fixed an issue where TypeDoc would constantly rebuild, #2844. +- Fixed an issue where the dropdown arrow in the index group would not respect the state of the dropdown, #2845. + +### Thanks! + +- @pjeby +- @shawninder +- @tats-u +- @XeroAlpha + +## 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 + +- Fix crash with TypeScript 5.5.x, #2789. + +## v0.27.1 (2024-11-28) + +### Bug Fixes + +- Include classes which inherit from another package in class hierarchy in packages mode, #2467. +- Fixed handling of `@categoryDescription` and `@groupDescription` on module pages, #2787. +- Fixed automatic discovery of entry points in packages mode. +- Reverted accidental style change for hierarchy page introduced in 0.27.0 +- The hierarchy Expand/Collapse link will now only appear if the hierarchies are different. + +## v0.27.0 (2024-11-27) + +### Breaking Changes + +- Convert to ESM to enable easier use of ESM-only dependencies. +- Drop support for TypeScript <5.0, no longer supported by DefinitelyTyped +- Relaxed requirements for file names and generated url fragments. This may + result in a different file name structure, #2714. +- Anchors to document headings and reflections within a HTML generated pages + have changed. They can be partially restored to the previous format by + setting `--sluggerConfiguration.lowercase false`. This change was made to + more closely match the default behavior of GitHub's markdown rendering and + VSCode's autocomplete when creating a relative link to an external markdown + file. +- Removed the `hideParameterTypesInTitle` option, this was originally added as + a workaround for many signatures overflowing the available horizontal space + in rendered pages. TypeDoc now has logic to wrap types/signatures smartly, + so this option is no longer necessary. +- Changed the default `kindSortOrder` to put references last. +- Changed the default `sort` order to use `alphabetical-ignoring-documents` + instead of `alphabetical`. +- Changed default of `suppressCommentWarningsInDeclarationFiles` to `true` +- API: Constructor signatures now use the parent class name as their name + (e.g. `X`, not `new X`) +- API: `@group`, `@category`, `@groupDescription` and `@categoryDescription` + will no longer be removed from the reflections they are present on. They are + skipped during rendering with the `notRenderedTags` option. + +### Features + +- Add support for TypeScript 5.7 +- TypeDoc will now discover entry points from `package.json` exports if they + are not provided manually, #1937. +- Relative links to markdown files may now include `#anchor` links to + reference a heading within them. +- Improved support for `@param` comments with nested object types, #2555. +- Improved support for `@param` comments which reference a type + alias/interface. Important properties on the referenced type can now be + highlighted with `@param options.foo`, which will result in the additional + note being included under the documentation for that parameter, #2147. Note: + This feature is limited to references. It is not supported on other types of + types. +- Added a new `outputs` option which is an array of outputs. This can be used + to render the documentation multiple times with different rendering options + or output types, #2597. +- Added support for rendering alerts (or callouts) in markdown. +- Add support for an `@expand` tag which can be placed on type aliases and + interfaces. When a type with `@expand` is referenced and TypeDoc has a place + to include additional details about the type, the properties of the type + will be included in the page where `@expand` is found. Note that use of this + tag can _significantly_ increase the size of your generated documentation if + it is applied to commonly used types as it will result in inlining the + comments for those types everywhere they are referenced, #2303. +- Add support for an `@inline` tag which can be placed on type aliases and + interfaces. When a type with `@inline` is referenced, TypeDoc will resolve + the referenced type and convert the type as if it was included directly + within the referencing type. Note that use of this tag can _significantly_ + increase the size of your generated documentation if it is applied to + commonly used types as it will result in inlining the comments for those + types everywhere they are referenced, #2303. +- Introduced a new `@useDeclaredType` tag for type aliases which can sometimes + improve their documentation, #2654. +- Added a new `@mergeModuleWith` tag which can be used to tell TypeDoc to + place a module/namespace's children under a different module/namespace and + remove the real parent, #2281. +- Added new `@include` and `@includeCode` inline tags to include files within + comments/documents. +- Add `notRenderedTags` option. This option is similar to the `excludeTags` + option, but while `excludeTags` will result in the tag being completely + removed from the documentation, `notRenderedTags` only prevents it from + being included when rendering. +- Added `groupReferencesByType` option. +- Added `navigation.excludeReferences` option +- Added `useFirstParagraphOfCommentAsSummary` option to configure how TypeDoc + handles comments for module members without the `@summary` tag. +- Introduced `favicon` option to specify a `.ico` or `.svg` favicon to reference. +- Sections within the page and in the "On This Page" navigation are now tied + together and will expand/collapse together, #2335. +- API: Introduced a new `app.outputs` object for defining new output strategies. +- API: TypeDoc's CSS is now wrapped in `@layer typedoc`, #2782. + +### Bug Fixes + +- TypeDoc now properly flags `readonly` index signatures. +- TypeDoc will now use the first signature's comment for later signatures in + overloads if present, #2718. +- Fixed handling of `@enum` if the type was declared before the variable, #2719. +- Fixed empty top level modules page in packages mode, #2753. +- TypeDoc can now link to type alias properties, #2524. +- TypeDoc will now document the merged symbol type when considering globals + declared inside `declare global`, #2774 +- TypeDoc now converts `declare module "foo"` as a module rather than a namespace, #2778. +- Import types in type aliases now use module member references if present, #2779. +- Fixed an issue where properties were not properly marked optional in some + cases. This primarily affected destructured parameters. +- Added `yaml` to the highlight languages supported by default. +- TypeDoc now recognizes `txt` as an alias of `text` to indicate a code block + should not be highlighted. +- Items which are hidden with `@ignore` or `@hidden` but still referenced by + other types will no longer produce warnings about not being exported. +- If a project only has one module within it, TypeDoc will now consider that + module when resolving `@link` tags. +- The arrows to indicate whether or not a section is open now work when + JavaScript is disabled. +- Group/category search boosts are now applied when writing the search index + rather than when converting. This prevents issues where boosts used by just + one package were incorrectly reported as unused when running with + entryPointStrategy set to packages. + +### Thanks! + +- @Huxpro +- @mrfigg +- @tgreyuk +- @XeroAlpha + +## 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. +- Exported constants no longer render the type and default value if they are the same, #2717. +- The HTML output now wraps tag blocks with `
` tags and includes the tag name in a class name, #2723. + +### Bug Fixes + +- Correctly handle external link resolver link text when referencing an external symbol, #2700. +- Big integer literals are now supported as default values, #2721. +- Corrected handling of `@link` tags present in comments at the start of source files. +- The index will now display when a module only contains documents, #2722. +- `ReflectionSymbolId.pos` no longer references the position _before_ any doc comments for a symbol. + This could cause typedoc-plugin-dt-links to produce links which didn't go to the expected location in a file. + +### Thanks! + +- @Corso02 +- @lriggle-strib +- @XeroAlpha + +## v0.26.7 (2024-09-09) + +### Features + +- Support TypeScript 5.6, #2699. +- Added `customJs` option to include a script tag in generated HTML output, #2650. +- Added `markdownLinkExternal` option to treat `http[s]://` links in markdown documents and comments as external to be opened in a new tab, #2679. +- Added `navigation.excludeReferences` option to prevent re-exports from appearing in the left hand navigation, #2685. +- Added support for the `@abstract` tag, #2692. + +### Bug Fixes + +- Fixed an issue where links in packages mode would be resolved incorrectly, #2680. +- `@link` tags to symbols which are not included in the documentation will produce invalid link warnings again, #2681. +- Fixed handling of `@param` tags on comments attached to function callback parameters, #2683. +- The `alphabetical` and `alphabetical-ignoring-documents` sort options now use `localeCompare` to sort, #2684. +- Fixed incorrect placement of parameter default values in some signatures with a `this` parameter, #2698. + +### Thanks! + +- @Aryakoste +- @waynemwashuma + +## v0.26.6 (2024-08-18) + +### Features + +- Use of the `@extends` block tag no longer produces warnings, #2659. + This tag should only be used in JavaScript projects to specify the type parameters used when extending a parent class. It will not be rendered. +- Added new `navigation.compactFolders` option to prevent TypeDoc from compacting folders, similar to the VSCode option. #2667. + +### Bug Fixes + +- The `suppressCommentWarningsInDeclarationFiles` option now correctly ignores warnings in `.d.cts` and `.d.mts` files, #2647. +- Restored re-exports in the page navigation menu, #2671. +- JSON serialized projects will no longer contain reflection IDs for other projects created in the same run. Gerrit0/typedoc-plugin-zod#6. +- In packages mode the reflection ID counter will no longer be reset when converting projects. This previously could result in links to files not working as expected. + +## v0.26.5 (2024-07-21) + +### Features + +- TypeDoc now exposes array option defaults under `OptionDefaults`, #2640. + +### Bug Fixes + +- Constructor parameters which share a name with a property on a parent class will no longer inherit the comment on the parent class, #2636. +- Packages mode will now attempt to use the comment declared in the comment class for inherited members, #2622. +- TypeDoc no longer crashes when `@document` includes an empty file, #2638. +- API: Event listeners added later with the same priority will be called later, #2643. + +### Thanks! + +- @bladerunner2020 + +## v0.26.4 (2024-07-10) + +### Bug Fixes + +- The page navigation sidebar no longer incorrectly includes re-exports if the same member is exported with multiple names #2625. +- Page navigation now ensures the current page is visible when the page is first loaded, #2626. +- If a relative linked image is referenced multiple times, TypeDoc will no longer sometimes produce invalid links to the image #2627. +- `@link` tags will now be validated in referenced markdown documents, #2629. +- `@link` tags are now resolved in project documents, #2629. +- HTML/JSON output generated by TypeDoc now contains a trailing newline, #2632. +- TypeDoc now correctly handles markdown documents with CRLF line endings, #2628. +- `@hidden` is now properly applied when placed in a function implementation comment, #2634. +- Comments on re-exports are now rendered. + +### Thanks! + +- @bukowa +- @garrett-hopper + +## v0.26.3 (2024-06-28) + +### Features + +- "On This Page" navigation now includes the page groups in collapsible sections, #2616. + +### Bug Fixes + +- `mailto:` links are no longer incorrectly recognized as relative paths, #2613. +- Added `@since` to the default list of recognized tags, #2614. +- Relative paths to directories will no longer cause the directory to be copied into the media directory, #2617. + +## v0.26.2 (2024-06-24) + +### Features + +- Added a `--suppressCommentWarningsInDeclarationFiles` option to disable warnings from + parsing comments in declaration files, #2611. +- Improved comment discovery to more closely match TypeScript's discovery when getting comments + for members of interfaces/classes, #2084, #2545. + +### Bug Fixes + +- The `text` non-highlighted language no longer causes warnings when rendering, #2610. +- If a comment on a method is inherited from a parent class, and the child class does not + use an `@param` tag from the parent, TypeDoc will no longer warn about the `@param` tag. + +## v0.26.1 (2024-06-22) + +### Features + +- Improved Korean translation coverage, #2602. + +### Bug Fixes + +- Added `@author` to the default list of recognized tags, #2603. +- Anchor links are no longer incorrectly checked for relative paths, #2604. +- Fixed an issue where line numbers reported in error messages could be incorrect, #2605. +- Fixed relative link detection for markdown links containing code in their label, #2606. +- Fixed an issue with packages mode where TypeDoc would use (much) more memory than required, #2607. +- TypeDoc will no longer crash when asked to render highlighted code for an unsupported language, #2609. +- Fixed an issue where relatively-linked files would not be copied to the output directory in packages mode. +- Fixed an issue where modifier tags were not applied to top level modules in packages mode. +- Fixed an issue where excluded tags were not removed from top level modules in packages mode. +- `.jsonc` configuration files are now properly read as JSONC, rather than being passed to `require`. + +### Thanks! + +- @KNU-K + +## v0.26.0 (2024-06-22) + +### Breaking Changes + +- Drop support for Node 16. +- Moved from `marked` to `markdown-it` for parsing as marked has moved to an async model which supporting would significantly complicate TypeDoc's rendering code. + This means that any projects setting `markedOptions` needs to be updated to use `markdownItOptions`. + Unlike `marked@4`, `markdown-it` pushes lots of functionality to plugins. To use plugins, a JavaScript config file must be used with the `markdownItLoader` option. +- Updated Shiki from 0.14 to 1.x. This should mostly be a transparent update which adds another 23 supported languages and 13 supported themes. + As Shiki adds additional languages, the time it takes to load the highlighter increases linearly. To avoid rendering taking longer than necessary, + TypeDoc now only loads a few common languages. Additional languages can be loaded by setting the `--highlightLanguages` option. +- Changed default of `--excludePrivate` to `true`. +- Renamed `--sitemapBaseUrl` to `--hostedBaseUrl` to reflect that it can be used for more than just the sitemap. +- Removed deprecated `navigation.fullTree` option. +- Removed `--media` option, TypeDoc will now detect image links within your comments and markdown documents and automatically copy them to the site. +- Removed `--includes` option, use the `@document` tag instead. +- Removed `--stripYamlFrontmatter` option, TypeDoc will always do this now. +- Renamed the `--htmlLang` option to `--lang`. +- Removed the `--gaId` option for Google Analytics integration and corresponding `analytics` theme member, #2600. +- All function-likes may now have comments directly attached to them. This is a change from previous versions of TypeDoc where functions comments + were always moved down to the signature level. This mostly worked, but caused problems with type aliases, so was partially changed in 0.25.13. + This change was extended to apply not only to type aliases, but also other function-likes declared with variables and callable properties. + As a part of this change, comments on the implementation signature of overloaded functions will now be added to the function reflection, and will + not be inherited by signatures of that function, #2521. +- API: TypeDoc now uses a typed event emitter to provide improved type safety, this found a bug where `Converter.EVENT_CREATE_DECLARATION` + was emitted for `ProjectReflection` in some circumstances. +- API: `MapOptionDeclaration.mapError` has been removed. +- API: Deprecated `BindOption` decorator has been removed. +- API: `DeclarationReflection.indexSignature` has been renamed to `DeclarationReflection.indexSignatures`. + Note: This also affects JSON serialization. TypeDoc will support JSON output from 0.25 through at least 0.26. +- API: `JSONOutput.SignatureReflection.typeParameter` has been renamed to `typeParameters` to match the JS API. +- API: `DefaultThemeRenderContext.iconsCache` has been removed as it is no longer needed. +- API: `DefaultThemeRenderContext.hook` must now be passed `context` if required by the hook. + +### Features + +- Added support for TypeScript 5.5. +- Added new `--projectDocuments` option to specify additional Markdown documents to be included in the generated site #247, #1870, #2288, #2565. +- TypeDoc now has the architecture in place to support localization. No languages besides English + are currently shipped in the package, but it is now possible to add support for additional languages, #2475. +- Added support for a `packageOptions` object which specifies options that should be applied to each entry point when running with `--entryPointStrategy packages`, #2523. +- `--hostedBaseUrl` will now be used to generate a `` element in the project root page, #2550. +- Added support for documenting individual elements of a union type, #2585. + Note: This feature is only available on type aliases directly containing unions. +- TypeDoc will now log the number of errors/warnings errors encountered, if any, after a run, #2581. +- New option, `--customFooterHtml` to add custom HTML to the generated page footer, #2559. +- TypeDoc will now copy modifier tags to children if specified in the `--cascadedModifierTags` option, #2056. +- TypeDoc will now warn if mutually exclusive modifier tags are specified for a comment (e.g. both `@alpha` and `@beta`), #2056. +- Groups and categories can now be collapsed in the page body, #2330. +- Added support for JSDoc `@hideconstructor` tag. + This tag should only be used to work around TypeScript#58653, prefer the more general `@hidden`/`@ignore` tag to hide members normally, #2577. +- Added `--useHostedBaseUrlForAbsoluteLinks` option to use the `--hostedBaseUrl` option to produce absolute links to pages on a site, #940. +- Tag headers now generate permalinks in the default theme, #2308. +- TypeDoc now attempts to use the "most likely name" for a symbol if the symbol is not present in the documentation, #2574. +- Fixed an issue where the "On This Page" section would include markdown if the page contained headings which contained markdown. +- TypeDoc will now warn if a block tag is used which is not defined by the `--blockTags` option. +- Added three new sort strategies `documents-first`, `documents-last`, and `alphabetical-ignoring-documents` to order markdown documents. +- Added new `--alwaysCreateEntryPointModule` option. When set, TypeDoc will always create a `Module` for entry points, even if only one is provided. + If `--projectDocuments` is used to add documents, this option defaults to `true`, otherwise, defaults to `false`. +- Added new `--highlightLanguages` option to control what Shiki language packages are loaded. +- TypeDoc will now render union elements on new lines if there are more than 3 items in the union. +- TypeDoc will now only render the "Type Declaration" section if it will provide additional information not already presented in the page. + This results in significantly smaller documentation pages in many cases where that section would just repeat what has already been presented in the rendered type. +- Added `comment.beforeTags` and `comment.afterTags` hooks for plugin use. + Combined with `CommentTag.skipRendering` this can be used to provide custom tag handling at render time. + +### Bug Fixes + +- TypeDoc now supports objects with multiple index signatures, #2470. +- Header anchor links in rendered markdown are now more consistent with headers generated by TypeDoc, #2546. +- Types rendered in the `Returns` header are now properly colored, #2546. +- Links added with the `navigationLinks` option are now moved into the pull out navigation on mobile displays, #2548. +- `@license` and `@import` comments will be ignored at the top of files, #2552. +- Fixed issue in documentation validation where constructor signatures where improperly considered not documented, #2553. +- Keyboard focus is now visible on dropdowns and checkboxes in the default theme, #2556. +- The color theme label in the default theme now has an accessible name, #2557. +- Fixed issue where search results could not be navigated while Windows Narrator was on, #2563. +- `charset` is now correctly cased in `` tag generated by the default theme, #2568. +- Fixed very slow conversion on Windows where Msys git was used by typedoc to discover repository links, #2586. +- Validation will now be run in watch mode, #2584. +- Fixed an issue where custom themes which added dependencies in the `` element could result in broken icons, #2589. +- `@default` and `@defaultValue` blocks are now recognized as regular blocks if they include inline tags, #2601. +- Navigation folders sharing a name will no longer be saved with a shared key to `localStorage`. +- The `--hideParameterTypesInTitle` option no longer applies when rendering function types. +- Broken `@link` tags in readme files will now cause a warning when link validation is enabled. +- Fixed `externalSymbolLinkMappings` option's support for [meanings](https://typedoc.org/guides/declaration-references/#meaning) in declaration references. +- Buttons to copy code now have the `type=button` attribute set to avoid being treated as submit buttons. +- `--hostedBaseUrl` will now implicitly add a trailing slash to the generated URL. + +### Thanks! + +- @Aryakoste +- @bladerunner2020 +- @Dinnerbone +- @HarelM +- @kraenhansen +- @Nil2000 +- @steve02081504 +- @tristanzander ## v0.25.13 (2024-04-07) ### Features -- Added `gitRevision:short` placeholder option to `--sourceLinkTemplate` option, #2529. - Links generated by TypeDoc will now default to using the non-short git revision. -- Moved "Generated by TypeDoc" footer into a `