MDX

This guide will help you understand how to use MDX with renoun.

What is MDX?

MDX is a format that allows you to write JSX directly within Markdown documents. This lets you embed React components and JSX elements inside your Markdown files, creating interactive and dynamic content. MDX works seamlessly with renoun, making it a powerful tool for your documentation needs.

MDXContent component

The easiest way to get started using MDX with renoun is with the MDXContent component:

import { MDXContent } from 'renoun/components'

const content = `
# Hello, world!

This is an MDX file.
`

export default function Page() {
  return <MDXContent value={content} />
}

In this example, the MDXContent component renders a string of MDX content within your React components. It parses the MDX and converts it into React components that can be rendered in your application.

MDX with Next.js

If you’re working with Next.js, configuring MDX with renoun is straightforward. We have a dedicated guide that walks you through the process of setting it up with your Next.js project.

To learn how to configure MDX with Next.js, check out the Next.js Guide.

Pre-configured Plugins

The renoun/mdx import includes pre-configured plugins for both remark and rehype, which are part the MDX process that parses and transforms MDX content.

You can import these respective plugins and add them to your MDX configuration to extend the functionality of your MDX content.

import { remarkPlugins, rehypePlugins } from 'renoun/mdx'

Here’s a list of the plugins and their effects:

Community Plugins

remark-gfm

Adds support for GitHub Flavored Markdown (GFM) to MDX.

  • Enables strikethrough, tables, task lists, and URLs directly in MDX.
  • Enhances the readability and functionality of markdown content.

remark-frontmatter

Parses front matter from MDX files which is useful for adding metadata to your documents.

remark-mdx-frontmatter

Converts the parsed front matter from remark-frontmatter to an exported frontmatter variable.

remark-smartypants

Transforms punctuation in MDX to typographically correct symbols using SmartyPants.

  • Straight quotes ( " and ' ) into “curly” quote HTML entities
  • Dashes ( -- and --- ) into en- (–) and em-dash (—) entities
  • Three consecutive dots ( ... ) into an ellipsis entity …

remark-strip-badges

Strips out badges, which are often used in README files.

remark-squeeze-paragraphs

Cleans up the document by removing unnecessary empty paragraphs which can be caused by packages like remark-strip-badges.

rehype-infer-reading-time-meta

Infers reading time metadata for MDX content.

rehype-unwrap-images

Ensures that images are not wrapped in paragraph tags.

renoun plugins

In addition to the community plugins listed above, renoun adds specific custom plugins to further extend the capabilities of MDX content.

remark add-headings

Adds an id to all headings and exports a headings variable.

remark remove-immediate-paragraphs

Removes paragraph elements added around immediate element and component children.

For example, when using elements like div, this will remove the paragraph element added around the text content:

<div>
  An example of using a longer sentence in an element that when formatted by
  tools like Prettier will be moved to a new line.
</div>

If you’d like MDX to still wrap the text contents in a paragraph element, you can use a line break before and after the content like so:

<div>

By adding a line break before and after the content, MDX will now wrap this text in a paragraph element.

</div>

Reformats all relative links that use ordered numbers and extensions. For example, ./01.introduction.mdx will be transformed to ./introduction.

rehype add-code-meta-props

Parses CodeBlock and CodeInline props and adds them to pre and code element properties respectively.

rehype add-reading-time

Exports the reading time metadata added by rehype-infer-reading-time-meta as a readingTime variable.

Applying plugins

After installing the package, you can import and apply the plugins to the MDXContent component or any other MDX configuration in your application.

We’ll use the example from before and add the renoun/mdx plugins to the MDXContent component:

import { MDXContent } from 'renoun/components'
import { remarkPlugins, rehypePlugins } from 'renoun/mdx'

const content = `
---
title: Hello, world!
---

# Hello, world!

This is an MDX file.
`

export default function Page() {
  return (
    <MDXContent
      remarkPlugins={remarkPlugins}
      rehypePlugins={rehypePlugins}
      value={content}
    />
  )
}

Now we can utilize plugins like remark-frontmatter to specify front matter in our MDX content. By adding remarkPlugins and rehypePlugins, you can modify how MDX is parsed and rendered, enabling additional functionality in your components.

Conclusion

MDX is a powerful tool that can be used to create interactive and dynamic content in your documentation. By using the MDXContent component and custom plugins, you can easily render MDX content in your components and extend the functionality of the MDX rendering process.

Last updated