mdast-util-mdx

What is mdast-util-mdx?

The mdast-util-mdx npm package is a utility tool designed to work with MDX (Markdown for the component era) and MDAST (Markdown Abstract Syntax Tree). It provides functions to parse and serialize MDX documents, allowing developers to manipulate MDX content programmatically within the unified ecosystem.

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

Parsing MDX

This feature allows the parsing of MDX text into an MDAST format, enabling further manipulation or inspection of the structure.

import { fromMarkdown } from 'mdast-util-mdx';
const mdxText = '# Hello, MDX!';
const mdast = fromMarkdown(mdxText, {extensions: [mdx()] });

Serializing MDX

This feature enables the serialization of an MDAST structure back into a string of MDX, useful for generating MDX files programmatically.

import { toMarkdown } from 'mdast-util-mdx';
const mdast = {type: 'root', children: [{type: 'heading', depth: 1, children: [{type: 'text', value: 'Hello, MDX!'}]}]};
const mdxText = toMarkdown(mdast, {extensions: [mdxToMarkdown()] });

Other packages similar to mdast-util-mdx

remark-mdx

This package is part of the unified ecosystem and is specifically tailored for parsing and compiling MDX files. It is similar to mdast-util-mdx but integrates more closely with the remark ecosystem, providing a more seamless experience when working with Markdown and MDX together.

README

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.

You might instead want to use this package through remark-mdx or remark-mdxjs with remark.

Alternatively, the extensions can be used 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

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:

var fs = require('fs')
var fromMarkdown = require('mdast-util-from-markdown')
var toMarkdown = require('mdast-util-to-markdown')
var syntax = require('micromark-extension-mdxjs')
var mdx = require('mdast-util-mdx')

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

var tree = fromMarkdown(doc, {
  extensions: [syntax()],
  mdastExtensions: [mdx.fromMarkdown]
})

console.log(tree)

var out = toMarkdown(tree, {extensions: [mdx.toMarkdown]})

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'}
            }
          ],
          sourceType: 'module'
        }
      }
    },
    {
      type: 'paragraph',
      children: [{type: 'text', value: 'Here’s an expression:'}]
    },
    {
      type: 'mdxFlowExpression',
      value: '\n1 + 1 /* } */\n',
      data: {
        estree: {
          type: 'BinaryExpression',
          left: {type: 'Literal', value: 1},
          operator: '+',
          right: {type: 'Literal', value: 1}
        }
      }
    },
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'Which you can also put inline: '},
        {
          type: 'mdxTextExpression',
          value: '1+1',
          data: {
            estree: {
              type: 'BinaryExpression',
              left: {type: 'Literal', value: 1},
              operator: '+',
              right: {type: 'Literal', value: 1}
            }
          }
        },
        {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

mdx.fromMarkdown

mdx.toMarkdown

Note: the separate extensions are also available at mdast-util-mdx/from-markdown and mdast-util-mdx/to-markdown.

Support MDX (or MDX.js). The exports of fromMarkdown is an extension for mdast-util-from-markdown. The export of toMarkdown is an extension for mdast-util-to-markdown.

There are no options.

Related

• remarkjs/remark — markdown processor powered by plugins
• remarkjs/remark-mdx — remark plugin to support MDX
• remarkjs/remark-mdxjs — remark plugin to support 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