[api-documenter] formatting with markdown or HTML

[stropho]

Please prefix the issue title with the project name i.e. [rush], [api-extractor] etc.

Is this a feature or a bug?

• Feature
• Bug
  🤷‍♂️

Please describe the actual behavior.
My problem arose when I wanted to make a list of items in TSDoc. Eventually, I found that the formatting capabilities are not very consistent. Let's consider the following example

/**
 *
 * - md list item 1
 * - md list item 2
 *
 * <ul>
 * <li>list item 1</li>
 * <li>list item 2</li>
 * </ul>

 * # md header
 * <h2>header h2<h2>
 * <h5>header h5<h5>
 * <header>header</header>
 *
 * **md bold** <b>html bold</b>
 */

the content of doc model looks like

{ 
// ...
"docComment": `/**
 * - md list item 1 - md list item 2
 *
 * <ul> <li>list item 1</li> <li>list item 2</li> </ul>
 *
 * # md header <h2>header h2<h2> <h5>header h5<h5> <header>header</header>
 *
 * **md bold** <b>html bold</b>
 *
 */
` // ...
}

This means that everything which is not separated by an empty line, gets inlined. That seems pretty straight forward. However it breaks the list created with dashes, i.e. - md list item . As mentioned in #1441 and microsoft/tsdoc#178

So here I thought: ok, let's use html for everything. The TSDoc in not going to look great but the result might be worth it. When running the api-documenter to generate markdown, we get

- md list item 1 - md list item 2

<ul> <li>list item 1</li> <li>list item 2</li> </ul>

\# md header &lt;<!-- -->h2<!-- -->&gt;<!-- -->header h2<!-- -->&lt;<!-- -->h2<!-- -->&gt; &lt;<!-- -->h5<!-- -->&gt;<!-- -->header h5<!-- -->&lt;<!-- -->h5<!-- -->&gt; <header>header</header>

\*\*md bold\*\* <b>html bold</b>

🤔 All of the markdown , except the inlined list items, got escaped. HTML mostly stayed, but <h2> tags and similar got escaped as well.

Are there any decisions behind this? Maybe mentioning the behaviour in the documentation could help somebody...
Or is this something nobody has faced before?

FYI, using

    "@microsoft/api-documenter": "^7.7.13",
    "@microsoft/api-extractor": "^7.7.9",

[octogonz]

@stropho When I paste your TSDoc into the TSDoc Playground, it is reporting tsdoc-malformed-html-name for <h2>.

That's a high priority TSDoc parser bug. We should get that fixed.

If you'd like to open an issue about <h2> in the TSDoc repo, that would be helpful. I'll try to make a PR asap.

[octogonz]

Here's a PR: microsoft/tsdoc#225

[octogonz]

The HTML parsing fix was released with API Extractor 7.7.11.

The other issues in this thread are being tracked by microsoft/tsdoc#169 and related issues such as microsoft/tsdoc#178 and #1441

Those issues have been open for a long time, but we haven't forgotten about them. (For faster progress, you can always click this button.) 😇