MDX

MDX is a variant of Markdown that compiles to JSX, and supports embedding interactive components inside Markdown documents. Parcel supports MDX out of the box.

Example

You can import a .mdx file into your JavaScript and render it using React:

import Hello from './hello.mdx';

export function App() {
  return <Hello />;
}

# Hello, MDX!

This is an MDX file.

Dependencies

Parcel detects dependency references in MDX files and processes them as well. These references are re-written so that they link to the correct output files. Supported dependencies include:

Links

Links to other pages can be created with the Markdown link syntax or the HTML <a> element.

This is a [link](another-page.mdx).

This is <a href="somewhere.html">another link</a>

Images

Images can be referenced using the Markdown image syntax, HTML <img> element, or <picture>` element. See the HTML docs for more details.

![alt](some-image.jpg)

<img src="another-image.png">

Video, audio, and other assets

The <video>, <audio>, <track>, <embed>, <object>, and <iframe> elements are supported. The referenced URLs are processed by Parcel and rewritten to include a content hash.

Code blocks

Parcel supports customizing how code blocks are rendered by specifying your own CodeBlock component. This allows you to implement syntax highlighting and other features.

import Hello from './hello.mdx';

const components = {CodeBlock};

export function App() {
  return <Hello components={components} />;
}

function CodeBlock({lang, children}) {
  return (
    <pre>
      <code className={lang ? `language-${lang}` : null}>
        {syntaxHighlight(children)}
      </code>
    </pre>
  );
}

function syntaxHighlight() {
  // ...
}

CodeBlock props

Markdown code fences accept arbitrary props, which are parsed as JSX and passed into the CodeBlock component.

```tsx boolean string="hi" number={2}
console.log("hi");
```

The above example compiles to:

<CodeBlock lang="tsx" boolean string="hi" number={2}>
console.log("hi");
</CodeBlock>

Rendering live code examples

Markdown code fences in JavaScript, TypeScript, and CSS support running the code live and rendering the result inline. Set the render prop on the code fence to pass the result of the code block to the <CodeBlock> component. For example:

```tsx render
<div>Hello world!</div>
```

would render

<CodeBlock lang="tsx" render={<div>Hello world!</div>}>
  &lt;div&gt;Hello world!&lt;/div&gt;
</CodeBlock>

The provided CodeBlock component can choose where to display the rendered value. The default implementation renders it after the <pre> element.

<pre>
  <code class="lang-tsx">
    &lt;div&gt;Hello world!&lt;/div&gt;
  </code>
</pre>
<div>Hello world!</div>