fix(core): fix inline formatting of types when "useCodeBlocks" is used

Author: tgreyuk

.changeset/selfish-pens-live.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- fix(core): Fix inline formatting of types when when "useCodeBlocks" is used (#742).

packages/typedoc-plugin-markdown/src/libs/markdown/back-ticks.ts

@@ -2,8 +2,16 @@ import { escapeChars } from '@plugin/libs/utils/index.js';
 
 /**
  * Wraps a string in backticks.
- * If the input string itself contains a backtick, pipe, or backslash (which can result in unwanted side effects) the string is escaped instead.
  */
 export function backTicks(text: string) {
-  return /(`|\||\\)/g.test(text) ? escapeChars(text) : `\`${text}\``;
+  // If the input string itself contains a pipe, or backslash (which can result in unwanted side effects) the string is escaped instead.
+  if (/(\||\\)/g.test(text)) {
+    return escapeChars(text);
+  }
+  // If the input string itself contains a backtick, the string is wrapped in double backticks.
+  if (/`/g.test(text)) {
+    return `\`\` ${text} \`\``;
+  }
+  // Otherwise, the string is wrapped in single backticks.
+  return `\`${text}\``;
 }

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

@@ -13,7 +13,11 @@ export function unEscapeChars(str: string) {
     .replace(/\\_/g, '_')
     .replace(/\\{/g, '{')
     .replace(/\\}/g, '}')
-    .replace(/(?<!\\)`/g, '')
+    .replace(/``.*?``|(?<!\\)`/g, (match) =>
+      match.startsWith('``') ? match : '',
+    )
+    .replace(/`` /g, '')
+    .replace(/ ``/g, '')
     .replace(/\\`/g, '`')
     .replace(/\\\*/g, '*')
     .replace(/\\\|/g, '|')

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

@@ -1,23 +1,29 @@
-import { backTicks } from '@plugin/libs/markdown/index.js';
+import { backTicks, codeBlock } from '@plugin/libs/markdown/index.js';
 import { MarkdownThemeContext } from '@plugin/theme/index.js';
 import { SignatureReflection } from 'typedoc';
 
 export function indexSignature(
   this: MarkdownThemeContext,
   model: SignatureReflection,
 ): string {
-  const md = [''];
+  const useCodeBlocks = this.options.getValue('useCodeBlocks');
+
   const params = model.parameters
     ? model.parameters.map((parameter) => {
         return parameter.type
-          ? `${backTicks(parameter.name)}: ${this.partials.someType(
+          ? `${useCodeBlocks ? parameter.name : backTicks(parameter.name)}: ${this.partials.someType(
               parameter.type,
             )}`
           : '';
       })
     : [];
   if (model.type) {
-    md.push(`\\[${params.join('')}\\]: ${this.partials.someType(model.type)}`);
+    if (this.options.getValue('useCodeBlocks')) {
+      return codeBlock(
+        `[${params.join('')}]: ${this.partials.someType(model.type)}`,
+      );
+    }
+    return `\\[${params.join('')}\\]: ${this.partials.someType(model.type)}`;
   }
-  return md.join(' ');
+  return '';
 }

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

@@ -1,4 +1,5 @@
-import { backTicks, link } from '@plugin/libs/markdown/index.js';
+import { backTicks, codeBlock, link } from '@plugin/libs/markdown/index.js';
+import { removeLineBreaks } from '@plugin/libs/utils/index.js';
 import { MarkdownThemeContext } from '@plugin/theme/index.js';
 import { ArrayType, ReferenceType, SignatureReflection } from 'typedoc';
 
@@ -15,11 +16,11 @@ export function typeAndParent(
   }
 
   if (model instanceof ReferenceType && model.reflection) {
-    const refl =
+    const reflection =
       model.reflection instanceof SignatureReflection
         ? model.reflection.parent
         : model.reflection;
-    const parent = refl?.parent;
+    const parent = reflection?.parent;
     if (parent) {
       const resultWithParent: string[] = [];
       if (parent?.url) {
@@ -29,15 +30,18 @@ export function typeAndParent(
       } else {
         resultWithParent.push(backTicks(parent?.name));
       }
-      if (refl?.url) {
+      if (reflection?.url) {
         resultWithParent.push(
-          link(backTicks(refl.name), this.getRelativeUrl(refl.url)),
+          link(backTicks(reflection.name), this.getRelativeUrl(reflection.url)),
         );
       } else {
-        resultWithParent.push(backTicks(refl?.name));
+        resultWithParent.push(backTicks(reflection?.name));
       }
       return resultWithParent.join('.');
     }
   }
-  return backTicks(model.toString());
+  if (this.options.getValue('useCodeBlocks')) {
+    return codeBlock(model.toString());
+  }
+  return backTicks(removeLineBreaks(model.toString()));
 }

packages/typedoc-plugin-markdown/src/theme/context/resources.ts

@@ -290,7 +290,7 @@ There is no association list partial for properties as these are handled as a st
 
 export const resourceHelpers = (context: MarkdownThemeContext) => {
   return {
-    getAngleBracket: (bracket: '<' | '>') =>
+    getAngleBracket: (bracket: '>' | '<') =>
       helpers.getAngleBracket.apply(context, [bracket]) as string,
     getCommentParts: (model: CommentDisplayPart[]) =>
       helpers.getCommentParts.apply(context, [model]) as string,

packages/typedoc-plugin-markdown/test/fixtures/config.mjs

@@ -275,7 +275,7 @@ const config = {
   },
   utils: {
     only: false,
-    entryPoints: '/utils/index.ts',
+    entryPoints: '/utils/*.ts',
     commonOptions: {
       hidePageHeader: true,
       hideBreadcrumbs: true,

packages/typedoc-plugin-markdown/test/fixtures/src/utils/asserts-template-literal.ts

@@ -0,0 +1,31 @@
+export type Integrity = `sha512-${string}`;
+
+export const isIntegrity = (i: unknown): i is Integrity =>
+  typeof i === "string" && i.startsWith("sha512-");
+
+export const asIntegrity = (i: unknown): Integrity => {
+  if (!isIntegrity(i)) {
+    throw new Error("not integrity");
+  }
+  return i;
+};
+
+export const assertIntegrity: (i: unknown) => asserts i is Integrity = (i) => {
+  asIntegrity(i);
+};
+
+export type CustomString = string;
+
+export const isString = (i: unknown): i is CustomString =>
+  typeof i === "string";
+
+export const asString = (i: unknown): CustomString => {
+  if (!isString(i)) {
+    throw new Error("not a custom string");
+  }
+  return i;
+};
+
+export const assertString: (i: unknown) => asserts i is CustomString = (i) => {
+  asString(i);
+};

packages/typedoc-plugin-markdown/test/fixtures/src/utils/brackets.ts

@@ -0,0 +1,16 @@
+export interface InterfaceWithChars<T> {
+  prop: T;
+  '>': string;
+  '<': string;
+  '<tag>': string;
+}
+
+export class ClassWithChars<T> {
+  prop!: T;
+}
+
+export const variableWithChars = {
+  ['<x>']: '>',
+  ['<y>']: '<',
+  ['<z>']: '<tag>',
+};

packages/typedoc-plugin-markdown/test/fixtures/src/utils/constructor-override.ts

@@ -0,0 +1,15 @@
+class LRUCache<T, U, V> {
+  constructor() {}
+}
+
+type CacheFetchContext = {};
+
+export class Cache extends LRUCache<
+  CacheFetchContext,
+  CacheFetchContext,
+  CacheFetchContext
+> {
+  constructor() {
+    super();
+  }
+}

packages/typedoc-plugin-markdown/test/fixtures/src/utils/index-signature.ts

@@ -0,0 +1,9 @@
+type Delimiter = "·";
+
+type Id =
+  | `${"git"}${Delimiter}${string}${Delimiter}${string}`
+  | `${"remote"}${Delimiter}${string}${Delimiter}${string}`;
+
+export type LongIndexSignature = {
+  [key: `${Id} ${string}`]: `${"dev" | "prod"} ${Id}`;
+};

packages/typedoc-plugin-markdown/test/fixtures/src/utils/index.ts renamed to packages/typedoc-plugin-markdown/test/fixtures/src/utils/prettier.ts

@@ -1,20 +1,3 @@
-export interface InterfaceWithChars<T> {
-  prop: T;
-  '>': string;
-  '<': string;
-  '<tag>': string;
-}
-
-export class ClassWithChars<T> {
-  prop!: T;
-}
-
-export const variableWithChars = {
-  ['<x>']: '>',
-  ['<y>']: '<',
-  ['<z>']: '<tag>',
-};
-
 /**
  * ```ts
  * reallyUgly    (

packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.interface.spec.ts.snap

@@ -600,7 +600,7 @@ Comments for IndexableInterface
 
 ## Indexable
 
- \\[\`s\`: \`string\`\\]: \`string\`
+\\[\`s\`: \`string\`\\]: \`string\`
 
 ## Properties
 
@@ -621,7 +621,9 @@ Comments for IndexableInterface
 
 ## Indexable
 
- \\[\`s\`: \`string\`\\]: \`string\`
+\`\`\`ts
+[s: string]: string
+\`\`\`
 
 ## Properties
 
@@ -882,9 +884,9 @@ exports[`Interface Reflection should compile multiple indexable interface: (Outp
 
 ## Indexable
 
- \\[\`key\`: \`string\`\\]: \`string\`
+\\[\`key\`: \`string\`\\]: \`string\`
 
- \\[\`index\`: \`number\`\\]: \`string\`
+\\[\`index\`: \`number\`\\]: \`string\`
 
 ## Properties
 
@@ -905,9 +907,13 @@ exports[`Interface Reflection should compile multiple indexable interface: (Outp
 
 ## Indexable
 
- \\[\`key\`: \`string\`\\]: \`string\`
+\`\`\`ts
+[key: string]: string
+\`\`\`
 
- \\[\`index\`: \`number\`\\]: \`string\`
+\`\`\`ts
+[index: number]: string
+\`\`\`
 
 ## Properties
 

packages/typedoc-plugin-markdown/test/specs/__snapshots__/reflection.type-alias.spec.ts.snap

@@ -612,7 +612,7 @@ Comments for ReadonlyMapedType
 exports[`Type Alias Reflection should compile string literal type: (Output File Strategy "members") (Option Group "1") 1`] = `
 "# Type Alias: StringLiteralType
 
-> **StringLiteralType**: \`" "\` \\| \`"string"\` \\| "string\\|with\\|pipes" \\| "string\\\`with\\\`backticks" \\| \`"<foo>"\` \\| \`"*"\`
+> **StringLiteralType**: \`" "\` \\| \`"string"\` \\| "string\\|with\\|pipes" \\| \`\` "string\`with\`backticks" \`\` \\| \`"<foo>"\` \\| \`"*"\`
 
 Comments for StringLiteralType
 
@@ -751,7 +751,7 @@ Comments for TypeWithReturns
 exports[`Type Alias Reflection should compile union type with template strings: (Output File Strategy "members") (Option Group "1") 1`] = `
 "# Type Alias: UnionTypeWithTemplateStrings
 
-> **UnionTypeWithTemplateStrings**: \\\`v$\\{number\\}\\\` \\| \\\`v$\\{number\\}.$\\{number\\}\\\` \\| \\\`v$\\{number\\}.$\\{number\\}.$\\{number\\}\\\`
+> **UnionTypeWithTemplateStrings**: \`\` \`v\${number}\` \`\` \\| \`\` \`v\${number}.\${number}\` \`\` \\| \`\` \`v\${number}.\${number}.\${number}\` \`\`
 
 Union with template strings
 

packages/typedoc-plugin-markdown/test/specs/__snapshots__/utils.spec.ts.snap

@@ -1,5 +1,91 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`Utils should format index signature type: (Output File Strategy "members") (Option Group "1") 1`] = `
+"# Type Alias: LongIndexSignature
+
+> **LongIndexSignature**: \\{\\}
+
+## Index Signature
+
+\\[\`key\`: \`\` \`git·\${string}·\${string} \${string}\` \`\` \\| \`\` \`remote·\${string}·\${string} \${string}\` \`\`\\]: \`\` \`dev git·\${string}·\${string}\` \`\` \\| \`\` \`dev remote·\${string}·\${string}\` \`\` \\| \`\` \`prod git·\${string}·\${string}\` \`\` \\| \`\` \`prod remote·\${string}·\${string}\` \`\`
+"
+`;
+
+exports[`Utils should format index signature type: (Output File Strategy "members") (Option Group "2") 1`] = `
+"# Type Alias: LongIndexSignature
+
+\`\`\`ts
+type LongIndexSignature = {};
+\`\`\`
+
+## Index Signature
+
+\`\`\`ts
+[key:
+  | \`git·\${string}·\${string} \${string}\`
+  | \`remote·\${string}·\${string} \${string}\`]:
+  | \`dev git·\${string}·\${string}\`
+  | \`dev remote·\${string}·\${string}\`
+  | \`prod git·\${string}·\${string}\`
+  | \`prod remote·\${string}·\${string}\`
+\`\`\`
+"
+`;
+
+exports[`Utils should format type with constructor overrides: (Output File Strategy "members") (Option Group "1") 1`] = `
+"# Class: Cache
+
+## Extends
+
+- \`LRUCache\`<\`CacheFetchContext\`, \`CacheFetchContext\`, \`CacheFetchContext\`>
+
+## Constructors
+
+### new Cache()
+
+> **new Cache**(): [\`Cache\`](Cache.md)
+
+#### Returns
+
+[\`Cache\`](Cache.md)
+
+#### Overrides
+
+\`LRUCache< CacheFetchContext, CacheFetchContext, CacheFetchContext >.constructor\`
+"
+`;
+
+exports[`Utils should format type with constructor overrides: (Output File Strategy "members") (Option Group "2") 1`] = `
+"# Class: Cache
+
+## Extends
+
+- \`LRUCache\`&lt;\`CacheFetchContext\`, \`CacheFetchContext\`, \`CacheFetchContext\`&gt;
+
+## Constructors
+
+### new Cache()
+
+\`\`\`ts
+new Cache(): Cache
+\`\`\`
+
+#### Returns
+
+[\`Cache\`](Cache.md)
+
+#### Overrides
+
+\`\`\`ts
+LRUCache<
+  CacheFetchContext,
+  CacheFetchContext,
+  CacheFetchContext
+>.constructor
+\`\`\`
+"
+`;
+
 exports[`Utils should get class with brackets: (Output File Strategy "members") (Option Group "1") 1`] = `
 "# Class: ClassWithChars&lt;T&gt;