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();
+  }
+}