mdast-util-mdx-jsx

What is mdast-util-mdx-jsx?

The mdast-util-mdx-jsx package is a utility for working with MDX (Markdown for the component era) JSX nodes within the mdast (Markdown Abstract Syntax Tree) format. It allows for parsing, manipulating, and serializing MDX JSX nodes in the context of mdast, making it a powerful tool for developers working with MDX content in JavaScript and TypeScript projects.

What are mdast-util-mdx-jsx's main functionalities?

Parsing MDX JSX nodes

This feature allows for the parsing of MDX JSX nodes from a Markdown string. The code sample demonstrates how to use the package in conjunction with `mdast-util-from-markdown` to parse a string containing an MDX JSX component into an mdast syntax tree.

"use strict";

var fromMarkdown = require('mdast-util-from-markdown');
var mdxJsx = require('mdast-util-mdx-jsx');

var doc = '<Button>Click me!</Button>';

var tree = fromMarkdown(doc, {
  extensions: [mdxJsx.fromMarkdown()],
});

console.log(tree);

Serializing MDX JSX nodes

This feature enables the serialization of MDX JSX nodes back into a Markdown string with embedded JSX. The code sample shows how to convert an mdast syntax tree containing an MDX JSX element back into a Markdown string using `mdast-util-to-markdown` with the mdx-jsx extension.

"use strict";

var toMarkdown = require('mdast-util-to-markdown');
var mdxJsx = require('mdast-util-mdx-jsx');

var tree = {
  type: 'root',
  children: [
    {
      type: 'mdxJsxFlowElement',
      name: 'Button',
      children: [{type: 'text', value: 'Click me!'}]
    }
  ]
};

var doc = toMarkdown(tree, {
  extensions: [mdxJsx.toMarkdown()],
});

console.log(doc);

Other packages similar to mdast-util-mdx-jsx

remark-mdx

remark-mdx is a plugin for the remark Markdown processor that adds support for parsing and serializing MDX. It is similar to mdast-util-mdx-jsx in that it deals with MDX content, but it operates within the remark ecosystem, providing a higher-level abstraction compared to the lower-level mdast utilities.

rehype-react

rehype-react is a plugin that allows you to transform rehype (HTML AST) trees to React components. While it operates in a different part of the unified ecosystem, focusing on HTML rather than Markdown, it shares the concept of transforming syntax trees (in this case, HTML ASTs) into JSX components, similar to how mdast-util-mdx-jsx works with MDX JSX nodes.

README

mdast-util-mdx-jsx

Extension for mdast-util-from-markdown and/or mdast-util-to-markdown to support MDX (or MDX.js) JSX. When parsing (from-markdown), must be combined with micromark-extension-mdx-jsx.

This utility handles parsing and serializing. See micromark-extension-mdx-jsx for how the syntax works.

When to use this

Use mdast-util-mdx if you want all of MDX / MDX.js. Use this otherwise.

Install

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm:

npm install mdast-util-mdx-jsx

Use

Say we have an MDX.js file, example.mdx:

<Box>
  - a list
</Box>

<MyComponent {...props} />

<abbr title="Hypertext Markup Language">HTML</abbr> is a lovely language.

And our module, example.js, looks as follows:

import fs from 'node:fs'
import * as acorn from 'acorn'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toMarkdown} from 'mdast-util-to-markdown'
import {mdxJsx} from 'micromark-extension-mdx-jsx'
import {mdxJsxFromMarkdown, mdxJsxToMarkdown} from 'mdast-util-mdx-jsx'

const doc = fs.readFileSync('example.mdx')

const tree = fromMarkdown(doc, {
  extensions: [mdxJsx({acorn: acorn, addResult: true})],
  mdastExtensions: [mdxJsxFromMarkdown]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [mdxJsxToMarkdown]})

console.log(out)

Now, running node example yields (positional info removed for brevity):

{
  type: 'root',
  children: [
    {
      type: 'mdxJsxFlowElement',
      name: 'Box',
      attributes: [],
      children: [
        {
          type: 'list',
          ordered: false,
          start: null,
          spread: false,
          children: [
            {
              type: 'listItem',
              spread: false,
              checked: null,
              children: [
                {type: 'paragraph', children: [{type: 'text', value: 'a list'}]}
              ]
            }
          ]
        }
      ]
    },
    {
      type: 'mdxJsxFlowElement',
      name: 'MyComponent',
      attributes: [
        {
          type: 'mdxJsxExpressionAttribute',
          value: '...props',
          data: {
            estree: {
              type: 'Program',
              body: [
                {
                  type: 'ExpressionStatement',
                  expression: {
                    type: 'ObjectExpression',
                    properties: [
                      {
                        type: 'SpreadElement',
                        argument: {type: 'Identifier', name: 'props'}
                      }
                    ]
                  }
                }
              ],
              sourceType: 'module'
            }
          }
        }
      ],
      children: []
    },
    {
      type: 'paragraph',
      children: [
        {
          type: 'mdxJsxTextElement',
          name: 'abbr',
          attributes: [
            {
              type: 'mdxJsxAttribute',
              name: 'title',
              value: 'Hypertext Markup Language'
            }
          ],
          children: [{type: 'text', value: 'HTML'}]
        },
        {type: 'text', value: ' is a lovely language.'}
      ]
    }
  ]
}

