mdast-util-mdx-expression

mdast extension to parse and serialize MDX (or MDX.js) expressions

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
mdast-util-mdx-expression
101.3.22 months ago2 years agoMinified + gzip package size for mdast-util-mdx-expression in KB

Popular Searches

Readme

mdast-util-mdx-expression
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sizesize-badgesize !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
mdast extensions to parse and serialize MDX expressions ({Math.PI}).

Contents

*   [`mdxExpressionFromMarkdown`](#mdxexpressionfrommarkdown)
*   [`mdxExpressionToMarkdown`](#mdxexpressiontomarkdown)
*   [`MdxFlowExpression`](#mdxflowexpression)
*   [`MdxTextExpression`](#mdxtextexpression)
*   [`MdxFlowExpressionHast`](#mdxflowexpressionhast)
*   [`MdxTextExpressionHast`](#mdxtextexpressionhast)
*   [Nodes](#nodes)
*   [Content model](#content-model)

What is this?

This package contains two extensions that add support for MDX expression syntax in markdown to mdast. These extensions plug into mdast-util-from-markdownmdast-util-from-markdown (to support parsing expressions in markdown into a syntax tree) and mdast-util-to-markdownmdast-util-to-markdown (to support serializing expressions in syntax trees to markdown).

When to use this

You can use these extensions when you are working with mdast-util-from-markdown and mdast-util-to-markdown already.
When working with mdast-util-from-markdown, you must combine this package with micromark-extension-mdx-expressionextension.
When you are working with syntax trees and want all of MDX, use mdast-util-mdxmdast-util-mdx instead.
All these packages are used in remark-mdxremark-mdx, which focusses on making it easier to transform content by abstracting these internals away.

Install

This package is ESM onlyesm. In Node.js (version 14.14+ and 16.0+), install with npm:
npm install mdast-util-mdx-expression

In Deno with esm.shesmsh:
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@1'

In browsers with esm.shesmsh:
<script type="module">
  import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@1?bundle'
</script>

Use

Say our document example.mdx contains:
{
  a + 1
}

b {true}.

…and our module example.js looks as follows:
import fs from 'node:fs/promises'
import * as acorn from 'acorn'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toMarkdown} from 'mdast-util-to-markdown'
import {mdxExpression} from 'micromark-extension-mdx-expression'
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'mdast-util-mdx-expression'

const doc = await fs.readFile('example.mdx')

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

console.log(tree)

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

console.log(out)

…now running node example.js yields (positional info removed for brevity):
{
  type: 'root',
  children: [
    {
      type: 'mdxFlowExpression',
      value: '\na + 1\n',
      data: {
        estree: {
          type: 'Program',
          body: [
            {
              type: 'ExpressionStatement',
              expression: {
                type: 'BinaryExpression',
                left: {type: 'Identifier', name: 'a'},
                operator: '+',
                right: {type: 'Literal', value: 1, raw: '1'}
              }
            }
          ],
          sourceType: 'module'
        }
      }
    },
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'b '},
        {
          type: 'mdxTextExpression',
          value: 'true',
          data: {
            estree: {
              type: 'Program',
              body: [
                {
                  type: 'ExpressionStatement',
                  expression: {type: 'Literal', value: true, raw: 'true'}
                }
              ],
              sourceType: 'module'
            }
          }
        },
        {type: 'text', value: '.'}
      ]
    }
  ]
}

{
  a + 1
}

b {true}.

API

This package exports the identifiers mdxExpressionFromMarkdownapi-mdx-expression-from-markdown and mdxExpressionToMarkdownapi-mdx-expression-to-markdown. There is no default export.

mdxExpressionFromMarkdown

Extension for mdast-util-from-markdownmdast-util-from-markdown to enable MDX expressions.
When using the micromark syntax extensionextension with addResult, nodes will have a data.estree field set to an ESTree Programprogram node.

mdxExpressionToMarkdown

Extension for mdast-util-to-markdownmdast-util-to-markdown to enable MDX expressions.

MdxFlowExpression

MDX expression node, occurring in flow (block) (TypeScript type).
Type
import type {Program} from 'estree-jsx'
import type {Literal} from 'mdast'

interface MdxFlowExpression extends Literal {
  type: 'mdxFlowExpression'
  data?: {estree?: Program | null | undefined} & Literal['data']
}

MdxTextExpression

MDX expression node, occurring in text (block) (TypeScript type).
Type
import type {Program} from 'estree-jsx'
import type {Literal} from 'mdast'

interface MdxTextExpression extends Literal {
  type: 'mdxTextExpression'
  data?: {estree?: Program | null | undefined} & Literal['data']
}

MdxFlowExpressionHast

Same as MdxFlowExpressionapi-mdx-flow-expression, but registered with @types/hast (TypeScript type).
Type
import type {Program} from 'estree-jsx'
import type {Literal} from 'hast'

interface MdxFlowExpressionHast extends Literal {
  type: 'mdxFlowExpression'
  data?: {estree?: Program | null | undefined} & Literal['data']
}

MdxTextExpressionHast

Same as MdxTextExpressionapi-mdx-text-expression, but registered with @types/hast (TypeScript type).
Type
import type {Program} from 'estree-jsx'
import type {Literal} from 'hast'

interface MdxTextExpressionHast extends Literal {
  type: 'mdxTextExpression'
  data?: {estree?: Program | null | undefined} & Literal['data']
}

HTML

MDX expressions have no representation in HTML. Though, when you are dealing with MDX, you will likely go through hast. You can enable passing MDX expressions through to hast by configuring mdast-util-to-hastmdast-util-to-hast with passThrough: ['mdxFlowExpression', 'mdxTextExpression'].

Syntax

See Syntax in micromark-extension-mdx-expressionsyntax.

Syntax tree

The following interfaces are added to mdast by this utility.

Nodes

MdxFlowExpression

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

MdxFlowExpression (Literaldfn-literal) represents a JavaScript expression embedded in flow (block). It can be used where flowdfn-flow-content 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 (Literaldfn-literal) represents a JavaScript expression embedded in text (span, inline). It can be used where phrasingdfn-phrasing-content 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

FlowContent (MDX expression)

type FlowContentMdxExpression = MdxFlowExpression | FlowContent

PhrasingContent (MDX expression)

type PhrasingContentMdxExpression = MdxTextExpression | PhrasingContent

Types

This package is fully typed with TypeScript. It exports the additional types MdxFlowExpressionapi-mdx-flow-expression, MdxFlowExpressionHastapi-mdx-flow-expression-hast, MdxTextExpressionapi-mdx-text-expression, and MdxTextExpressionHastapi-mdx-text-expression-hast.
It also registers the node types with @types/mdast and @types/hast. If you’re working with the syntax tree, make sure to import this utility somewhere in your types, as that registers the new node types in the tree.
/**
 * @typedef {import('mdast-util-mdx-expression')}
 */

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

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

visit(tree, (node) => {
  // `node` can now be an expression node.
})

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 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

— remark plugin to support MDX
— mdast utility to support MDX
— micromark extension to parse MDX expressions

Contribute

See contributing.mdcontributing in syntax-tree/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.

License

MITlicense © Titus Wormerauthor