feat(core): exposed "useHTMLEncodedBrackets" option (#564)

.changeset/swift-baboons-bathe.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Exposed "useHTMLEncodedBrackets" option (#564).

docs/pages/docs/options.mdx

@@ -48,6 +48,7 @@ Options that are used for general configuration and utility purposes.
 - [--sanitizeComments](./options/utility-options.mdx#--sanitizecomments)
 - [--anchorPrefix](./options/utility-options.mdx#--anchorprefix)
 - [--useHTMLAnchors](./options/utility-options.mdx#--usehtmlanchors)
+- [--useHTMLEncodedBrackets](./options/utility-options.mdx#--usehtmlencodedbrackets)
 - [--preserveAnchorCasing](./options/utility-options.mdx#--preserveanchorcasing)
 - [--textContentMappings](./options/utility-options.mdx#--textcontentmappings)
 - [--navigationModel](./options/utility-options.mdx#--navigationmodel)

docs/pages/docs/options/display-options.mdx

@@ -1,4 +1,4 @@
-import { Callout, FileTree } from 'nextra/components';
+import { Callout, FileTree } from "nextra/components";
 
 # Display Options
 
@@ -115,7 +115,7 @@ This option should be set when a full type representation is preferred.
 
 <Callout emoji="💡">Sets the format of index items.</Callout>
 
-> Accepts one of `"list"` | `"table"`. Defaults to `"list"`.
+> Accepts one of `"list"` | `"table"` | `"htmlTable"`. Defaults to `"list"`.
 
 This option renders index items either as a simple unordered list or in a table.
 
@@ -142,7 +142,7 @@ When table style is selected the following will be the behaviour:
 This option specifies the output format for parameters and type parameters of functions and class methods:
 
 - **"list"**: parameters are output as bullet points in a linear list, suitable for more detailed comments.
-- **"table"**: parameters are output within a markdown table, condensed into a single paragraph.
+- **"table"**: parameters are output within a Markdown table, condensed into a single paragraph.
 - **"htmlTable"**: parameters are output in an HTML table, enabling block elements to render in table cells.
 
 ```json filename="typedoc.json"
@@ -160,7 +160,7 @@ This option specifies the output format for parameters and type parameters of fu
 This option specifies the output format for interface properties:
 
 - **"list"**: properties are output in linear blocks with headings, suitable for more detailed comments.
-- **"table"**: properties are output within a markdown table, condensed into a single paragraph.
+- **"table"**: properties are output within a Markdown table, condensed into a single paragraph.
 - **"htmlTable"**: properties are output in an HTML table, enabling block elements to render in tabular format.
 
 ```json filename="typedoc.json"
@@ -178,7 +178,7 @@ This option specifies the output format for interface properties:
 This option specifies the output format for class properties:
 
 - **"list"**: properties are output in linear blocks with headings, suitable for more detailed comments.
-- **"table"**: properties are output within a markdown table, condensed into a single paragraph.
+- **"table"**: properties are output within a Markdown table, condensed into a single paragraph.
 - **"htmlTable"**: properties are output in an HTML table, enabling block elements to render in tabular format.
 
 ```json filename="typedoc.json"
@@ -196,7 +196,7 @@ This option specifies the output format for class properties:
 This option specifies the output format for enumeration members:
 
 - **"list"**: members are output in linear blocks with headings, suitable for more detailed comments.
-- **"table"**: members are output within a markdown table, condensed into a single paragraph.
+- **"table"**: members are output within a Markdown table, condensed into a single paragraph.
 - **"htmlTable"**: members are output in an HTML table, enabling block elements to render in tabular format.
 
 ```json filename="typedoc.json"
@@ -216,7 +216,7 @@ This option specifies the output format for enumeration members:
 This option specifies the output format for type declaration of variables and type aliases.
 
 - **"list"**: declarations are output in linear blocks with headings, suitable for more detailed comments.
-- **"table"**: declarations are output within a markdown table, condensed into a single paragraph.
+- **"table"**: declarations are output within a Markdown table, condensed into a single paragraph.
 - **"htmlTable"**: declarations are output in an HTML table, enabling block elements to render in tabular format.
 
 ```json filename="typedoc.json"
@@ -238,7 +238,7 @@ This option will handle the formatting of object literals assigned as properties
 Note this options will only take effect when `propertiesFormat` is set to `list`.
 
 - **"list"**: members are output in linear blocks with headings, suitable for more detailed comments.
-- **"table"**: members are output within a markdown table, condensed into a single paragraph.
+- **"table"**: members are output within a Markdown table, condensed into a single paragraph.
 - **"htmlTable"**: members are output in an HTML table, enabling block elements to render in tabular format.
 
 ```json filename="typedoc.json"

docs/pages/docs/options/file-options.mdx

@@ -125,7 +125,7 @@ Flattened output:
 
 > Accepts a string value. Defaults to `".md"`.
 
-Typically markdown files are recognised by the `.md` or `.markdown` file extensions.`.mdx` maybe required for compatibility with certain markdown parsers.
+Typically Markdown files are recognised by the `.md` or `.markdown` file extensions.`.mdx` maybe required for compatibility with certain Markdown parsers.
 
 ```json filename="typedoc.json"
 {

docs/pages/docs/options/utility-options.mdx

@@ -66,7 +66,7 @@ This option should be used when parsers require a custom anchor prefix.
 
 This option should be used if there are issues with anchoring to symbols within a page.
 
-- For markdown parsers that do not automatically assign header ids.
+- For Markdown parsers that do not automatically assign header ids.
 - When cross referencing symbols that are referenced in a table row.
 
 ```json filename="typedoc.json"
@@ -75,6 +75,21 @@ This option should be used if there are issues with anchoring to symbols within
 }
 ```
 
+## --useHTMLEncodedBrackets
+
+<Callout emoji="💡">Use HTML encoded entities for angle brackets.</Callout>
+
+> Accepts a boolean value. Defaults to `false`.
+
+By default, opening and closing angle brackets (`<` and `>`) are escaped using backslashes, and most modern Markdown processors handle them consistently.
+However, using HTML entities (`&lt;` and `&gt;`) might be preferable to avoid any inconsistencies across different Markdown processors.
+
+```json filename="typedoc.json"
+{
+  "useHTMLEncodedBrackets": false
+}
+```
+
 ## --preserveAnchorCasing
 
 <Callout emoji="💡">

packages/typedoc-plugin-markdown/src/_typedoc.d.ts

@@ -60,6 +60,7 @@ declare module 'typedoc' {
     typeDeclarationFormat: 'list' | 'table' | 'htmlTable';
     useCodeBlocks: boolean;
     useHTMLAnchors: boolean;
+    useHTMLEncodedBrackets: boolean;
   }
 
   // eslint-disable-next-line @typescript-eslint/no-namespace

packages/typedoc-plugin-markdown/src/libs/utils/_index.ts

@@ -1,4 +1,5 @@
 export * from './camel-to-title-case';
+export * from './encode-angle-brackets';
 export * from './escape-chars';
 export * from './format-markdown';
 export * from './format-table-cell';

packages/typedoc-plugin-markdown/src/libs/utils/encode-angle-brackets.ts

@@ -0,0 +1,3 @@
+export function encodeAngleBrackets(str: string) {
+  return str.replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}

packages/typedoc-plugin-markdown/src/libs/utils/un-escape-chars.ts

@@ -4,11 +4,12 @@ export function unEscapeChars(str: string) {
       /(`[^`]*?)\\*([^`]*?`)/g,
       (match, p1, p2) => `${p1}${p2.replace(/\*/g, '\\*')}`,
     )
-    .replace(/ ↗️/g, '')
     .replace(/\\\\/g, '\\')
     .replace(/(?<!\\)\*/g, '')
     .replace(/\\</g, '<')
     .replace(/\\>/g, '>')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
     .replace(/\\_/g, '_')
     .replace(/\\{/g, '{')
     .replace(/\\}/g, '}')

packages/typedoc-plugin-markdown/src/options/declarations.ts

@@ -140,7 +140,7 @@ export const flattenOutputFiles: Partial<DeclarationOption> = {
 };
 
 /**
- * Typically markdown files are recognised by the `.md` or `.markdown` file extensions.`.mdx` maybe required for compatibility with certain markdown parsers.
+ * Typically Markdown files are recognised by the `.md` or `.markdown` file extensions.`.mdx` maybe required for compatibility with certain Markdown parsers.
  *
  * @example ".mdx"
  *
@@ -358,7 +358,7 @@ export const indexFormat: Partial<DeclarationOption> = {
  * This option specifies the output format for parameters and type parameters of functions and class methods:
  *
  * - **"list"**: parameters are output as bullet points in a linear list, suitable for more detailed comments.
- * - **"table"**: parameters are output within a markdown table, condensed into a single paragraph.
+ * - **"table"**: parameters are output within a Markdown table, condensed into a single paragraph.
  * - **"htmlTable"**: parameters are output in an HTML table, enabling block elements to render in table cells.
  *
  * @category Display
@@ -374,7 +374,7 @@ export const parametersFormat: Partial<DeclarationOption> = {
  * This option specifies the output format for interface properties:
  *
  * - **"list"**: properties are output in linear blocks with headings, suitable for more detailed comments.
- * - **"table"**: properties are output within a markdown table, condensed into a single paragraph.
+ * - **"table"**: properties are output within a Markdown table, condensed into a single paragraph.
  * - **"htmlTable"**: properties are output in an HTML table, enabling block elements to render in tabular format.
  *
  * @category Display
@@ -390,7 +390,7 @@ export const interfacePropertiesFormat: Partial<DeclarationOption> = {
  * This option specifies the output format for class properties:
  *
  * - **"list"**: properties are output in linear blocks with headings, suitable for more detailed comments.
- * - **"table"**: properties are output within a markdown table, condensed into a single paragraph.
+ * - **"table"**: properties are output within a Markdown table, condensed into a single paragraph.
  * - **"htmlTable"**: properties are output in an HTML table, enabling block elements to render in tabular format.
  *
  * @category Display
@@ -406,7 +406,7 @@ export const classPropertiesFormat: Partial<DeclarationOption> = {
  * This option specifies the output format for enumeration members:
  *
  * - **"list"**: members are output in linear blocks with headings, suitable for more detailed comments.
- * - **"table"**: members are output within a markdown table, condensed into a single paragraph.
+ * - **"table"**: members are output within a Markdown table, condensed into a single paragraph.
  * - **"htmlTable"**: members are output in an HTML table, enabling block elements to render in tabular format.
  *
  * @category Display
@@ -422,7 +422,7 @@ export const enumMembersFormat: Partial<DeclarationOption> = {
  * This option specifies the output format for type declaration of variables and type aliases.
  *
  * - **"list"**: declarations are output in linear blocks with headings, suitable for more detailed comments.
- * - **"table"**: declarations are output within a markdown table, condensed into a single paragraph.
+ * - **"table"**: declarations are output within a Markdown table, condensed into a single paragraph.
  * - **"htmlTable"**: declarations are output in an HTML table, enabling block elements to render in tabular format.
  *
  * @category Display
@@ -440,7 +440,7 @@ export const typeDeclarationFormat: Partial<DeclarationOption> = {
  * Note this options will only take effect when `propertiesFormat` is set to `list`.
  *
  * - **"list"**: members are output in linear blocks with headings, suitable for more detailed comments.
- * - **"table"**: members are output within a markdown table, condensed into a single paragraph.
+ * - **"table"**: members are output within a Markdown table, condensed into a single paragraph.
  * - **"htmlTable"**: members are output in an HTML table, enabling block elements to render in tabular format.
  *
  * @category Display
@@ -539,7 +539,7 @@ export const anchorPrefix: Partial<DeclarationOption> = {
 /**
  * This option should be used if there are issues with anchoring to symbols within a page.
  *
- * - For markdown parsers that do not automatically assign header ids.
+ * - For Markdown parsers that do not automatically assign header ids.
  * - When cross referencing symbols that are referenced in a table row.
  *
  * @category Utility
@@ -550,6 +550,18 @@ export const useHTMLAnchors: Partial<DeclarationOption> = {
   defaultValue: false,
 };
 
+/**
+ * By default, opening and closing angle brackets (`<` and `>`) are escaped using backslashes, and most modern Markdown processors handle them consistently.
+ * However, using HTML entities (`&lt;` and `&gt;`) might be preferable to avoid any inconsistencies across different Markdown processors.
+ *
+ * @category Utility
+ */
+export const useHTMLEncodedBrackets: Partial<DeclarationOption> = {
+  help: 'Use HTML encoded entities for angle brackets.',
+  type: ParameterType.Boolean,
+  defaultValue: false,
+};
+
 /**
  * By default references to symbol anchor links are lowercased.
  *

packages/typedoc-plugin-markdown/src/theme/context/helpers/_index.ts

@@ -1,3 +1,4 @@
+export * from './get-angle-bracket';
 export * from './get-comment-parts';
 export * from './get-declaration-type';
 export * from './get-description-for-reflection';

packages/typedoc-plugin-markdown/src/theme/context/helpers/get-angle-bracket.ts

@@ -0,0 +1,12 @@
+import { MarkdownThemeContext } from '@plugin/theme';
+
+export function getAngleBracket(
+  this: MarkdownThemeContext,
+  bracket: '<' | '>',
+): string {
+  const useEntities = this.options.getValue('useHTMLEncodedBrackets');
+  if (bracket === '<') {
+    return useEntities ? '&lt;' : '\\<';
+  }
+  return useEntities ? '&gt;' : '\\>';
+}

packages/typedoc-plugin-markdown/src/theme/context/partials/member.declarationTitle.ts

@@ -1,6 +1,7 @@
-import { backTicks, bold, codeBlock } from 'libs/markdown';
-import { escapeChars } from 'libs/utils';
-import { MarkdownThemeContext } from 'theme';
+import { backTicks, bold, codeBlock } from '@plugin/libs/markdown';
+import { escapeChars } from '@plugin/libs/utils';
+import { encodeAngleBrackets } from '@plugin/libs/utils/encode-angle-brackets';
+import { MarkdownThemeContext } from '@plugin/theme';
 import { DeclarationReflection } from 'typedoc';
 
 export function declarationTitle(
@@ -54,17 +55,21 @@ export function declarationTitle(
       ? nameParts[nameParts.length - 1]
       : model.name;
 
+  const displayDeclarationName = this.options.getValue('useHTMLEncodedBrackets')
+    ? encodeAngleBrackets(declarationName)
+    : declarationName;
+
   name.push(
     /[\\`]/.test(declarationName)
-      ? escapeChars(declarationName)
-      : bold(escapeChars(declarationName)),
+      ? escapeChars(displayDeclarationName)
+      : bold(escapeChars(displayDeclarationName)),
   );
 
   if (model.typeParameters) {
     name.push(
-      `\\<${model.typeParameters
+      `${this.helpers.getAngleBracket('<')}${model.typeParameters
         ?.map((typeParameter) => backTicks(typeParameter.name))
-        .join(', ')}\\>`,
+        .join(', ')}${this.helpers.getAngleBracket('>')}`,
     );
   }
 

packages/typedoc-plugin-markdown/src/theme/context/partials/member.memberTitle.ts

@@ -1,6 +1,7 @@
-import { backTicks, strikeThrough } from 'libs/markdown';
-import { escapeChars } from 'libs/utils';
-import { MarkdownThemeContext } from 'theme';
+import { backTicks, strikeThrough } from '@plugin/libs/markdown';
+import { escapeChars } from '@plugin/libs/utils';
+import { encodeAngleBrackets } from '@plugin/libs/utils/encode-angle-brackets';
+import { MarkdownThemeContext } from '@plugin/theme';
 import { DeclarationReflection, ReflectionKind, ReflectionType } from 'typedoc';
 
 export function memberTitle(
@@ -14,10 +15,12 @@ export function memberTitle(
     name.push(this.helpers.getReflectionFlags(model.flags) + ' ');
   }
 
+  const modelName = this.options.getValue('useHTMLEncodedBrackets')
+    ? encodeAngleBrackets(model.name)
+    : model.name;
+
   name.push(
-    `${
-      /\\/.test(model.name) ? backTicks(model.name) : escapeChars(model.name)
-    }`,
+    `${/\\/.test(model.name) ? backTicks(model.name) : escapeChars(modelName)}`,
   );
 
   if (
@@ -31,7 +34,9 @@ export function memberTitle(
     const typeParameters = model.typeParameters
       .map((typeParameter) => typeParameter.name)
       .join(', ');
-    name.push(`${`\\<${typeParameters}\\>`}`);
+    name.push(
+      `${`${this.helpers.getAngleBracket('<')}${typeParameters}${this.helpers.getAngleBracket('>')}`}`,
+    );
   }
 
   if (model.flags.isOptional) {

packages/typedoc-plugin-markdown/src/theme/context/partials/member.signatureTitle.ts

@@ -1,6 +1,6 @@
-import { backTicks, bold, codeBlock } from 'libs/markdown';
-import { escapeChars } from 'libs/utils';
-import { MarkdownThemeContext } from 'theme';
+import { backTicks, bold, codeBlock } from '@plugin/libs/markdown';
+import { escapeChars } from '@plugin/libs/utils';
+import { MarkdownThemeContext } from '@plugin/theme';
 import { SignatureReflection } from 'typedoc';
 
 export function signatureTitle(
@@ -37,9 +37,9 @@ export function signatureTitle(
 
   if (model.typeParameters) {
     md.push(
-      `\\<${model.typeParameters
+      `${this.helpers.getAngleBracket('<')}${model.typeParameters
         .map((typeParameter) => backTicks(typeParameter.name))
-        .join(', ')}\\>`,
+        .join(', ')}${this.helpers.getAngleBracket('>')}`,
     );
   }
 

packages/typedoc-plugin-markdown/src/theme/context/partials/member.typeArguments.ts

@@ -1,18 +1,18 @@
-import { MarkdownThemeContext } from 'theme';
+import { MarkdownThemeContext } from '@plugin/theme';
 import { ReflectionType, SomeType } from 'typedoc';
 
 export function typeArguments(
   this: MarkdownThemeContext,
   model: SomeType[],
   options?: { forceCollapse?: boolean },
 ): string {
-  return `\\<${model
+  return `${this.helpers.getAngleBracket('<')}${model
     .map((typeArgument) =>
       typeArgument instanceof ReflectionType
         ? this.partials.reflectionType(typeArgument, {
             forceCollapse: options?.forceCollapse,
           })
         : this.partials.someType(typeArgument),
     )
-    .join(', ')}\\>`;
+    .join(', ')}${this.helpers.getAngleBracket('>')}`;
 }