Notable Peru Mariachis

    mdast-util-mdxjs-esm
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.1 • Public • Published

    mdast-util-mdxjs-esm

    Build Coverage Downloads Size Sponsors Backers Chat

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

    Contents

    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 14.14+ and 16.0+), install with npm:

    npm install mdast-util-mdxjs-esm

    In Deno with esm.sh:

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

    In browsers with esm.sh:

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

    Use

    Say our document example.mdx contains:

    import a from 'b'
    export const c = ''
    
    d

    …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 {mdxjsEsm} from 'micromark-extension-mdxjs-esm'
    import {mdxjsEsmFromMarkdown, mdxjsEsmToMarkdown} from 'mdast-util-mdxjs-esm'
    
    const doc = await fs.readFile('example.mdx')
    
    const tree = fromMarkdown(doc, {
      extensions: [mdxjsEsm({acorn, addResult: true})],
      mdastExtensions: [mdxjsEsmFromMarkdown]
    })
    
    console.log(tree)
    
    const out = toMarkdown(tree, {extensions: [mdxjsEsmToMarkdown]})
    
    console.log(out)

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

    {
      type: 'root',
      children: [
        {
          type: 'mdxjsEsm',
          value: "import a from 'b'\nexport const c = ''",
          data: {
            estree: {
              type: 'Program',
              body: [
                {
                  type: 'ImportDeclaration',
                  specifiers: [
                    {
                      type: 'ImportDefaultSpecifier',
                      local: {type: 'Identifier', name: 'a'}
                    }
                  ],
                  source: {type: 'Literal', value: 'b', raw: "'b'"}
                },
                {
                  type: 'ExportNamedDeclaration',
                  declaration: {
                    type: 'VariableDeclaration',
                    declarations: [
                      {
                        type: 'VariableDeclarator',
                        id: {type: 'Identifier', name: 'c'},
                        init: {type: 'Literal', value: '', raw: "''"}
                      }
                    ],
                    kind: 'const'
                  },
                  specifiers: [],
                  source: null
                }
              ],
              sourceType: 'module'
            }
          }
        },
        {type: 'paragraph', children: [{type: 'text', value: 'd'}]}
      ]
    }
    import a from 'b'
    export const c = ''
    
    d

    API

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

    mdxjsEsmFromMarkdown

    Extension for mdast-util-from-markdown to enable MDX ESM.

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

    mdxjsEsmToMarkdown

    Extension for mdast-util-to-markdown to enable MDX ESM.

    MdxjsEsm

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

    Type
    import type {Program} from 'estree-jsx'
    import type {Literal} from 'mdast'
    
    interface MdxjsEsm extends Literal {
      type: 'mdxjsEsm'
      data?: {estree?: Program | null | undefined}
    }

    MdxjsEsmHast

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

    Type
    import type {Program} from 'estree-jsx'
    import type {Literal} from 'hast'
    
    interface MdxjsEsm extends Literal {
      type: 'mdxjsEsm'
      data?: {estree?: Program | null | undefined}
    }

    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

    interface MdxjsEsm <: Literal {
      type: 'mdxjsEsm'
    }

    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:

    import a from 'b'

    Yields:

    {
      type: 'mdxjsEsm',
      value: 'import a from \'b\''
    }

    Content model

    FlowContent (MDX.js ESM)

    type 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.

    /**
     * @typedef {import('mdast-util-mdxjs-esm')}
     */
    
    import {visit} from 'unist-util-visit'
    
    /** @type {import('mdast').Root} */
    const tree = getMdastNodeSomeHow()
    
    visit(tree, (node) => {
      // `node` can now be an ESM node.
    })

    Compatibility

    Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 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

    Install

    npm i mdast-util-mdxjs-esm

    DownloadsWeekly Downloads

    544,498

    Version

    1.3.1

    License

    MIT

    Unpacked Size

    19.5 kB

    Total Files

    8

    Last publish

    Collaborators

    • wooorm
    • kmck