[api-documenter] Do not escape Markdown in doc comments

[markus-incisive]

Summary

Most Markdown in the doc comments is escaped, which causes unexpected/unwanted/inconsistent behavior. VSCode allows for Markdown and renders it as expected, but api-documenter doesn't.

Repro steps

Given the following class:

/**
 * I am **bold**.
 *
 * @public
 */
export class MyClass {}

VSCode will render the markdown, but api-documenter emits it with the Markdown escaped as "I am **bold**".

Putting a backslash in front of the Markdown characters works for VSCode, but only sometimes works with api-documenter. This example throws a tsdoc-unnecessary-backslash warning.

/**
 * I am \_not italic\_.
 *
 * @public
 */
export class MyClass {}

One way to get api-documenter to format text is to use HTML tags, but VSCode will not render HTML tags.

/**
 * I should be <b>bold</b>.
 *
 * @public
 */
export class MyClass {}

Details

There doesn't seem to be a way to get both VSCode and api-documenter to both render formatted text. This applies to @example and @remarks blocks as well.

I expected api-documenter to support Markdown in doc comments, and leave it to the user to write proper Markdown (explicitly escaping when needed). This behavior could be turned on via an option, since there may still be situations to disallow Markdown in doc comments especially depending on the intended documentation target.

• Code and code blocks are supported by both VSCode and api-documenter
  • Note: api-documenter only supports code marked with exactly 1 (`) or 3 (```) backticks, and won't for example support ``this `code` has a backtick`` (Warning: tsdoc-code-span-empty).
• api-documenter will escape asterisks (*), underscores (_), and headers (#); while VSCode renders them as Markdown when applicable.
• VSCode allows escaping asterisks (*), underscores (_), and headers (#); while api-documenter doesn't nothing different for escaped characters except throwing for escaped underscores.

Standard questions

Please answer these questions to help us investigate your issue more quickly:

Question	Answer
@microsoft/api-documenter version?	7.25.14
Operating system?	Windows
Documentation target?	Markdown
Would you consider contributing a PR?	No
TypeScript compiler version?	5.4.2
Node.js version (node -v)?	22.7.0

[markus-incisive]

May just be a TSDoc issue microsoft/tsdoc#12