[api-extractor] Containers (`:::`) should retain formatting

[davej]

Summary

Using a comment like this, I would expect the admonition contain to retain formatting.

/**
 * :::admonition type="info"
 * Works on **all platforms**
 * :::
 */

Instead the new lines are lost and the container appears all on one line:

* :::admonition type=\"info\" Works on **all platforms** :::

When this eventually gets output to Markdown then it is not rendered correctly. Is there a way that I can either force a new line or force formatting to be retained?

Question	Answer
@microsoft/api-extractor version?	7.16.1
Operating system?	macOS 12.3
API Extractor scenario?	docs (.api.json)
Would you consider contributing a PR?	Yes
TypeScript compiler version?	4.5.5
Node.js version (node -v)?	16.14.2

[octogonz]

:::admonition is not valid TSDoc. See https://tsdoc.org for rationale why we don't support arbitrary proprietary syntaxes.

The recommendation would be to represent this as an HTML tag (<admonition type="info">) and then transform it in your documentation pipeline.

[davej]

Thank you @octogonz, that makes sense.

Is there an existing mechanism for parsing and transforming HTML tags? Is there a file in api-documenter that I can edit? Or are you suggesting that I create my own parser of the markdown files after api-documenter has spit them out?

[octogonz]

It would be helpful to know a little more about your usage and documentation pipeline. The :::admonition markup for example, where is this syntax defined? What tool is processing it?

[davej]

Sure. The markdown files are eventually being used by Svelte KitDocs. See here for where the :::admonition markup comes from: https://kit-docs.svelteness.dev/docs/markdown/extensions#admonitions

So, the current flow looks like this:

1. api-extractor extracts comments from a typescript API and converts it to api.json.
2. api-documenter then takes that JSON and converts it to markdown.
3. Svelte KitDocs uses the markdown that it is output api-documenter to compile an online documentation site.

Happy to go into detail on any of those steps if it's helpful.

[davej]

@octogonz just pinging to see if you have an idea about where is the best place to insert this functionality in my pipeline. Let me know if there is a better place that I should be asking this.