Serializing interleaved Markdown in JSX can lead to a few quirks

[johno]

In Gatsby Recipes we wrap blocks of Markdown with JSX tags in a few spots. After manipulating the AST we then serialize back to MDX. This can cause a few quirks.

Consider the following input:

**Success**!

You're ready to get started!

-   Read the docs: [https://theme-ui.com](https://theme-ui.com)
-   Learn about the theme specification: [https://system-ui.com](https://system-ui.com)

_note:_ if you're running this recipe on the default starter (or any other starter with
base css), you'll need to remove the require to `layout.css` in the `components/layout.js` file
as otherwise they'll override some theme-ui styles.

We manipulate the AST and wrap it up like so:

    const wrappedResourceSteps = resourceSteps.map((step, i) => {
      return {
        type: `mdxBlockElement`,
        name: `RecipeStep`,
        attributes: [
          {
            type: `mdxAttribute`,
            name: `step`,
            value: String(i + 1),
          },
          {
            type: `mdxAttribute`,
            name: `totalSteps`,
            value: String(resourceSteps.length),
          },
        ],
        children: step,
      }
    })

We then result in:

<RecipeStep
  step="4"
  totalSteps="4"
>
  **Success**!

  You're ready to get started!

  -   Read the docs: [https://theme-ui.com](https://theme-ui.com)
  -   Learn about the theme specification: [https://system-ui.com](https://system-ui.com)

  _note:_ if you're running this recipe on the default starter (or any other starter with
  base css), you'll need to remove the require to `layout.css` in the `components/layout.js` file
  as otherwise they'll override some theme-ui styles.
</RecipeStep>

The indention of the "note" paragraph below causes it to be parsed as part of the li so we end up with:

    <ul>
      <li {...{
        "parentName": "ul"
      }}>
        <p {...{
          "parentName": "li"
        }}>{`Read the docs: `}
          <a {...{
            "href": "https://theme-ui.com",
            "parentName": "p"
          }}>{`https://theme-ui.com`}</a></p>
      </li>
      <li {...{
        "parentName": "ul"
      }}>
        <p {...{
          "parentName": "li"
        }}>{`Learn about the theme specification: `}
          <a {...{
            "href": "https://system-ui.com",
            "parentName": "p"
          }}>{`https://system-ui.com`}</a></p>
        <p {...{
          "parentName": "li"
        }}><em {...{
            "parentName": "p"
          }}>{`note:`}</em>
          {` if you're running this recipe on the default starter (or any other starter with
base css), you'll need to remove the require to `}
          <inlineCode {...{
            "parentName": "p"
          }}>{`layout.css`}</inlineCode>
          {` in the `}
          <inlineCode {...{
            "parentName": "p"
          }}>{`components/layout.js`}</inlineCode>
          {` file
as otherwise they'll override some theme-ui styles.`}</p>
      </li>
    </ul>

It seems like when we serialize to MDX we will need to dedent block-based Markdown inside JSX tags, otherwise significant whitespace will be injected that might not be intended. Any thoughts on how to best do this @wooorm?

[wooorm]

Pretty cool that the AST and serializing mostly works! 😅

I decided to allow folks to indent (and remove indented code), because I saw a couple of folks doing indents and expecting it to work. Hence, for the serializing, I also applied an indent.
For the second parse, are there any options on? It may be that pedantic: false (default, but gatsby-remark has it on for some reason) or commonmark: true (future) will help here?

[johno]

Yeah! It's pretty robust so far! 🙏 💟

The second parse is using whatever the defaults are for MDX, so the parse => wrap with JSX => serialization => parse produces a different AST in terms of the Markdown content.

You can parse this with remark's default options and get the same thing:

  **Success**!

  You're ready to get started!

  -   Read the docs: [https://theme-ui.com](https://theme-ui.com)
  -   Learn about the theme specification: [https://system-ui.com](https://system-ui.com)

  _note:_ if you're running this recipe on the default starter (or any other starter with
  base css), you'll need to remove the require to `layout.css` in the `components/layout.js` file
  as otherwise they'll override some theme-ui styles.

Perhaps in MDX we should have commonmark on by default? Would that make sense?

[wooorm]

It’s probably a bug in remark somewhere. commonmark: true, pedantic: false, might fix it. Or maybe not haha. micromark would definitely fix it, though!

[wooorm]

Hi all! I’m going to close this as it landed on the main, the (now default) branch we’re using to gear up to the MDX@2 release.

The reason is so that it’s more clear which issues still need to be solved already and don’t require further work.

Expect another next release soonish, which might include it, or maybe it’s already released as a beta!

For more info, see #1041.