mdast-util-mdxjs-esm

mdast extensions to parse and serialize MDX ESM (import/exports).

Contents

• What is this?
• When to use this
• Install
• Use
• API
  • mdxjsEsmFromMarkdown()
  • mdxjsEsmToMarkdown()
  • MdxjsEsm
  • MdxjsEsmHast
• HTML
• Syntax
• Syntax tree
  • Nodes
  • Content model
• Types
• Compatibility
• Related
• Contribute
• License

What is this?

This package contains two extensions that add support for MDX ESM syntax in markdown to mdast. These extensions plug into mdast-util-from-markdown (to support parsing ESM in markdown into a syntax tree) and mdast-util-to-markdown (to support serializing ESM 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-mdxjs-esm.

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.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

1npm install mdast-util-mdxjs-esm

In Deno with esm.sh:

1import {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} from 'https://esm.sh/mdast-util-mdxjs-esm@2'

In browsers with esm.sh:

1<script type="module">
2  import {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} from 'https://esm.sh/mdast-util-mdxjs-esm@2?bundle'
3</script>

Use

Say our document example.mdx contains:

1import a from 'b'
2export const c = ''
3
4d

…and our module example.js looks as follows:

1import fs from 'node:fs/promises'
2import * as acorn from 'acorn'
3import {fromMarkdown} from 'mdast-util-from-markdown'
4import {toMarkdown} from 'mdast-util-to-markdown'
5import {mdxjsEsm} from 'micromark-extension-mdxjs-esm'
6import {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} from 'mdast-util-mdxjs-esm'
7
8const doc = await fs.readFile('example.mdx')
9
10const tree = fromMarkdown(doc, {
11  extensions: [mdxjsEsm({acorn, addResult: true})],
12  mdastExtensions: [mdxjsEsmFromMarkdown()]
13})
14
15console.log(tree)
16
17const out = toMarkdown(tree, {extensions: [mdxjsEsmToMarkdown()]})
18
19console.log(out)

…now running node example.js yields (positional info removed for brevity):

1{
2  type: 'root',
3  children: [
4    {
5      type: 'mdxjsEsm',
6      value: "import a from 'b'\nexport const c = ''",
7      data: {
8        estree: {
9          type: 'Program',
10          body: [
11            {
12              type: 'ImportDeclaration',
13              specifiers: [
14                {
15                  type: 'ImportDefaultSpecifier',
16                  local: {type: 'Identifier', name: 'a'}
17                }
18              ],
19              source: {type: 'Literal', value: 'b', raw: "'b'"}
20            },
21            {
22              type: 'ExportNamedDeclaration',
23              declaration: {
24                type: 'VariableDeclaration',
25                declarations: [
26                  {
27                    type: 'VariableDeclarator',
28                    id: {type: 'Identifier', name: 'c'},
29                    init: {type: 'Literal', value: '', raw: "''"}
30                  }
31                ],
32                kind: 'const'
33              },
34              specifiers: [],
35              source: null
36            }
37          ],
38          sourceType: 'module'
39        }
40      }
41    },
42    {type: 'paragraph', children: [{type: 'text', value: 'd'}]}
43  ]
44}

1import a from 'b'
2export const c = ''
3
4d

API

This package exports the identifiers mdxjsEsmFromMarkdown and mdxjsEsmToMarkdown. There is no default export.

mdxjsEsmFromMarkdown()

Create an extension for mdast-util-from-markdown to enable MDX.js ESM in markdown.

When using the micromark syntax extension with addResult, nodes will have a data.estree field set to an ESTree Program node.

Returns

Extension for mdast-util-from-markdown to enable MDX.js ESM (FromMarkdownExtension).

mdxjsEsmToMarkdown()

Create an extension for mdast-util-to-markdown to enable MDX.js ESM in markdown.

Returns

Extension for mdast-util-to-markdown to enable MDX.js ESM (ToMarkdownExtension).

MdxjsEsm

MDX ESM (import/export) node (TypeScript type).

Type

1import type {Program} from 'estree-jsx'
2import type {Data, Literal} from 'mdast'
3
4interface MdxjsEsm extends Literal {
5  type: 'mdxjsEsm'
6  data?: MdxjsEsmData | undefined
7}
8
9export interface MdxjsEsmData extends Data {
10  estree?: Program | null | undefined
11}

MdxjsEsmHast

Same as MdxjsEsm, but registered with @types/hast (TypeScript type).

Type

1import type {Program} from 'estree-jsx'
2import type {Data, Literal} from 'hast'
3
4interface MdxjsEsmHast extends Literal {
5  type: 'mdxjsEsm'
6  data?: MdxjsEsmHastData | undefined
7}
8
9export interface MdxjsEsmHastData extends Data {
10  estree?: Program | null | undefined
11}

HTML

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

Syntax

See Syntax in micromark-extension-mdxjs-esm.

Syntax tree

The following interfaces are added to mdast by this utility.

Nodes

MdxjsEsm

1interface MdxjsEsm <: Literal {
2  type: 'mdxjsEsm'
3}

MdxjsEsm (Literal) represents ESM import/exports embedded in MDX. It can be used where flow content is expected. Its content is represented by its value field.

For example, the following Markdown:

1import a from 'b'

Yields:

1{
2  type: 'mdxjsEsm',
3  value: 'import a from \'b\''
4}

Content model

FlowContent (MDX.js ESM)

1type FlowContentMdxjsEsm = MdxjsEsm | FlowContent

Note that when ESM is present, it can only exist as top-level content: if it has a parent, that parent must be Root.

Types

This package is fully typed with TypeScript. It exports the additional types MdxjsEsm and MdxjsEsmHast.

It also registers the node type 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.

1/**
2 * @typedef {import('mdast-util-mdxjs-esm')}
3 */
4
5import {visit} from 'unist-util-visit'
6
7/** @type {import('mdast').Root} */
8const tree = getMdastNodeSomeHow()
9
10visit(tree, function (node) {
11  // `node` can now be an ESM node.
12})

Compatibility

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-mdxjs-esm@^2, compatible with Node.js 16.

This utility works with mdast-util-from-markdown version 2+ and mdast-util-to-markdown version 2+.

Related

• remarkjs/remark-mdx — remark plugin to support MDX
• syntax-tree/mdast-util-mdx — mdast utility to support MDX
• micromark/micromark-extension-mdxjs-esm — micromark extension to parse MDX.js ESM

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