feat: Added sanitizeComments option.

.github/workflows/ci.yml

@@ -32,6 +32,6 @@ jobs:
       - name: Lint
         run: npm run lint --workspace typedoc-plugin-markdown
       - name: Build
-        run: npm run build --workspaces --if-present
+        run: npm run build-all
       - name: Test
-        run: npm run test --workspaces --if-present
+        run: npm run test-all

.prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "plugins": ["prettier-plugin-organize-imports"]
+}

devtools/examples/docusaurus/docusaurus.config.js

@@ -143,6 +143,7 @@ const config = {
       ({
         docs: {
           sidebarPath: require.resolve('./sidebars.js'),
+          sidebarCollapsed: true,
           numberPrefixParser: false,
 
           // Please change this to your repo.
@@ -167,6 +168,9 @@ const config = {
     ({
       // Replace with your project's social card
       image: 'img/docusaurus-social-card.jpg',
+      sidebar: {
+        autoCollapseCategories: true,
+      },
       navbar: {
         title: 'My Site',
         logo: {

devtools/packages/prebuild-options/tasks/generate-docs.ts

@@ -14,9 +14,17 @@ export async function generateOptionsDocs(docsConfig: DocsConfig) {
     `import { Callout, FileTree } from 'nextra/components';`,
   ];
   out.push('# Options');
-  out.push(
-    'Listed on this page are the additional options that can be added to the TypeDoc configuration.',
-  );
+  if (docsConfig.docsPath === '/docs') {
+    out.push(
+      `These options can be used in addition to the core TypeDoc options.`,
+    );
+  } else {
+    out.push(
+      `<Callout type="info">
+  Please view options exposed by [typedoc-plugin-markdown](/docs/options) in addition to those listed here.
+</Callout>`,
+    );
+  }
 
   // DECLARATIONS
   if (docsConfig.declarations) {

docs/package.json

@@ -12,19 +12,19 @@
   },
   "author": "Thomas Grey",
   "dependencies": {
-    "@fortawesome/fontawesome-svg-core": "^6.5.1",
-    "@fortawesome/free-brands-svg-icons": "^6.5.1",
-    "@fortawesome/free-solid-svg-icons": "^6.5.1",
+    "@fortawesome/fontawesome-svg-core": "^6.5.2",
+    "@fortawesome/free-brands-svg-icons": "^6.5.2",
+    "@fortawesome/free-solid-svg-icons": "^6.5.2",
     "@fortawesome/react-fontawesome": "^0.2.0",
     "@vercel/analytics": "^1.2.2",
-    "next": "^14.1.4",
+    "next": "^14.2.1",
     "nextra": "3.0.0-alpha.22",
     "nextra-theme-docs": "3.0.0-alpha.22",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@types/node": "^20.12.4",
+    "@types/node": "^20.12.7",
     "autoprefixer": "^10.4.19",
     "postcss": "^8.4.38",
     "tailwindcss": "^3.4.3"

docs/pages/api-docs/Interface.NavigationItem.md

@@ -10,9 +10,9 @@ The model used to define the navigation structure.
 
 ***
 
-### url?
+### path?
 
-> `optional` **url**: `null` \| `string`
+> `optional` **path**: `null` \| `string`
 
 ***
 

docs/pages/api-docs/Interface.PluginOptions.md

@@ -196,6 +196,14 @@ Specify the base path for all urls.
 
 ***
 
+### sanitizeComments
+
+> **sanitizeComments**: `boolean`
+
+Sanitize HTML and JSX inside JsDoc comments.
+
+***
+
 ### textContentMappings
 
 > **textContentMappings**: `Partial`\<[`TextContentMappings`](/api-docs/Interface.TextContentMappings.md)\>

docs/pages/docs/_meta.js

@@ -10,6 +10,7 @@ export default {
     type: 'separator',
     title: 'Guides',
   },
+  'using-typedoc': '',
   'customizing-output': '',
   navigation: '',
   '-- Support': {

docs/pages/docs/changelog.mdx

@@ -18,20 +18,6 @@ import { Callout } from 'nextra/components';
 - Improved and cleaner UI.
 - A set of updated and additional new options with comprehensive documentation.
 
-### 🐛 Bug Fixes
-
-The release features numerous bug fixes including:
-
-- Duplication in callback/callable/function properties. ([#581](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/581)).
-- @experimental / @internal annotations ([#556](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/556))
-- Fix events output and strikethough deprecqted items ([#534](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/534))
-- @example block not rendered with Headline ([#501](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/501))
-- Correctly resolve packge readme urls from member pages ([#483](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/483))
-- Mark final default parameters as optional ([#396](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/396))
-- Respect monorepo `readmeFile` configuration ([#383](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/383))
-- Replace new lines in tables with `<br />` ([#331](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/331))
-- Provide a link/excerpt/screenshot to a demo/example rendered outpout ([#102](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/102))
-
 ### 🚀 Migrating from v3
 
 Migrating from v3 to v4 should be fairly straightforward. These pointers will help you understand the changes and how to update your project.
@@ -52,4 +38,36 @@ Migrating from v3 to v4 should be fairly straightforward. These pointers will he
 - The option `hideInPageTOC` has been removed. In-page TOC are no longer included by default. You can include in-page TOCs by using [typedoc-plugin-remark](/plugins/remark) and the [remark-toc](plugins/remark/suggested-plugins#remark-toc) plugin.
 - The option `objectLiteralTypeDeclarationStyle` has been removed. Please use [`typeDeclarationFormat`](/docs/options#typedeclarationformat).
 
+### 🐛 Bug Fixes
+
+The release features numerous bug fixes including:
+
+- Duplication in callback/callable/function properties. ([#581](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/581)).
+- @experimental / @internal annotations. ([#556](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/556))
+- Fix events output and strikethough deprecqted items. ([#534](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/534))
+- Class static functions are no longer marked. ([#533](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/533))
+- @example block not rendered with Headline ([#501](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/501))
+- Support for categories ([#499](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/499))
+- Correctly resolve packge readme urls from member pages. ([#483](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/483))
+- Add the ability to add a separate frontmatter for readme file. ([#469](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/469))
+- Items in tables are not linkable. ([#463](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/463))
+- Custom i18n texts. ([#458](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/458))
+- How to improve the formatting for types?. ([#456](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/456))
+- How to change title format. ([#450](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/450))
+- Export Docusaurus plugin options type. ([#440](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/440))
+- How to export interface as a table. ([#403](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/403))
+- Broken Link caused by Typescript class being defined in an index file. ([#402](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/403))
+- Markdown plugin inserts unnecessary escape characters. ([#398](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/398))
+- Potential bug with optional function argument. ([#396](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/396))
+- Respect monorepo `readmeFile` configuration ([#383](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/383))
+- Embed all objects under a Module/Namespace onto single page. ([#338](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/338))
+- Extra spaces when merging lines in a table. ([#331](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/331))
+- Does not support namespace (or module) and interface with same name. ([#300](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/300))
+- Integration with VitePress? ([#287](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/287))
+- Typedoc comments with text wrapped in `<` and `>` breaks Docusaurus Markdown parser. ([#276](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/276))
+- Navigation support? ([#262](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/262))
+- Sidebar Category Support? ([#213](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/213))
+- Properties as Table like function properties. ([#109](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/109))
+- Provide a link/excerpt/screenshot to a demo/example rendered outpout ([#102](https://github.com/tgreyuk/typedoc-plugin-markdown/issues/102))
+
 

docs/pages/docs/options.mdx

@@ -2,7 +2,7 @@ import { Callout, FileTree } from 'nextra/components';
 
 # Options
 
-Listed on this page are the additional options that can be added to the TypeDoc configuration.
+These options can be used in addition to the core TypeDoc options.
 
 ## Output Options
 
@@ -729,6 +729,34 @@ This option should be used if there are issues with anchoring to symbols within
 
 ___
 
+### sanitizeComments
+
+<Callout emoji="💡">Sanitize HTML and JSX inside JsDoc comments.</Callout>
+
+> Accepts a boolean value. Defaults to `false`.
+
+*Please note this options does not effect the rendering of inline code or code blocks (using single/triple backticks).*
+
+By default all comments writen inside JsDoc comments will be passed to the output as written, and parsers will interpret un-escaped angle brackets as HTML/JSX tags..
+
+This option will escape angle brackets `<` `>` and curly braces `{` `}` written inside JsDoc comments.
+
+This option would typically be used when source code comes from an external library exposing the following poential issues:
+
+- Comments contain raw tags that should be interpreted as code examples.
+- Comments contain invalid syntax that (in the case of MDX) will cause breaking parsing errors.
+- Although most parsers use XSS filters, this option provides an additional layer of XSS security.
+
+
+```json filename="typedoc.json"
+{
+  "sanitizeComments": false
+}
+
+```
+
+___
+
 ### preserveAnchorCasing
 
 <Callout emoji="💡">Preserve anchor casing when generating link to symbols.</Callout>

docs/pages/docs/quick-start.mdx

@@ -14,38 +14,29 @@ npm install typedoc typedoc-plugin-markdown@next --save-dev
 
 ## Usage
 
-Plugins are loaded by using the TypeDoc [`plugin`](https://typedoc.org/options/configuration/#plugin) configuration option:
+Plugins are loaded by using the TypeDoc `plugin` configuration option:
+
+```shell
+typedoc --plugin typedoc-plugin-markdown --out ./docs
+```
+
+Or:
 
 ```json filename="typedoc.json"
 {
-  "plugin": ["typedoc-plugin-markdown"]
+  "plugin": ["typedoc-plugin-markdown"],
+  "out": "./docs"
 }
 ```
 
-## Options
-
-### Setting Options
-
-Please see TypeDoc's [Configuring Options](https://typedoc.org/options/configuration/) page for details on how to set options.
-
-Options can be set via a `typedoc.json` file, or if you would like to inform your IDE about the shape of the exported options the plugin provides, you can use a `typedoc.config.js` file:
-
-```js filename="typedoc.config.js"
-/** @type {import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions} */
-module.exports = {
-  entryPoints: ['./src/index.ts', './src/secondary-entry.ts'],
-  out: 'doc',
-};
+```json filename="package.json"
+{
+  "docs": "typedoc"
+}
 ```
 
-For a full list of additional options exposed by this plugin, see the [Options](/docs/options) page.
-
-### Supported TypeDoc Options
-
-The majority of [TypeDoc's options](https://typedoc.org/options/) are supported, including all [input](https://typedoc.org/options/input/), [comments](https://typedoc.org/options/comments/), [organization](https://typedoc.org/options/organization/), [validation](https://typedoc.org/options/validation/) and [other](https://typedoc.org/options/other/) options.
-[Output](https://typedoc.org/options/output/) options that are specific to the HTML theme are ignored.
-
-Some typical (and frequently asked about) TypeDoc options that might be useful are:
+```shell filename="CLI"
+npm run docs
+```
 
-- Using [disableSources](https://typedoc.org/options/output/#disablesources) to prevent outputting source references.
-- Setting [readme](https://typedoc.org/options/input/#readme) to `none` to exclude the project readme from the docs.
+For more information please see the [Using TypeDoc](/docs/using-typedoc) guide.

docs/pages/docs/using-typedoc.mdx

@@ -0,0 +1,55 @@
+import { Callout, FileTree } from 'nextra/components';
+
+# Using TypeDoc
+
+This plugin is like any other TypeDoc plugin and is fully compatible with the TypeDoc ecosystem, supporting other plugins (not spefically targetting HTML output) and the majority of TypeDoc's options.
+
+## Configuring Options
+
+Please see TypeDoc's [Configuring Options](https://typedoc.org/options/configuration/) page for details on how to set options.
+
+## Option Typings
+
+If you would like to inform your IDE about the shape of the exported options the plugin provides a `PluginOptions` interface that can be imported to a `typedoc.config.js` file with a `@type` annotation:
+
+```js filename="typedoc.config.js"
+/** @type {import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions} */
+module.exports = {
+  entryPoints: ['./src/index.ts', './src/secondary-entry.ts'],
+  out: 'doc',
+  plugin: ['typedoc-plugin-markdown', 'some-other-plugin'],
+};
+```
+
+For a full list of additional options exposed by this plugin, see the [Options](/docs/options) page.
+
+## TypeDoc Options
+
+### Supported Options
+
+The majority of [TypeDoc's options](https://typedoc.org/options/) are supported, including all [input](https://typedoc.org/options/input/), [comments](https://typedoc.org/options/comments/), [organization](https://typedoc.org/options/organization/), [validation](https://typedoc.org/options/validation/) and [other](https://typedoc.org/options/other/) options.
+These options control the behaviour of TypeDoc when parsing source files and are not specific to any particular theme.
+
+### Ignored Options
+
+[Output](https://typedoc.org/options/output/) options that are specific to the HTML theme are ignored.
+
+The ignored output options are:
+
+- `--cacheBust` ❌
+- `--cname` ❌
+- `--customCss` ❌
+- `--darkHighlightTheme` ❌
+- `--gaID` ❌
+- `--githubPages` ❌
+- `--htmlLang` ❌
+- `--lightHighlightTheme` ❌
+- `--markedOptions` ❌
+- `--searchCategoryBoosts` ❌
+- `--searchGroupBoosts` ❌
+- `--searchInComments` ❌
+- `--sitemapBaseUrl` ❌
+- `--visibilityFilters` ❌
+
+*As of TypeDoc version 0.25.13*
+

docs/pages/plugins/docusaurus.mdx

@@ -8,15 +8,30 @@ import { faBolt } from '@fortawesome/free-solid-svg-icons';
 
 <PackageDescription pjson={pjson}></PackageDescription>
 
+## Overview
+
+This plugin integrates TypeDoc into the Docusaurus lifecycle and generates static TypeDoc pages in Markdown.
+
 ## Features
 
 - Presets relevant options of typedoc-plugin-markdown.
-- Runs TypeDoc from the Docusaurus CLI.
-- Builds sidebar file.
+- Bootstraps TypeDoc from the Docusaurus CLI.
+- Generates a sidebar file with configurable structure.
+
+## Alternatives
+
+A popular alternative to this plugin is [docusaurus-plugin-typedoc-api](https://www.npmjs.com/package/docusaurus-plugin-typedoc-api).
+
+The main difference is:
+
+- `docusaurus-plugin-typedoc-api` renders dynamic React pages offering a rich and flexible UI and is fully integrated with the Docusaurus ecosystem.
+- `docusaurus-plugin-typedoc` (this plugin) renders static markdown files but is more integrated with the TypeDoc ecosystem and is compatible with other TypeDoc plugins.
+
+In the end it comes down to personal preference and the requirements of your project.
 
 ## Example
 
-The following is a simple example of a VitePress project running TypeDoc.
+The following is a simple example of a Docusaurus project running TypeDoc.
 
 <Cards num={2}>
   <Cards.Card

docs/pages/plugins/docusaurus/_meta.js

@@ -1,5 +1,5 @@
 export default {
   'quick-start': '',
   options: '',
-  guide: '',
+  guide: 'Guide',
 };

docs/pages/plugins/docusaurus/changelog.mdx

@@ -0,0 +1,23 @@
+# Changelog
+
+## 1.0.0-next.xx
+
+> v1 is a new release along with typedoc-plugin-markdown v4.
+
+### 🚀 Migrating from 0.x.x
+
+#### 💥 Breaking Changes
+
+##### typedoc-plugin-Markdown
+
+- Please see typedoc-plugin-markdown migration guide for details on how to migrate from v3 to v4.
+
+##### Sidebar
+
+- A manual sidebar file should be referenced in `sidebars.js` rather than autogenerated configuration as previouslly recommended. See [sidebar guide](/plugins/docusaurus/guide/sidebar).
+- With the updated configuration the existing sidebar options `position` and `categoryLabel` are no longer relevant.
+
+##### Other options
+
+- `includeExtension` has been removed as this behaviour is now the default.
+- `frontmatter` option has been removed. Please use `typedoc-plugin-frontmatter`.