mdast-util-mdx-expression
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizesize-badgesize
!Sponsorssponsors-badgecollective
!Backersbackers-badgecollective
!Chatchat-badgechatmdast extensions to parse and serialize MDX expressions.
Contents
* [`mdxExpressionFromMarkdown`](#mdxexpressionfrommarkdown)
* [`mdxExpressionToMarkdown`](#mdxexpressiontomarkdown)
* [Nodes](#nodes)
* [Content model](#content-model)
What is this?
This package contains extensions that add support for the expression syntax enabled by MDX tomdast-util-from-markdown
mdast-util-from-markdown and
mdast-util-to-markdown
mdast-util-to-markdown.When to use this
These tools are all rather low-level. In most cases, you’d want to useremark-mdx
remark-mdx with remark instead.When you are working with syntax trees and want all of MDX, use
mdast-util-mdx
mdast-util-mdx instead.When working with
mdast-util-from-markdown
, you must combine this package with
micromark-extension-mdx-expression
extension.Install
This package is ESM onlyesm. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:npm install mdast-util-mdx-expression
In Deno with
esm.sh
esmsh:import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@1'
In browsers with
esm.sh
esmsh:<script type="module">
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@1?bundle'
</script>
Use
Say our documentexample.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 identifiersmdxExpressionFromMarkdown
and
mdxExpressionToMarkdown
.
There is no default export.mdxExpressionFromMarkdown
Extension for mdast-util-from-markdown
mdast-util-from-markdown.When using the syntax extension with
addResult
extension, nodes will have
a data.estree
field set to an ESTree.mdxExpressionToMarkdown
Extension for mdast-util-to-markdown
mdast-util-to-markdown.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 typesMdxFlowExpression
and MdxTextExpression
.It also registers the node types with
@types/mdast
.
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 12.20+, 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
Seecontributing.md
contributing in syntax-tree/.github
health for
ways to get started.
See support.md
support 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.