mdast-util-mdx

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

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
mdast-util-mdx
3.0.09 months ago3 years agoMinified + gzip package size for mdast-util-mdx in KB

Popular Searches

Readme

mdast-util-mdx
!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sizesize-badgesize !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat

Contents

*   [`mdxFromMarkdown()`](#mdxfrommarkdown)
*   [`mdxToMarkdown(options?)`](#mdxtomarkdownoptions)
*   [`ToMarkdownOptions`](#tomarkdownoptions)

What is this?

This package contains two extensions that add support for MDX syntax in markdown to mdast: ESM (import x from 'y'), JSX (<a />), and expressions ({Math.PI}). These extensions plug into mdast-util-from-markdownmdast-util-from-markdown (to support parsing MDX in markdown into a syntax tree) and mdast-util-to-markdownmdast-util-to-markdown (to support serializing MDX 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-mdxmdx or micromark-extension-mdxjsmdxjs.
Instead of this package, you can also use the extensions separately:
— support MDX expressions
— support MDX JSX
— support MDX ESM
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 16+), install with npm:
npm install mdast-util-mdx

In Deno with esm.shesmsh:
import {mdxFromMarkdown, mdxToMarkdown} from 'https://esm.sh/mdast-util-mdx@3'

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

Use

Say our document example.mdx contains:
import Box from "place"

Here’s an expression:

{
  1 + 1 /* } */
}

Which you can also put inline: {1+1}.

<Box>
  <SmallerBox>
    - Lists, which can be indented.
  </SmallerBox>
</Box>

…and our module example.js looks as follows:
import fs from 'node:fs/promises'
import {mdxjs} from 'micromark-extension-mdxjs'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {mdxFromMarkdown, mdxToMarkdown} from 'mdast-util-mdx'
import {toMarkdown} from 'mdast-util-to-markdown'

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

const tree = fromMarkdown(doc, {
  extensions: [mdxjs()],
  mdastExtensions: [mdxFromMarkdown()]
})

console.log(tree)

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

console.log(out)

…now running node example.js yields (positional info removed for brevity):
{
  type: 'root',
  children: [
    {
      type: 'mdxjsEsm',
      value: 'import Box from "place"',
      data: {
        estree: {
          type: 'Program',
          body: [
            {
              type: 'ImportDeclaration',
              specifiers: [
                {
                  type: 'ImportDefaultSpecifier',
                  local: {type: 'Identifier', name: 'Box'}
                }
              ],
              source: {type: 'Literal', value: 'place', raw: '"place"'}
            }
          ],
          sourceType: 'module'
        }
      }
    },
    {
      type: 'paragraph',
      children: [{type: 'text', value: 'Here’s an expression:'}]
    },
    {
      type: 'mdxFlowExpression',
      value: '\n1 + 1 /* } */\n',
      data: {
        estree: {
          type: 'Program',
          body: [
            {
              type: 'ExpressionStatement',
              expression: {
                type: 'BinaryExpression',
                left: {type: 'Literal', value: 1, raw: '1'},
                operator: '+',
                right: {type: 'Literal', value: 1, raw: '1'}
              }
            }
          ],
          sourceType: 'module'
        }
      }
    },
    {
      type: 'paragraph',
      children: [
        {type: 'text', value: 'Which you can also put inline: '},
        {
          type: 'mdxTextExpression',
          value: '1+1',
          data: {
            estree: {
              type: 'Program',
              body: [
                {
                  type: 'ExpressionStatement',
                  expression: {
                    type: 'BinaryExpression',
                    left: {type: 'Literal', value: 1, raw: '1'},
                    operator: '+',
                    right: {type: 'Literal', value: 1, raw: '1'}
                  }
                }
              ],
              sourceType: 'module'
            }
          }
        },
        {type: 'text', value: '.'}
      ]
    },
    {
      type: 'mdxJsxFlowElement',
      name: 'Box',
      attributes: [],
      children: [
        {
          type: 'mdxJsxFlowElement',
          name: 'SmallerBox',
          attributes: [],
          children: [
            {
              type: 'list',
              ordered: false,
              start: null,
              spread: false,
              children: [
                {
                  type: 'listItem',
                  spread: false,
                  checked: null,
                  children: [
                    {
                      type: 'paragraph',
                      children: [
                        {type: 'text', value: 'Lists, which can be indented.'}
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

import Box from "place"

Here’s an expression:

{
  1 + 1 /* } */
}

Which you can also put inline: {1+1}.

<Box>
  <SmallerBox>
    *   Lists, which can be indented.
  </SmallerBox>
</Box>

API

This package exports the identifiers mdxFromMarkdownapi-mdx-from-markdown and mdxToMarkdownapi-mdx-to-markdown. There is no default export.

mdxFromMarkdown()

Create an extension for mdast-util-from-markdownmdast-util-from-markdown to enable MDX (ESM, JSX, expressions).
Returns
Extension for mdast-util-from-markdown to enable MDX (FromMarkdownExtensionfrom-markdown-extension).
When using the syntax extensions with addResultmdxjs, ESM and expression nodes will have data.estree fields set to ESTree Programprogram node.

mdxToMarkdown(options?)

Create an extension for mdast-util-to-markdownmdast-util-to-markdown to enable MDX (ESM, JSX, expressions).
Extension for mdast-util-to-markdownmdast-util-to-markdown.
Parameters
— configuration
Returns
Extension for mdast-util-to-markdown to enable MDX (FromMarkdownExtensionto-markdown-extension).

ToMarkdownOptions

Configuration (TypeScript type).
Fields
  • quote ('"' or "'", default: '"')
— preferred quote to use around attribute values
  • quoteSmart (boolean, default: false)
— use the other quote if that results in less bytes
  • tightSelfClosing (boolean, default: false)
— do not use an extra space when closing self-closing elements: `<img/>`
instead of `<img />`
  • printWidth (number, default: Infinity)
— try and wrap syntax at this width.
When set to a finite number (say, `80`), the formatter will print
attributes on separate lines when a tag doesn’t fit on one line.
The normal behavior is to print attributes with spaces between them instead
of line endings

HTML

MDX has no representation in HTML. Though, when you are dealing with MDX, you will likely go through hast. You can enable passing MDX through to hast by configuring mdast-util-to-hastmdast-util-to-hast with `passThrough: 'mdxjsEsm', 'mdxFlowExpression', 'mdxJsxFlowElement', 'mdxJsxTextElement', 'mdxTextExpression'`.

Syntax

See Syntax in micromark-extension-mdxjsmdxjs.

Syntax tree

This utility combines several mdast utilities. See their readmes for the node types supported in the tree:
— support MDX expressions
— support MDX JSX
— support MDX ESM

Types

This package is fully typed with TypeScript. It exports the additional types MdxFlowExpression and MdxTextExpression from mdast-util-mdx-expression; MdxJsxAttribute, MdxJsxAttributeValueExpression, MdxJsxExpressionAttribute, MdxJsxFlowElement, MdxJsxTextElement, and ToMarkdownOptionsapi-to-markdown-options from mdast-util-mdx-jsx; and MdxjsEsm from mdast-util-mdxjs-esm.
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')}
 */

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

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

visit(tree, function (node) {
  // `node` can now be an expression, JSX, or ESM node.
})

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-mdx@^3, compatible with Node.js 16.
This utility works with mdast-util-from-markdown version 2+ and mdast-util-to-markdown version 2+.

Related

— remark plugin to support MDX
— micromark extension to parse MDX
— micromark extension to parse JavaScript-aware MDX

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