rehype-mdx-elements

v1.0.0

Published

6 months ago

**[rehype][]** plugin to convert MDX JSX elements to regular HTML elements.

Downloads

19,260

0High
0Medium
0Low

etler

rehype-mdx-elements

rehype plugin to convert MDX JSX elements to regular HTML elements.

What is this?

This package is a unified (rehype) plugin to convert MDX JSX element nodes to regular HTML elements that can be handled by component mapping.

unified is a project that transforms content with abstract syntax trees (ASTs). rehype adds support for HTML to unified. MDX is markdown that supports JSX. hast is the HTML AST that rehype uses. This is a rehype plugin that transforms MDX JSX elements in the hast.

When should I use this?

This plugin is useful when you want to render arbitrary markdown with custom component support while maintaining security. Unlike full MDX implementations that support JSX expressions and imports, this plugin only processes JSX elements with literal attributes, making it safe for untrusted content.

Use this plugin when you need to:

Render arbitrary markdown with custom components
Preserve case-sensitive component names and attributes
Avoid the security risks of full JSX expression evaluation

Install

This package is ESM only.

npm install rehype-mdx-elements

yarn add rehype-mdx-elements

<script type="module">
  import {rehypeMdxElements} from 'https://esm.sh/rehype-mdx-elements?bundle'
</script>

Use

example.mdx:

# Hello

<Button variant="primary">Click me</Button>

Some text with <Alert type="warning">important info</Alert>.

<script>alert('xss')</script>

example.tsx:

import {readFileSync} from 'node:fs'
import {unified} from 'unified'
import remarkParse from 'remark-parse'
import remarkMdx from 'remark-mdx'
import remarkRehype from 'remark-rehype'
import {rehypeMdxElements} from 'rehype-mdx-elements'
import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
import {Fragment, jsx, jsxs} from 'react/jsx-runtime'
import React from 'react'

// Component definitions
const Button = (props: {variant?: string; children?: React.ReactNode}) => (
  <button className={`btn ${props.variant || 'default'}`}>
    {props.children}
  </button>
)

const Alert = (props: {type?: string; children?: React.ReactNode}) => (
  <div className={`alert alert-${props.type || 'info'}`}>
    {props.children}
  </div>
)

const components = {Button, Alert}

const file = readFileSync('example.mdx')

const processor = unified()
  .use(remarkParse)
  .use(remarkMdx)
  .use(remarkRehype, {passThrough: ['mdxJsxFlowElement', 'mdxJsxTextElement']})
  .use(rehypeMdxElements, {
    allowedElements: Object.keys(components)
  })

const tree = processor.parse(file)
const transformedTree = await processor.run(tree)

// Convert to React elements
const reactElement = toJsxRuntime(transformedTree, {
  Fragment,
  jsx,
  jsxs,
  components
})

console.log(reactElement)

Running example.tsx produces JSX runtime elements with the following content:

<>
  <h1>Hello</h1>
  <Button variant="primary">Click me</Button>
  <p>Some text with <Alert type="warning">important info</Alert>.</p>
</>

API