mdast-util-mdx-jsx

mdast extension to parse and serialize MDX or MDX.js JSX

Usage no npm install needed!

<script type="module">
  import mdastUtilMdxJsx from 'https://cdn.skypack.dev/mdast-util-mdx-jsx';
</script>

README

mdast-util-mdx-jsx

Build Coverage Downloads Size Sponsors Backers Chat

Extensions to parse and serialize JSX between mdast and markdown.

Contents

What is this?

This package contains extensions that add support for the JSX syntax enabled by MDX to mdast-util-from-markdown and mdast-util-to-markdown.

JSX is an XML-like syntax extension to ECMAScript (JavaScript), which MDX brings to markdown. For more info on MDX, see What is MDX?

When to use this

These tools are all rather low-level. In most cases, you’d want to use remark-mdx with remark instead.

When you are working with syntax trees and want all of MDX, use mdast-util-mdx instead.

When working with mdast-util-from-markdown, you’d want to combine this package with micromark-extension-mdx-jsx.

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

npm install mdast-util-mdx-jsx

In Deno with Skypack:

import {mdxJsxFromMarkdown, mdxJsxToMarkdown} from 'https://cdn.skypack.dev/mdast-util-mdx-jsx@1?dts'

In browsers with Skypack:

<script type="module">
  import {mdxJsxFromMarkdown, mdxJsxToMarkdown} from 'https://cdn.skypack.dev/mdast-util-mdx-jsx@1?min'
</script>

Use

Say our document example.mdx contains:

<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.js 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

This package exports the following identifiers: mdxJsxFromMarkdown, mdxJsxToMarkdown. There is no default export.

mdxJsxFromMarkdown()

Function that can be called to get an extension for mdast-util-from-markdown.

When using micromark-extension-mdx-jsx with options.addResult, nodes will have a data.estree field set to an ESTree.

mdxJsxToMarkdown(options?)

Function that can be called to get an extension for mdast-util-to-markdown.

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

options

Configuration (optional).

options.quote

Preferred quote to use around attribute values ('"' or "'", default: '"').

options.quoteSmart

Use the other quote if that results in less bytes (boolean, default: false).

options.tightSelfClosing

Do not use an extra space when closing self-closing elements: <img/> instead of <img /> (boolean, default: false).

options.printWidth

Try and wrap syntax as this width (number, default: Infinity). When set to a finite number (say, 80), the formatter will print attributes on separate lines when a tag doesn’t fit on one line. The normal behavior is to print attributes with spaces between them instead of line endings.

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

Types

This package is fully typed with TypeScript. It exports the MdxJsxAttributeValueExpression, MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement, and MdxJsxTextElement types that represents the supported nodes. It also exports ToMarkdownOptions, which represents the structure of the respective options.

It also registers the node types with @types/mdast. If you’re working with the syntax tree, make sure to import this plugin somewhere in your types, as that registers the new node types in the tree.

/** @typedef {import('mdast-util-mdx-jsx')} */

import {visit} from 'unist-util-visit'

/** @type {import('mdast').Root} */
const tree = getMdastNodeSomeHow()

visit(tree, (node) => {
  // `node` can now be one of the JSX nodes.
})

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with mdast-util-from-markdown version 1+ and mdast-util-to-markdown version 1+.

Related

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