Importing .mdx file and passing in props not working correctly

[brownieboy]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

As per https://docusaurus.io/docs/markdown-features/react, I'm trying to import and .mdx file into another .mdx file, and have the host .mdx pass props to the one that its importing. Here's the syntax, from the page to which I just linked

_markdown-partial-example.mdx

<span>Hello {props.name}</span>

This is text some content from _markdown-partial-example.mdx

import PartialExample from './_markdown-partial-example.mdx';

<PartialExample name="Sebastien" />;

I can get it to insert the variable text but if only I insert at the start of a paragraph of markdown, or preferably, on a line all of its own.

Steps to reproduce

Code example, extended from new.docusaurus.io, is here: https://codesandbox.io/s/infallible-davinci-276im

When then example renders:

1. click on the Docusaurus Tutorial button
2. navigate to Tutorial Intro -> create-a-document page
3. Scroll down to the Props variables testing section

This will show you how and when the prop variable renders.

The file docs/tutorial-basics/create-a-document.md is the one that imports the shared doc and passes in the myVariable prop to it. The file is just a few lines.

The file docs/shared-docs-test/_create-a-document.mdx is the file that is imported and which as the props passed to it.

Expected behaviour

We should be able to do a prop variable anywhere within the text of an imported .mdx file. It should render its value, and without messing up any surrounding formatting.

It seems to work okay in standalone .mdx, i.e. no docusaurus, see https://codesandbox.io/s/peaceful-bogdan-fceb9

Actual behaviour

A <>{props.name}<> doesn't work at all if its intermingled with other text before and after it. It only works at the start of a paragraph, although subsequent insertions within that paragraph will also work as long the paragraph starts off with another insertion. If the insertion is only in the middle of the paragraph somewhere, then you will see the underlying code instead of the rendered text.

Even when it does work, it messes up markdown elsewhere in the same paragraph, e.g. any markdown links will not get rendered to HTML anchors tags under the covers. Also, it will lose the paragraphs at the end, which I worked around by hard-coding <br /> tags.

Your environment

• Public source code: https://codesandbox.io/s/infallible-davinci-276im
• Public site URL: https://codesandbox.io/s/infallible-davinci-276im
• Docusaurus version used: Tested against main branch of main repo, cloned on 9 Dec 2021 when testing locally.
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Chrome 96.0.4664.45 (also latest Firefox). Node 14.18.1. Also tested on Codebox extending template from new.docusaurus.io
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Windows 10, running WSL (Ubuntu 20.04.3 LTS)

Reproducible demo

https://codesandbox.io/s/infallible-davinci-276im

Self-service

• I'd be willing to fix this bug myself.

[Josh-Cena]

Hi, this is an MDX issue, that JSX and MD don't interoperate well. This has been fixed in MDX v2, which we are actively attempting to upgrade to: #4029.

You can try the code on the playground: https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/ (this is the v1 one)

In v1, once you use JSX on one line, this paragraph has to be JSX throughout. Putting it at the beginning works because that makes MDX treat the paragraph as one JSX fragment. Instead of this:

Now we don't start the paragraph off with the props variable, but only have one further into the text <b>{'hey'}</b>.  This time it fails to render at all, and you see the underlying code.

Try this:

<p>Now we don't start the paragraph off with the props variable, but only have one further into the text <b>{'hey'}</b>.  This time it fails to render at all, and you see the underlying code.</p>

And instead of:

<b>{props.myVariable}</b> at the start of line again with a markdown link to [Disney home](https://www.disney.com).  The link fails to render to an anchor tag under the covers and you see the actual markdown.

Try:

<b>{props.myVariable}</b> at the start of line again with a markdown link to <a href="https://www.disney.com">Disney home</a>.  The link fails to render to an anchor tag under the covers and you see the actual markdown.

[brownieboy]

@Josh-Cena ,

Thank you for that very prompt and informative response.

Million dollar question then: do you have an ETA for MDX 2 support in Docusaurus?

[Josh-Cena]

Million dollar question then: do you have an ETA for MDX 2 support in Docusaurus?

That's hard to say. A big problem with MDX v2 is that it's ESM-only. If you have some knowledge of the Node ecosystem you know the pain of migrating to ESM (see #5816). We would likely postpone ESM till Docusaurus v3, and for the v2 official release, we will consider the possibility of transpiling their packages to CJS and re-release it for our own use.

With that said, it would probably not be in a few months (this year's last release would be this week). It's end of the year and people are slackin' off. Though I don't celebrate Christmas, I imagine a lot of people taking a break. Maybe after February because I would be relaxing a little during Chinese Spring Festival if no one else is picking it up.