Tsdoc: 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).