Embracing the Virtual Reality Web - Beyond 2D Screens

What is MDX?

MDX is a powerful syntax that enables you to incorporate JSX elements, including standard HTML and custom components, within your markdown content. For instance, this MDX input:

// gatsby.config.js
module.exports = {
  plugins: [
    `gatsby-plugin-image`,
    `gatsby-plugin-sharp`,
    `gatsby-transformer-sharp`, // Needed for dynamic images
  ],
}

Will produce the following HTML markup:

<h1>Hello World!</h1>
<p class="lead">This is an introductory paragraph for the article.</p>
<p>This is a standard markdown paragraph.</p>

MDX facilitates a seamless interleaving of JSX and markdown, offering the ultimate authoring experience.

The Problem with JSX in MDX

Using tools such as Prettier to ensure consistent code formatting is common practice. Code formatters like Prettier enforce maximum line lengths by wrapping any JSX elements that exceed the configured print width.

However, MDX expects JSX-only elements to be inline (i.e. have their opening and closing tags on the same line), rather than being blocks spanning multiple lines. If your JSX elements span multiple lines, MDX will treat their content as regular markdown.

In this example, the JSX <p> element has been automatically wrapped by Prettier:

# Hello World!
 
<p className="lead">
  This is a longer introductory paragraph that is automatically wrapped by
  Prettier, or other code formatters.
</p>

The resulting HTML markup created by MDX is invalid, as nested <p> tags are not allowed.

<h1>Hello World!</h1>
<p class="lead">
  <p>This is a longer introductory paragraph that is automatically wrapped by
  Prettier, or other code formatters.</p>
</p>

This behaviour was introduced in MDX Version 2. It is addressed in the migration guide and related GitHub issue.

How to Prevent Unwanted Paragraph Tags

To prevent JSX content from being automatically wrapped as markdown paragraphs, you have a few options:

Use a JavaScript Expression

The recommended approach is to use JavsScript expressions ({}) within your content as an 'escape hatch' to prevent JSX elements from being treated as regular markdown.

You can either wrap the entire JSX block as an expression by surrounding it with curly brackets:

# Hello World!
 
{
  <p className="lead">
    This is a longer introductory paragraph that is automatically wrapped by
    Prettier, or other code formatters.
  </p>
}

Or, wrap just the contents of the element so that MDX treats it as plain text:

# Hello World!
 
<p className="lead">
  {`This is a longer introductory paragraph that is automatically wrapped by
  Prettier, or other code formatters.`}
</p>

See the MDX docs for more details about using JavaScript expressions within MDX.

Disable Automatic Wrapping

An alternative approach is to keep your JSX elements inline by disabling automatic line wrapping in your MDX content, effectively avoiding the creation of multi-line JSX blocks.

If you're using Prettier, prevent code formatting of all files with an .mdx extension by adding this line to your .prettierignore file:

# Ignore all MDX files to prevent unwanted JSX line wrapping
*.mdx

Or by using the inline syntax before any JSX elements that exceed the configured print width:

# Hello World!
 
{/* prettier-ignore */}
<p className="lead">This is a longer introductory paragraph that is automatically wrapped by , or other code formatters.</p>

The inline prettier-ignore syntax may be preferable as it allows you to retain automatic formatting for the rest of your MDX content.

See the Prettier docs for more details about excluding code from formatting.

Create a Custom Component

The final option is to extract your multi-line JSX elements into custom components, like so:

export function MyCustomComponent() {
  return (
    <p className="lead">
      This is a longer introductory paragraph that is automatically wrapped by
      Prettier or other code formatters.
    </p>
  )
}

You can then reference the component within your MDX files without worrying about unwanted <p> tags being added by MDX.

# Hello World!
 
<MyCustomComponent />

This solution is well-suited for complex or reusable components. However, for simpler JSX elements, it may disrupt the flow of authoring MDX content.

Wrapping Up

Working with MDX and JSX can significantly improve your content creation process. However, it's important to be mindful of potential issues in the resulting HTML markup. By using JavaScript expressions, disabling automatic wrapping, or extracting custom components, you can effectively prevent invalid markup and keep your content clean and compliant.

With these strategies, you can fully leverage the potent combination of MDX and JSX to create engaging, rich, and well-structured content for your audience.