Status of support for various Markdown constructs

[wereHamster]

I tried to use markdown list syntax but that's being parsed as a normal string. What I originally wanted to do is use a list and then use @link inside that list, eg:

/**
 * suummary section here, followed by a list
 *
 *  - {@link Card | `<Card>`} use this
 *  - {@link Masonry | `<Masonry>`} or that
 */

Is markdown support limited to links or does markdown support mean all standard markdown elements such as headings, paragraphs, lists, code blocks etc.

[octogonz]

Good question! Here's a quick summary of the status:

Markdown feature	Support	HTML workaround	Notes
code spans	implemented	<code></code>
fenced code	implemented	<code></code>	We also support syntax highlighters
HTML tags	implemented		Today TSDoc's AST represents individual opening/closing elements. Very soon we're going to have it parse the full tree and report mismatched tags.
Escapes	partially supported		As part of the spec process, we need to specify rigorous escape mechanisms at each layer of the onion skin for JSDoc, Markdown, HTML, and their constituent parts.
bold/italics	planned	<b></b>	This is a trickier aspect of the spec, due to TSDoc's goal of output being predictable without access to an interactive renderer. Markdown * characters have tons of counterintuitive edge cases.
lists	planned	<ul></ul>	This is an easy work item, so we could implement it soon if someone wants it
thematic breaks	unsupported	<hr/>
images	unsupported
(Markdown) links	unsupported		Use {@link} instead of Markdown links. For special link types, use an HTML element.
block quotes	unsupported	<blockquote></blockquote>
headings	unsupported	<h2></h2l>	When I tried this, I found that it tends to interfere with the documentation system's own page layout. Feel free to open an issue if you disagree with that decision.
pipe-and-dash tables	unsupported	<table></table>	We're not planning to support GitHub tables because CommonMark doesn't support them either. We will recommend to use HTML for making tables (and any nesting construct).
nesting (e.g. fenced code inside a blockquote inside a list item)	unsupported		This position is outlined in RFC https://github.com/microsoft/tsdoc/issues/29

Community feedback is welcome.

[DylanVann]

I'm interested in lists. Maybe I opened this on the wrong repo: https://github.com/microsoft/web-build-tools/issues/1441

[octogonz]

No, it definitely needs to be supported by the TSDoc parser first, then API Documenter can add support for rendering it.

Could you open a separate TSDoc issue asking for lists specifically? That will make this easier to track, since this issue is "general discussion" not "enhancement"

[DylanVann]

Sure, here's one: https://github.com/microsoft/tsdoc/issues/178

[sergeych]

btw where are tables? there is mention about itm but apparently no support form markdown tables. its actually a pain sometimes.

[Gerrit0]

From the table Octogonz posted above:

pipe-and-dash tables | unsupported | <table></table>| We're not planning to support GitHub tables because CommonMark doesn't support them either. We will recommend to use HTML for making tables (and any nesting construct).