mdast-util-mdx-expression
mdast extensions to parse and serialize MDX expressions.
Contents
What is this?
This package contains extensions that add support for the expression syntax
enabled by MDX to mdast-util-from-markdown
and
mdast-util-to-markdown
.
When to use this
These tools are all rather low-level.
In most cases, you’d want to use remark-mdx
with remark instead.
When you are working with syntax trees and want all of MDX, use
mdast-util-mdx
instead.
When working with mdast-util-from-markdown
, you must combine this package with
micromark-extension-mdx-expression
.
Install
This package is ESM only.
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
:
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@1'
In browsers with esm.sh
:
<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 mdxExpressionFromMarkdown
and
mdxExpressionToMarkdown
.
There is no default export.
mdxExpressionFromMarkdown
Extension for mdast-util-from-markdown
.
When using the syntax extension with addResult
, nodes will have
a data.estree
field set to an ESTree.
mdxExpressionToMarkdown
Extension for mdast-util-to-markdown
.
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 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 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 MdxFlowExpression
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.
import {visit} from 'unist-util-visit'
const tree = getMdastNodeSomeHow()
visit(tree, (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
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