mdast extensions to parse and serialize MDX expressions ({Math.PI}).
- What is this?
- When to use this
- Install
- Use
- API
- HTML
- Syntax
- Syntax tree
- Types
- Compatibility
- Related
- Contribute
- License
This package contains two extensions that add support for MDX expression syntax
in markdown to mdast.
These extensions plug into
mdast-util-from-markdown (to support parsing
expressions in markdown into a syntax tree) and
mdast-util-to-markdown (to support serializing
expressions in syntax trees to markdown).
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-expression.
When you are working with syntax trees and want all of MDX, use
mdast-util-mdx instead.
All these packages are used in remark-mdx, which
focusses on making it easier to transform content by abstracting these
internals away.
This package is ESM only. In Node.js (version 16+), install with npm:
npm install mdast-util-mdx-expressionIn Deno with esm.sh:
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@2'In browsers with esm.sh:
<script type="module">
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@2?bundle'
</script>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 {mdxExpression} from 'micromark-extension-mdx-expression'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'mdast-util-mdx-expression'
import {toMarkdown} from 'mdast-util-to-markdown'
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}.This package exports the identifiers
mdxExpressionFromMarkdown and
mdxExpressionToMarkdown.
There is no default export.
Create an extension for mdast-util-from-markdown
to enable MDX expressions in markdown.
When using the micromark syntax extension with addResult, nodes
will have a data.estree field set to an ESTree Program node.
Extension for mdast-util-from-markdown to enable MDX expressions
(FromMarkdownExtension).
Create an extension for mdast-util-to-markdown
to enable MDX expressions in markdown.
Extension for mdast-util-to-markdown to enable MDX expressions
(ToMarkdownExtension).
MDX expression node, occurring in flow (block) (TypeScript type).
import type {Program} from 'estree-jsx'
import type {Data, Literal} from 'mdast'
interface MdxFlowExpression extends Literal {
type: 'mdxFlowExpression'
data?: MdxFlowExpressionData | undefined
}
interface MdxFlowExpressionData extends Data {
estree?: Program | null | undefined
}MDX expression node, occurring in text (block) (TypeScript type).
import type {Program} from 'estree-jsx'
import type {Data, Literal} from 'mdast'
interface MdxTextExpression extends Literal {
type: 'mdxTextExpression'
data?: MdxTextExpressionData | undefined
}
interface MdxTextExpressionData extends Data {
estree?: Program | null | undefined
}Same as MdxFlowExpression, but registered with
@types/hast (TypeScript type).
import type {Program} from 'estree-jsx'
import type {Data, Literal} from 'hast'
interface MdxFlowExpressionHast extends Literal {
type: 'mdxFlowExpression'
data?: MdxFlowExpressionData | undefined
}
interface MdxFlowExpressionData extends Data {
estree?: Program | null | undefined
}Same as MdxTextExpression, but registered with
@types/hast (TypeScript type).
import type {Program} from 'estree-jsx'
import type {Data, Literal} from 'hast'
interface MdxTextExpressionHast extends Literal {
type: 'mdxTextExpression'
data?: MdxTextExpressionData | undefined
}
interface MdxTextExpressionData extends Data {
estree?: Program | null | undefined
}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-hast with
passThrough: ['mdxFlowExpression', 'mdxTextExpression'].
See Syntax in micromark-extension-mdx-expression.
The following interfaces are added to mdast by this utility.
interface MdxFlowExpression <: Literal {
type: 'mdxFlowExpression'
}MdxFlowExpression (Literal) represents a JavaScript
expression embedded in flow (block).
It can be used where flow 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'}interface MdxTextExpression <: Literal {
type: 'mdxTextExpression"
}MdxTextExpression (Literal) represents a JavaScript
expression embedded in text (span, inline).
It can be used where phrasing 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'}type FlowContentMdxExpression = MdxFlowExpression | FlowContenttype PhrasingContentMdxExpression = MdxTextExpression | PhrasingContentThis package is fully typed with TypeScript.
It exports the additional types MdxFlowExpression,
MdxFlowExpressionHast,
MdxTextExpression, and
MdxTextExpressionHast.
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.
/**
* @import {} from 'mdast-util-mdx-expression'
* @import {Root} from 'mdast'
*/
import {visit} from 'unist-util-visit'
/** @type {Root} */
const tree = getMdastNodeSomeHow()
visit(tree, function (node) {
// `node` can now be an expression node.
})Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
mdast-util-mdx-expression@^2, compatible with Node.js 16.
This utility works with mdast-util-from-markdown version 2+ and
mdast-util-to-markdown version 2+.
remarkjs/remark-mdx— remark plugin to support MDXsyntax-tree/mdast-util-mdx— mdast utility to support MDXmicromark/micromark-extension-mdx-expression— micromark extension to parse MDX expressions
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.