mdast-util-mdx-expression

What is mdast-util-mdx-expression?

The `mdast-util-mdx-expression` package is a utility for working with MDX (Markdown with JSX) expressions within the MDAST (Markdown Abstract Syntax Tree) format. It provides tools to parse, transform, and stringify MDX expressions embedded in Markdown documents.

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

Parsing MDX Expressions

This feature allows you to parse MDX expressions from a Markdown string into an MDAST tree. The code sample demonstrates how to parse a simple MDX expression.

const { fromMarkdown } = require('mdast-util-mdx-expression');
const mdxExpression = 'const x = 42;';
const tree = fromMarkdown(mdxExpression);
console.log(tree);

Stringifying MDX Expressions

This feature allows you to convert an MDAST tree containing MDX expressions back into a Markdown string. The code sample demonstrates how to stringify a simple MDX expression.

const { toMarkdown } = require('mdast-util-mdx-expression');
const tree = {
  type: 'mdxFlowExpression',
  value: 'const x = 42;'
};
const markdown = toMarkdown(tree);
console.log(markdown);

Transforming MDAST Trees

This feature allows you to traverse and transform MDAST trees containing MDX expressions. The code sample demonstrates how to visit and modify an MDX expression within an MDAST tree.

const { visit } = require('unist-util-visit');
const { fromMarkdown, toMarkdown } = require('mdast-util-mdx-expression');
const mdxExpression = 'const x = 42;';
const tree = fromMarkdown(mdxExpression);
visit(tree, 'mdxFlowExpression', node => {
  node.value = 'const y = 24;';
});
const newMarkdown = toMarkdown(tree);
console.log(newMarkdown);

Other packages similar to mdast-util-mdx-expression

remark-mdx

The `remark-mdx` package is a plugin for the `remark` ecosystem that enables parsing and transforming MDX content. It provides similar functionality to `mdast-util-mdx-expression` but is more integrated into the `remark` processing pipeline.

README

mdast-util-mdx-expression

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

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

You probably should use either micromark-extension-mdx with mdast-util-mdx or micromark-extension-mdxjs with mdast-util-mdxjs (which both include this package) to support all of MDX or MDX.js. Or use it all through remark-mdx or remark-mdxjs (remark).

Install

npm:

npm install mdast-util-mdx-expression

Use

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

{
  a + 1
}

b {true}.

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

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

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

var tree = fromMarkdown(doc, {
  extensions: [syntax({acorn: acorn, addResult: true})],
  mdastExtensions: [mdxExpression.fromMarkdown]
})

console.log(tree)

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

console.log(out)

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

{
  type: 'root',
  children: [
    {
      type: 'mdxFlowExpression',
      value: '\na + 1\n',
      data: {
        estree: {
          type: 'BinaryExpression',
          left: {type: 'Identifier', name: 'a'},
          operator: '+',
          right: {type: 'Literal', value: 1}
        }
      }
    },
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'b '},
        {
          type: 'mdxTextExpression',
          value: 'true',
          data: {
            estree: {type: 'Literal', value: true}
          }
        },
        {type: 'text', value: '.'}
      ]
    }
  ]
}

{
  a + 1
}

b {true}.

API

mdxExpression.fromMarkdown

mdxExpression.toMarkdown

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

Support expressions in MDX or MDX.js. 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.

The indent of the value of MDXFlowExpressions is stripped.

Syntax tree

The following interfaces are added to mdast by this utility.

Nodes

MDXFlowExpression

interface MDXFlowExpression <: Literal {
  type: "mdxFlowExpression"
}

MDXFlowExpression (Literal) represents a JavaScript expression embedded in flow (block). It can be used where flow expression content is expected. Its content is represented by its value field.

For example, the following markdown:

{
  1 + 1
}

Yields:

{type: 'mdxFlowExpression', value: '\n1 + 1\n'}

MDXTextExpression

interface MDXTextExpression <: Literal {
  type: "mdxTextExpression"
}

MDXTextExpression (Literal) represents a JavaScript expression embedded in text (span, inline). It can be used where phrasing expression content is expected. Its content is represented by its value field.

For example, the following markdown:

a {1 + 1} b.

Yields:

{type: 'mdxTextExpression', value: '1 + 1'}

Content model

FlowExpressionContent

type FlowExpressionContent = MDXFlowExpression

FlowExpression content represent an embedded JavaScript expression.

PhrasingExpressionContent

type PhrasingExpressionContent = MDXTextExpression

PhrasingExpression content represent an embedded JavaScript expression.

PhrasingContent (MDX expression)

type PhrasingContentMdxExpression = PhrasingExpressionContent | PhrasingContent

FlowContent (MDX expression)

type FlowContentMdxExpression = FlowExpressionContent | FlowContent

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
• 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
• syntax-tree/mdast-util-mdxjs — mdast utility to support all of MDX.js
• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• micromark/micromark-extension-mdx-expression — micromark extension to parse expressions

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