Document some of the gotchas of MDX

[bourdakos1]

The markdown in OpenAPI definition descriptions is processed by MDX. The results are similar to what would be generated by commonmark, but there are some noticeable differences/gotchas.

What I've come across so far:

• Style attributes must follow the JSX syntax <div style={{ color: "red" }}> vs <div style="color: red;">
• All tags must be closed. For example: Replace <your-name> with your name. will throw an error instead of rendering: Replace with your name..
• Lists can contain html (similar to GitHub flavored markdown), so - Replace <your-name> with your name. will throw an error, because <your-name> will be treaded as html instead of a simple string

Valid commonmark:

List:
- one
- two
- <three>

<div style="background: red; height: 30px; width: 30px;">

Renders:

But the above is invalid MDX and would need to be rewritten as:

List:
- one
- two
- \<three\>

<div style={{ background: "red", height: "30px", width: "30px" }} />