<Box>
  *   a list
</Box>

<MyComponent {...props}/>

<abbr title="Hypertext Markup Language">HTML</abbr> is a lovely language.

API

mdxJsxFromMarkdown

mdxJsxToMarkdown

Support MDX (or MDX.js) JSX. The exports are extensions, respectively for mdast-util-from-markdown and mdast-util-to-markdown.

When using the syntax extension with addResult, nodes will have a data.estree field set to an ESTree.

There are no options, but passing options.quote to mdast-util-to-markdown is honored for attributes.

this extension configures mdast-util-to-markdown with fences: true and resourceLink: true too, do not overwrite them!

Syntax tree

The following interfaces are added to mdast by this utility.

Nodes

MDXJsxFlowElement

interface MDXJsxFlowElement <: Parent {
  type: "mdxJsxFlowElement"
}

MDXJsxFlowElement includes MDXJsxElement

MDXJsxFlowElement (Parent) represents JSX in flow (block). It can be used where flow content is expected. It includes the mixin MDXJsxElement.

For example, the following markdown:

<w x="y">
  z
</w>

Yields:

{
  type: 'mdxJsxFlowElement',
  name: 'w',
  attributes: [{type: 'mdxJsxAttribute', name: 'x', value: 'y'}],
  children: [{type: 'paragraph', children: [{type: 'text', value: 'z'}]}]
}

MDXJsxTextElement

interface MDXJsxTextElement <: Parent {
  type: "mdxJsxTextElement"
}

MDXJsxTextElement includes MDXJsxElement

MDXJsxTextElement (Parent) represents JSX in text (span, inline). It can be used where phrasing content is expected. It includes the mixin MDXJsxElement.

For example, the following markdown:

a <b c>d</b> e.

Yields:

{
  type: 'mdxJsxTextElement',
  name: 'b',
  attributes: [{type: 'mdxJsxAttribute', name: 'c', value: null}],
  children: [{type: 'text', value: 'd'}]
}

Mixin

MDXJsxElement

interface mixin MDXJsxElement {
  name: string?
  attributes: [MDXJsxExpressionAttribute | MDXJsxAttribute]
}

interface MDXJsxExpressionAttribute <: Literal {
  type: "mdxJsxExpressionAttribute"
}

interface MDXJsxAttribute <: Node {
  type: "mdxJsxAttribute"
  name: string
  value: MDXJsxAttributeValueExpression | string?
}

interface MDXJsxAttributeValueExpression <: Literal {
  type: "mdxJsxAttributeValueExpression"
}

MDXJsxElement represents a JSX element.

The name field can be present and represents an identifier. Without name, the element represents a fragment, in which case no attributes must be present.

The attributes field represents information associated with the node. The value of the attributes field is a list of MDXJsxExpressionAttribute and MDXJsxAttribute nodes.

MDXJsxExpressionAttribute represents an expression (typically in a programming language) that when evaluated results in multiple attributes.

MDXJsxAttribute represents a single attribute. The name field must be present. The value field can be present, in which case it is either a string (a static value) or an expression (typically in a programming language) that when evaluated results in an attribute value.

Content model

FlowContent (MDX JSX)

type MDXJsxFlowContent = MDXJsxFlowElement | FlowContent

PhrasingContent (MDX JSX)

type MDXJsxPhrasingContent = MDXJsxTextElement | PhrasingContent

Related

• remarkjs/remark — markdown processor powered by plugins
• remarkjs/remark-mdx — remark plugin to support MDX
• syntax-tree/mdast-util-from-markdown — mdast parser using micromark to create mdast from markdown
• syntax-tree/mdast-util-to-markdown — mdast serializer to create markdown from mdast
• syntax-tree/mdast-util-mdx — mdast utility to support all of MDX
• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• micromark/micromark-extension-mdx-jsx — micromark extension to parse JSX

Contribute

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MIT © Titus Wormer