Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/syntax-tree/mdast-util-mdx-jsx

mdast extension to parse and serialize MDX JSX
https://github.com/syntax-tree/mdast-util-mdx-jsx

jsx mdast mdast-util mdx mdxjs

Last synced: 3 months ago
JSON representation

mdast extension to parse and serialize MDX JSX

Awesome Lists containing this project

README 

          
# mdast-util-mdx-jsx



[![Build][build-badge]][build]

[![Coverage][coverage-badge]][coverage]

[![Downloads][downloads-badge]][downloads]

[![Size][size-badge]][size]

[![Sponsors][sponsors-badge]][collective]

[![Backers][backers-badge]][collective]

[![Chat][chat-badge]][chat]



[mdast][] extensions to parse and serialize [MDX][] JSX (``).



## Contents



* [What is this?](#what-is-this)

* [When to use this](#when-to-use-this)

* [Install](#install)

* [Use](#use)

* [API](#api)

  * [`mdxJsxFromMarkdown()`](#mdxjsxfrommarkdown)

  * [`mdxJsxToMarkdown(options?)`](#mdxjsxtomarkdownoptions)

  * [`MdxJsxAttribute`](#mdxjsxattribute)

  * [`MdxJsxAttributeValueExpression`](#mdxjsxattributevalueexpression)

  * [`MdxJsxExpressionAttribute`](#mdxjsxexpressionattribute)

  * [`MdxJsxFlowElement`](#mdxjsxflowelement)

  * [`MdxJsxFlowElementHast`](#mdxjsxflowelementhast)

  * [`MdxJsxTextElement`](#mdxjsxtextelement)

  * [`MdxJsxTextElementHast`](#mdxjsxtextelementhast)

  * [`ToMarkdownOptions`](#tomarkdownoptions)

* [HTML](#html)

* [Syntax](#syntax)

* [Syntax tree](#syntax-tree)

  * [Nodes](#nodes)

  * [Mixin](#mixin)

  * [Content model](#content-model)

* [Types](#types)

* [Compatibility](#compatibility)

* [Related](#related)

* [Contribute](#contribute)

* [License](#license)



## What is this?



This package contains two extensions that add support for MDX JSX syntax in

markdown to [mdast][].

These extensions plug into

[`mdast-util-from-markdown`][mdast-util-from-markdown] (to support parsing

JSX in markdown into a syntax tree) and

[`mdast-util-to-markdown`][mdast-util-to-markdown] (to support serializing

JSX in syntax trees to markdown).



[JSX][] is an XML-like syntax extension to ECMAScript (JavaScript), which MDX

brings to markdown.

For more info on MDX, see [What is MDX?][what-is-mdx]



## 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-mdx-jsx`][micromark-extension-mdx-jsx].



When you are working with syntax trees and want all of MDX, use

[`mdast-util-mdx`][mdast-util-mdx] instead.



All these packages are used in [`remark-mdx`][remark-mdx], which

focusses on making it easier to transform content by abstracting these

internals away.



## Install



This package is [ESM only][esm].

In Node.js (version 16+), install with [npm][]:



```sh

npm install mdast-util-mdx-jsx

```



In Deno with [`esm.sh`][esmsh]:



```js

import {mdxJsxFromMarkdown, mdxJsxToMarkdown} from 'https://esm.sh/mdast-util-mdx-jsx@3'

```



In browsers with [`esm.sh`][esmsh]:



```html



  import {mdxJsxFromMarkdown, mdxJsxToMarkdown} from 'https://esm.sh/mdast-util-mdx-jsx@3?bundle'



```



## Use



Say our document `example.mdx` contains:



```mdx



  - a list



HTML is a lovely language.

```



…and our module `example.js` looks as follows:



```js

import fs from 'node:fs/promises'

import * as acorn from 'acorn'

import {mdxJsx} from 'micromark-extension-mdx-jsx'

import {fromMarkdown} from 'mdast-util-from-markdown'

import {mdxJsxFromMarkdown, mdxJsxToMarkdown} from 'mdast-util-mdx-jsx'

import {toMarkdown} from 'mdast-util-to-markdown'



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



const tree = fromMarkdown(doc, {

  extensions: [mdxJsx({acorn, addResult: true})],

  mdastExtensions: [mdxJsxFromMarkdown()]

})



console.log(tree)



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



console.log(out)

```



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



```js

{

  type: 'root',

  children: [

    {

      type: 'mdxJsxFlowElement',

      name: 'Box',

      attributes: [],

      children: [

        {

          type: 'list',

          ordered: false,

          start: null,

          spread: false,

          children: [

            {

              type: 'listItem',

              spread: false,

              checked: null,

              children: [

                {type: 'paragraph', children: [{type: 'text', value: 'a list'}]}

              ]

            }

          ]

        }

      ]

    },

    {

      type: 'mdxJsxFlowElement',

      name: 'MyComponent',

      attributes: [

        {

          type: 'mdxJsxExpressionAttribute',

          value: '...props',

          data: {

            estree: {

              type: 'Program',

              body: [

                {

                  type: 'ExpressionStatement',

                  expression: {

                    type: 'ObjectExpression',

                    properties: [

                      {

                        type: 'SpreadElement',

                        argument: {type: 'Identifier', name: 'props'}

                      }

                    ]

                  }

                }

              ],

              sourceType: 'module'

            }

          }

        }

      ],

      children: []

    },

    {

      type: 'paragraph',

      children: [

        {

          type: 'mdxJsxTextElement',

          name: 'abbr',

          attributes: [

            {

              type: 'mdxJsxAttribute',

              name: 'title',

              value: 'Hypertext Markup Language'

            }

          ],

          children: [{type: 'text', value: 'HTML'}]

        },

        {type: 'text', value: ' is a lovely language.'}

      ]

    }

  ]

}

```



```markdown



  *   a list



HTML is a lovely language.

```



## API



This package exports the identifiers

[`mdxJsxFromMarkdown`][api-mdx-jsx-from-markdown] and

[`mdxJsxToMarkdown`][api-mdx-jsx-to-markdown].

There is no default export.



### `mdxJsxFromMarkdown()`



Create an extension for

[`mdast-util-from-markdown`][mdast-util-from-markdown]

to enable MDX JSX.



###### Returns



Extension for `mdast-util-from-markdown` to enable MDX JSX

([`FromMarkdownExtension`][from-markdown-extension]).



When using the [micromark syntax extension][micromark-extension-mdx-jsx] with

`addResult`, nodes will have a `data.estree` field set to an ESTree

[`Program`][program] node.



### `mdxJsxToMarkdown(options?)`



Create an extension for

[`mdast-util-to-markdown`][mdast-util-to-markdown]

to enable MDX JSX.



This extension configures `mdast-util-to-markdown` with

[`options.fences: true`][mdast-util-to-markdown-fences] and

[`options.resourceLink: true`][mdast-util-to-markdown-resourcelink] too, do not

overwrite them!



###### Parameters



* `options` ([`ToMarkdownOptions`][api-to-markdown-options])

  — configuration



###### Returns



Extension for `mdast-util-to-markdown` to enable MDX JSX

([`FromMarkdownExtension`][to-markdown-extension]).



### `MdxJsxAttribute`



MDX JSX attribute with a key (TypeScript type).



###### Type



```ts

import type {Literal} from 'mdast'



interface MdxJsxAttribute extends Literal {

  type: 'mdxJsxAttribute'

  name: string

  value?: MdxJsxAttributeValueExpression | string | null | undefined

}

```



### `MdxJsxAttributeValueExpression`



MDX JSX attribute value set to an expression (TypeScript type).



###### Type



```ts

import type {Program} from 'estree-jsx'

import type {Literal} from 'mdast'



interface MdxJsxAttributeValueExpression extends Literal {

  type: 'mdxJsxAttributeValueExpression'

  data?: {estree?: Program | null | undefined} & Literal['data']

}

```



### `MdxJsxExpressionAttribute`



MDX JSX attribute as an expression (TypeScript type).



###### Type



```ts

import type {Program} from 'estree-jsx'

import type {Literal} from 'mdast'



interface MdxJsxExpressionAttribute extends Literal {

  type: 'mdxJsxExpressionAttribute'

  data?: {estree?: Program | null | undefined} & Literal['data']

}

```



### `MdxJsxFlowElement`



MDX JSX element node, occurring in flow (block) (TypeScript type).



###### Type



```ts

import type {BlockContent, DefinitionContent, Parent} from 'mdast'



export interface MdxJsxFlowElement extends Parent {

  type: 'mdxJsxFlowElement'

  name: string | null

  attributes: Array

  children: Array

}

```



### `MdxJsxFlowElementHast`



Same as [`MdxJsxFlowElement`][api-mdx-jsx-flow-element], but registered with

`@types/hast` (TypeScript type).



###### Type



```ts

import type {ElementContent, Parent} from 'hast'



export interface MdxJsxFlowElementHast extends Parent {

  type: 'mdxJsxFlowElement'

  name: string | null

  attributes: Array

  children: Array

}

```



### `MdxJsxTextElement`



MDX JSX element node, occurring in text (phrasing) (TypeScript type).



###### Type



```ts

import type {Parent, PhrasingContent} from 'mdast'



export interface MdxJsxTextElement extends Parent {

  type: 'mdxJsxTextElement'

  name: string | null

  attributes: Array

  children: Array

}

```



### `MdxJsxTextElementHast`



Same as [`MdxJsxTextElement`][api-mdx-jsx-text-element], but registered with

`@types/hast` (TypeScript type).



###### Type



```ts

import type {ElementContent, Parent} from 'hast'



export interface MdxJsxTextElementHast extends Parent {

  type: 'mdxJsxTextElement'

  name: string | null

  attributes: Array

  children: Array

}

```



### `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: ``

  instead of ``

* `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 JSX has no representation in HTML.

Though, when you are dealing with MDX, you will likely go *through* hast.

You can enable passing MDX JSX through to hast by configuring

[`mdast-util-to-hast`][mdast-util-to-hast] with

`passThrough: ['mdxJsxFlowElement', 'mdxJsxTextElement']`.



## Syntax



See [Syntax in `micromark-extension-mdx-jsx`][syntax].



## Syntax tree



The following interfaces are added to **[mdast][]** by this utility.



### Nodes



#### `MdxJsxFlowElement`



```idl

interface MdxJsxFlowElement <: Parent {

  type: 'mdxJsxFlowElement'

}



MdxJsxFlowElement includes MdxJsxElement

```



**MdxJsxFlowElement** (**[Parent][dfn-parent]**) represents JSX in flow (block).

It can be used where **[flow][dfn-content-flow]** content is expected.

It includes the mixin **[MdxJsxElement][dfn-mixin-mdx-jsx-element]**.



For example, the following markdown:



```markdown



  z



```



Yields:



```js

{

  type: 'mdxJsxFlowElement',

  name: 'w',

  attributes: [{type: 'mdxJsxAttribute', name: 'x', value: 'y'}],

  children: [{type: 'paragraph', children: [{type: 'text', value: 'z'}]}]

}

```



#### `MdxJsxTextElement`



```idl

interface MdxJsxTextElement <: Parent {

  type: 'mdxJsxTextElement'

}



MdxJsxTextElement includes MdxJsxElement

```



**MdxJsxTextElement** (**[Parent][dfn-parent]**) represents JSX in text (span,

inline).

It can be used where **[phrasing][dfn-content-phrasing]** content is

expected.

It includes the mixin **[MdxJsxElement][dfn-mixin-mdx-jsx-element]**.



For example, the following markdown:



```markdown

a d e.

```



Yields:



```js

{

  type: 'mdxJsxTextElement',

  name: 'b',

  attributes: [{type: 'mdxJsxAttribute', name: 'c', value: null}],

  children: [{type: 'text', value: 'd'}]

}

```



### Mixin



#### `MdxJsxElement`



```idl

interface mixin MdxJsxElement {

  name: string?

  attributes: [MdxJsxExpressionAttribute | MdxJsxAttribute]

}



interface MdxJsxExpressionAttribute <: Literal {

  type: 'mdxJsxExpressionAttribute'

}



interface MdxJsxAttribute <: Node {

  type: 'mdxJsxAttribute'

  name: string

  value: MdxJsxAttributeValueExpression | string?

}



interface MdxJsxAttributeValueExpression <: Literal {

  type: 'mdxJsxAttributeValueExpression'

}

```



**MdxJsxElement** represents a JSX element.



The `name` field can be present and represents an identifier.

Without `name`, the element represents a fragment, in which case no attributes

must be present.



The `attributes` field represents information associated with the node.

The value of the `attributes` field is a list of **MdxJsxExpressionAttribute**

and **MdxJsxAttribute** nodes.



**MdxJsxExpressionAttribute** represents an expression (typically in a

programming language) that when evaluated results in multiple attributes.



**MdxJsxAttribute** represents a single attribute.

The `name` field must be present.

The `value` field can be present, in which case it is either a string (a static

value) or an expression (typically in a programming language) that when

evaluated results in an attribute value.



### Content model



###### `FlowContent` (MDX JSX)



```idl

type MdxJsxFlowContent = MdxJsxFlowElement | FlowContent

```



###### `PhrasingContent` (MDX JSX)



```idl

type MdxJsxPhrasingContent = MdxJsxTextElement | PhrasingContent

```



## Types



This package is fully typed with [TypeScript][].

It exports the additional types  [`MdxJsxAttribute`][api-mdx-jsx-attribute],

[`MdxJsxAttributeValueExpression`][api-mdx-jsx-attribute-value-expression],

[`MdxJsxExpressionAttribute`][api-mdx-jsx-expression-attribute],

[`MdxJsxFlowElement`][api-mdx-jsx-flow-element],

[`MdxJsxFlowElementHast`][api-mdx-jsx-flow-element-hast],

[`MdxJsxTextElement`][api-mdx-jsx-text-element],

[`MdxJsxTextElementHast`][api-mdx-jsx-text-element-hast], and

[`ToMarkdownOptions`][api-to-markdown-options].



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.



```js

/**

 * @import {} from 'mdast-util-mdx-jsx'

 * @import {Root} from 'mdast'

 */



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



/** @type {Root} */

const tree = getMdastNodeSomeHow()



visit(tree, function (node) {

  // `node` can now be one of the JSX nodes.

})

```



## 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-jsx@3`,

compatible with Node.js 16.



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

`mdast-util-to-markdown` version 2+.



## Related



* [`micromark/micromark-extension-mdx-jsx`][micromark-extension-mdx-jsx]

  — support MDX JSX in micromark

* [`syntax-tree/mdast-util-mdx`][mdast-util-mdx]

  — support MDX in mdast

* [`remarkjs/remark-mdx`][remark-mdx]

  — support MDX in remark



## Contribute



See [`contributing.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 conduct][coc].

By interacting with this repository, organization, or community you agree to

abide by its terms.



## License



[MIT][license] © [Titus Wormer][author]



[build-badge]: https://github.com/syntax-tree/mdast-util-mdx-jsx/workflows/main/badge.svg



[build]: https://github.com/syntax-tree/mdast-util-mdx-jsx/actions



[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/mdast-util-mdx-jsx.svg



[coverage]: https://codecov.io/github/syntax-tree/mdast-util-mdx-jsx



[downloads-badge]: https://img.shields.io/npm/dm/mdast-util-mdx-jsx.svg



[downloads]: https://www.npmjs.com/package/mdast-util-mdx-jsx



[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=mdast-util-mdx-jsx



[size]: https://bundlejs.com/?q=mdast-util-mdx-jsx



[sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg



[backers-badge]: https://opencollective.com/unified/backers/badge.svg



[collective]: https://opencollective.com/unified



[chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg



[chat]: https://github.com/syntax-tree/unist/discussions



[npm]: https://docs.npmjs.com/cli/install



[esmsh]: https://esm.sh



[license]: license



[author]: https://wooorm.com



[health]: https://github.com/syntax-tree/.github



[contributing]: https://github.com/syntax-tree/.github/blob/main/contributing.md



[support]: https://github.com/syntax-tree/.github/blob/main/support.md



[coc]: https://github.com/syntax-tree/.github/blob/main/code-of-conduct.md



[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c



[typescript]: https://www.typescriptlang.org



[mdast]: https://github.com/syntax-tree/mdast



[mdast-util-to-hast]: https://github.com/syntax-tree/mdast-util-to-hast



[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown



[from-markdown-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension



[mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown



[to-markdown-extension]: https://github.com/syntax-tree/mdast-util-to-markdown#options



[mdast-util-mdx]: https://github.com/syntax-tree/mdast-util-mdx



[program]: https://github.com/estree/estree/blob/master/es2015.md#programs



[dfn-parent]: https://github.com/syntax-tree/mdast#parent



[dfn-content-flow]: #flowcontent-mdx-jsx



[dfn-content-phrasing]: #phrasingcontent-mdx-jsx



[dfn-mixin-mdx-jsx-element]: #mdxjsxelement



[jsx]: https://facebook.github.io/jsx/



[what-is-mdx]: https://mdxjs.com/docs/what-is-mdx/



[micromark-extension-mdx-jsx]: https://github.com/micromark/micromark-extension-mdx-jsx



[syntax]: https://github.com/micromark/micromark-extension-mdx-jsx#syntax



[mdast-util-to-markdown-fences]: https://github.com/syntax-tree/mdast-util-to-markdown#optionsfences



[mdast-util-to-markdown-resourcelink]: https://github.com/syntax-tree/mdast-util-to-markdown#optionsresourcelink



[remark-mdx]: https://mdxjs.com/packages/remark-mdx/



[mdx]: https://mdxjs.com



[api-mdx-jsx-from-markdown]: #mdxjsxfrommarkdown



[api-mdx-jsx-to-markdown]: #mdxjsxtomarkdownoptions



[api-mdx-jsx-attribute]: #mdxjsxattribute



[api-mdx-jsx-attribute-value-expression]: #mdxjsxattributevalueexpression



[api-mdx-jsx-expression-attribute]: #mdxjsxexpressionattribute



[api-mdx-jsx-flow-element]: #mdxjsxflowelement



[api-mdx-jsx-flow-element-hast]: #mdxjsxflowelementhast



[api-mdx-jsx-text-element]: #mdxjsxtextelement



[api-mdx-jsx-text-element-hast]: #mdxjsxtextelementhast



[api-to-markdown-options]: #tomarkdownoptions