RFC: Interleaving Markdown in JSX

[johno]

Summary

Interleaving Markdown and JSX in MDX has been asked for by a lot of folks and is something we should officially support. It's been on the roadmap, but we've decided to add it as a minor version after v1. Now is that time 😸

It's a common need to wrap a block of content to achieve things like image + captions, notifs, callouts, and custom background/text colors for given sections.

Basic (proposed) example

Inline JSX blocks are automatically interleaved and block-level JSX requires an blank lines to open back up Markdown parsing:

# Hello, <span>*world*</span>, from <>{props.name}</>!

<Note>

This *is* **markdown**!

</Note>

Output JSX

<MDXLayout
  {...layoutProps}
  {...props}
  components={components}
  mdxType="MDXLayout"
>
  <h1>
    {`Hello, `}
    <span>
      <em parentName="h1">{`world`}</em>
    </span>
    {`, from `}
    <>{props.name}</>
    {`!`}
  </h1>
  <Note mdxType="Note">
    <p>
      {`This `}
      <em parentName="p">{`is`}</em>
      {` `}
      <strong parentName="p">{`markdown`}</strong>
      {`!`}
    </p>
  </Note>
</MDXLayout>

Motivation

This approach is currently being used in the wild and in production. As @jxnblk mentioned previously this approach comes with the benefit that it's in the Commonmark Spec.

• https://spec.commonmark.org/0.29/#example-136
• https://spec.commonmark.org/0.29/#example-137

Detailed design

The majority of parsing is already implemented. However, there are a few things we need to be able to address.

Handling embedded expressions {props.foo}

There are two additional scenarios where we need to be able to handle embedded expressions, which all essentially boil down to inline JSX.

# Hello, from <>{props.name}</>

<Note>

Here's another expression: <>{props.thing}</>

</Note>

This can get a bit tricky because technically the following should also be handled:

# Hello, <>from {props.name}</>

Handling more complex JSX blocks

When there is indented JSX across two lines the parser currently misses it. Something that doesn't currently work, but should:

# Hello, world!

<div>
  <div>

# I should be an h1 inside two divs

  </div>
<div>

Drawbacks

This will likely make the last JSX block parsing issue more difficult. The biggest remaining block issue is where we have empty lines in the JSX. This causes parsing breakages for render props and template strings.

Render props

# Hello, world

<SomeComponent>
  {prop => {
    const newValue = doStuff(prop)

    return <h1>{newValue}</h1>
  }}
</SomeComponent>

Template strings

# Hello, world!

<SomeComponent
  someProp={`
    Here's a template string

    with empty lines
  `}
/>

Alternatives

The other main alternative we've considered is an MDX component.

# Hello, <span><MDX>*world*</MDX></span>!

<Note>
  <MDX>
    This *is* **markdown**!
  </MDX>
</Note>

An additional alternative from PHP Markdown Extra is using a markdown attribute:

# Hello, <span markdown="1">*world*</span>!

<Note markdown="1">
  This *is* **markdown**!
</Note>

This comes with the benefit of being more explicit, but it is confusing for folks coming from traditional Markdown as they slowly adopt JSX. It also feels syntactically noisy.

I've toyed with different syntax in place of MDX like aliasing it to something terser: <_>. However, this isn't as approachable.

Adoption strategy

Considering this already mostly works and is already being used (just not officially supported) the adoption strategy should be straightforward. We'd need to fix some parsing edge cases mentioned above and add documentation.

Related issues

• 🏗 Improve JSX block parsing #195
• Transclusion of _inline_ markdown? #241
• Use babel-parse for import/export/jsx blocks #345
• Can't access props with inline JSX #556
• ... and many more 😆

---

cc/ @wooorm @jxnblk @ChristopherBiscardi @timneutkens @ChristianMurphy @silvenon

[ChristopherBiscardi]

It's probably worth mentioning at the beginning what the output of span/world should be as fragments are mentioned later for interpolation but not for interleaving

# Hello, <span>*world*</span>!

<Note>

This *is* **markdown**!

</Note>

[silvenon]

What should happen in this case?

# Hello, <>from {props.name}</>

It feels to me that if this worked, this should work as well:

# Hello from {props.name}

These things are hard 😓

[johno]

What should happen in this case?

# Hello, <>from {props.name}</>

Yeahhh, good point. I wonder if we should only allow embedded expressions to be the only "children" in a JSX block (whether inline or block - <>{props.name}</>)? That would make the parsing easier for the render props case, too. 🤔

[silvenon]

Yeah, I think that would be a win-win because it wouldn't be syntactically misleading.

[rchrdnsh]

would my use case in this issue:

#474

...be solved by this kind of feature? I realized that I'm really wanting to wrap different lists in different styles, but still write the lists in markdown, but then include jsx in the markdown, like so:

<ListStyleOne>

  -  Thing
      -  Subthing and this word is <Red>Red</Red> right here.
      -  Another subthing with a <Blue>colorful</Blue> word again.

</ListStyleOne>

it seems like this is the case initially, but I just want to be sure that I'm understanding this proposal correctly XD

[johno]

would my use case in this issue:

#474

...be solved by this kind of feature? I realized that I'm really wanting to wrap different lists in different styles, but still write the lists in markdown, but then include jsx in the markdown

It would 😄

[rchrdnsh]

noice :-)

[wooorm]

This looks good! I think it makes sense for users. But there’s still some parser problems. Here goes a few more questions and random thoughts.

• block-level JSX requires an empty newline

  To make sure we’re on the same page: I think you mean a blank line, namely two newlines (\n\n), optionally with white space (as defined by CM: https://spec.commonmark.org/0.29/#blank-lines). A newline is a carriage return and/or line feed. And line feed / carriage return are the unix / windows characters!

• The first example:

  # Hello, <span>*world*</span>, from <>{props.name</>!

  Turns into (zooming into world):

  <span>
    <em parentName="h1">{`world`}</em>
  </span>

  …is parentName indeed h1? 🤔
  P.S. props.name misses a closing curly brace

• I don’t think # Hello from {props.name} should be supported (@silvenon). Users are already learning that < and > need to be there to be in JSX. However, implementing it everywhere is easier than only inside inline JSX.

• I think <>from {props.name}</> shouldn’t be too tricky. We start out with Markdown. If </> or other JSX is found, either inline or block level JSX is entered. We add a new inline tokenizer to remark that only works “in” JSX. This means we need to match open and closing tags for inline JSX though, but that’s doable. As {} are not used in “normal” Markdown, we could just as well support it everywhere though.

Drawbacks

Interesting insights: MDX in JSX blocks in MDX is typically not indented, and needs two blank lines. I think that’s too fragile to depend on though. 🤔

[rsexton404]

Would it make the parsing more explicit if the JSX block included a markdown prop/attribute? There's prior art here from PHP Markdown Extra that is worth reviewing.

[johno]

Thanks for the thoughts @wooorm! I've addressed a few things in edits to the original comment.

…is parentName indeed h1?

Yeah I think this is something we'll need to also address since, you're right, it isn't 😆.

Would it make the parsing more explicit if the JSX block included a markdown prop/attribute? There's prior art here from PHP Markdown Extra that is worth reviewing.

Thanks for pointing this out @rsexton404! I've added it as an alternative in the comment. It'd definitely make parsing easier due to it's explicitness, but it's also a bit noisy. I'll need to think on that one!