mdast-util-mdx

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

When to use this

Use this if you’re dealing with the AST manually and want to support all of MDX. You can also use the extensions separately:

• mdast-util-mdx-expression — support MDX (or MDX.js) expressions
• mdast-util-mdx-jsx — support MDX (or MDX.js) JSX
• mdast-util-mdxjs-esm — support MDX.js ESM

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

Use

Say we have the following file, example.mdx:

import Box from "place"

Here’s an expression:

{
  1 + 1 /* } */
}

Which you can also put inline: {1+1}.

<Box>
  <SmallerBox>
    - Lists, which can be indented.
  </SmallerBox>
</Box>

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

import fs from 'node:fs'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toMarkdown} from 'mdast-util-to-markdown'
import {mdxjs} from 'micromark-extension-mdxjs'
import {mdxFromMarkdown, mdxToMarkdown} from 'mdast-util-mdx'

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

const tree = fromMarkdown(doc, {
  extensions: [mdxjs()],
  mdastExtensions: [mdxFromMarkdown]
})

console.log(tree)

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

console.log(out)

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

{
  type: 'root',
  children: [
    {
      type: 'mdxjsEsm',
      value: 'import Box from "place"',
      data: {
        estree: {
          type: 'Program',
          body: [
            {
              type: 'ImportDeclaration',
              specifiers: [
                {
                  type: 'ImportDefaultSpecifier',
                  local: {type: 'Identifier', name: 'Box'}
                }
              ],
              source: {type: 'Literal', value: 'place', raw: '"place"'}
            }
          ],
          sourceType: 'module'
        }
      }
    },
    {
      type: 'paragraph',
      children: [{type: 'text', value: 'Here’s an expression:'}]
    },
    {
      type: 'mdxFlowExpression',
      value: '\n1 + 1 /* } */\n',
      data: {
        estree: {
          type: 'Program',
          body: [
            {
              type: 'ExpressionStatement',
              expression: {
                type: 'BinaryExpression',
                left: {type: 'Literal', value: 1, raw: '1'},
                operator: '+',
                right: {type: 'Literal', value: 1, raw: '1'}
              }
            }
          ],
          sourceType: 'module'
        }
      }
    },
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'Which you can also put inline: '},
        {
          type: 'mdxTextExpression',
          value: '1+1',
          data: {
            estree: {
              type: 'Program',
              body: [
                {
                  type: 'ExpressionStatement',
                  expression: {
                    type: 'BinaryExpression',
                    left: {type: 'Literal', value: 1, raw: '1'},
                    operator: '+',
                    right: {type: 'Literal', value: 1, raw: '1'}
                  }
                }
              ],
              sourceType: 'module'
            }
          }
        },
        {type: 'text', value: '.'}
      ]
    },
    {
      type: 'mdxJsxFlowElement',
      name: 'Box',
      attributes: [],
      children: [
        {
          type: 'mdxJsxFlowElement',
          name: 'SmallerBox',
          attributes: [],
          children: [
            {
              type: 'list',
              ordered: false,
              start: null,
              spread: false,
              children: [
                {
                  type: 'listItem',
                  spread: false,
                  checked: null,
                  children: [
                    {
                      type: 'paragraph',
                      children: [
                        {type: 'text', value: 'Lists, which can be indented.'}
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

import Box from "place"

Here’s an expression:

{
  1 + 1 /* } */
}

Which you can also put inline: {1+1}.

<Box>
  <SmallerBox>
    *   Lists, which can be indented.
  </SmallerBox>
</Box>

API

This package exports the following identifier: mdxFromMarkdown, mdxToMarkdown. There is no default export.

mdxFromMarkdown

mdxToMarkdown

Support MDX (or MDX.js). The exports are respectively an extension for mdast-util-from-markdown and mdast-util-to-markdown.

There are no options.

Related

• remarkjs/remark — markdown processor powered by plugins
• remarkjs/remark-mdx — remark plugin to support MDX (or MDX.js)
• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• micromark/micromark-extension-mdx — micromark extension to parse MDX
• micromark/micromark-extension-mdxjs — micromark extension to parse MDX.js
• 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

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