micromark-extension-mdx-jsx

What is micromark-extension-mdx-jsx?

The micromark-extension-mdx-jsx package is an extension for micromark that enables parsing and compiling MDX JSX syntax. It allows you to use JSX components within your Markdown files, making it easier to integrate React components and other JSX-based elements into your Markdown content.

What are micromark-extension-mdx-jsx's main functionalities?

JSX Component Parsing

This feature allows you to parse JSX components within your Markdown content. The code sample demonstrates how to use the micromark-extension-mdx-jsx package to parse a simple JSX component and convert it to HTML.

const micromark = require('micromark');
const mdxJsx = require('micromark-extension-mdx-jsx');

const markdown = '<MyComponent prop="value" />';
const html = micromark(markdown, { extensions: [mdxJsx()] });
console.log(html);

Attribute Handling

This feature allows you to handle various types of attributes within JSX components in your Markdown. The code sample shows how to parse a JSX component with multiple attributes, including string and numeric values.

const micromark = require('micromark');
const mdxJsx = require('micromark-extension-mdx-jsx');

const markdown = '<MyComponent prop1="value1" prop2={2} />';
const html = micromark(markdown, { extensions: [mdxJsx()] });
console.log(html);

Nested JSX Components

This feature supports nested JSX components within your Markdown content. The code sample demonstrates how to parse a parent component containing a nested child component.

const micromark = require('micromark');
const mdxJsx = require('micromark-extension-mdx-jsx');

const markdown = '<ParentComponent><ChildComponent /></ParentComponent>';
const html = micromark(markdown, { extensions: [mdxJsx()] });
console.log(html);

Other packages similar to micromark-extension-mdx-jsx

remark-mdx

remark-mdx is a plugin for the remark processor that enables MDX support. It allows you to write JSX within Markdown files and is part of the unified ecosystem. Compared to micromark-extension-mdx-jsx, remark-mdx is more tightly integrated with the remark processor and offers a broader range of plugins for additional functionality.

README

micromark-extension-mdx-jsx

micromark extension to support MDX (or MDX.js) JSX.

This package provides the low-level modules for integrating with the micromark tokenizer but has no handling of compiling to HTML: go to a syntax tree instead.

You should use this with mdast-util-mdx-jsx (mdast). Alternatively, use micromark-extension-mdx with mdast-util-mdx or micromark-extension-mdxjs with mdast-util-mdxjs to support all of MDX (or MDX.js). Or, use it through remark-mdx or remark-mdxjs (remark).

Install

npm:

npm install micromark-extension-mdx-jsx

Use

See mdast-util-mdx-jsx for an example.

API

syntax(options?)

Support MDX (or MDX.js) JSX.

The export of syntax is a function that can be called with options and returns an extension for the micromark parser (to tokenize JSX; can be passed in extensions).

options

options.acorn

Acorn parser to use (Acorn, optional).

options.acornOptions

Options to pass to acorn (Object, default: {ecmaVersion: 2020, locations: true, sourceType: 'module'}). All fields except for locations can be set.

options.addResult

Whether to add an estree field to the mdxTextJsx and mdxFlowJsx tokens with the results from acorn (boolean, default: false).

Syntax

This extensions support both MDX and MDX.js. The first is agnostic to the programming language (it could contain attribute expressions and attribute value expressions with Rust or so), the last is specific to JavaScript (in which case attribute expressions must be spread expressions). To turn on gnostic mode, pass acorn.

The syntax of JSX supported here is described in W3C Backus–Naur form with the following additions:

1. A - B — matches any string that matches A but does not match B.
2. 'string' — same as "string" but with single quotes.
3. BREAK — lookahead match for a block break opportunity (either EOF (end of file), U+000A LINE FEED (LF), U+000D CARRIAGE RETURN (CR), or another JSX tag)

The syntax is defined as follows, however, do note that interleaving (mixing) of markdown and MDX is defined elsewhere, and that the constraints are imposed in mdast-util-mdx-jsx.

; Entries
mdxFlow ::= *spaceOrTab element *spaceOrTab BREAK
mdxText ::= element

element ::= selfClosing | closed
selfClosing ::=
  ; constraint: tag MUST be named, MUST NOT be closing, and MUST be self-closing
  tag
closed ::=
  ; constraint: tag MUST NOT be closing and MUST NOT be self-closing
  tag
  *data
  ; constraint: tag MUST be closing, MUST NOT be self-closing, MUST NOT have
  ; attributes, and either both tags MUST have the same name or both tags MUST
  ; be nameless
  tag

data ::= element | text

tag ::=
  '<' *1closing
  *1(*whitespace name *1attributesAfterIdentifier *1closing)
  *whitespace '>'

attributesAfterIdentifier ::=
  1*whitespace (attributesBoolean | attributesValue) |
  *whitespace attributesExpression |
attributesAfterValue ::=
  *whitespace (attributesBoolean | attributesExpression | attributesValue)
attributesBoolean ::= key *1attributesAfterIdentifier
; Note: in gnostic mode the value of the expression must instead be a single valid ES spread expression
attributesExpression ::= expression *1attributesAfterValue
attributesValue ::= key initializer *1attributesAfterValue

closing ::= *whitespace '/'

name ::= identifier *1(local | members)
key ::= identifier *1local
local ::= *whitespace ':' *whitespace identifier
members ::= member *member
member ::= *whitespace '.' *whitespace identifier

identifier ::= identifierStart *identifierPart
initializer ::= *whitespace '=' *whitespace value
value ::= doubleQuoted | singleQuoted | expression
; Note: in gnostic mode the value must instead be a single valid ES expression
expression ::= '{' *(expressionText | expression) '}'

doubleQuoted ::= '"' *doubleQuotedText '"'
singleQuoted ::= "'" *singleQuotedText "'"

spaceOrTab ::= " " | "\t"
text ::= character - '<' - '{'
whitespace ::= esWhitespace
doubleQuotedText ::= character - '"'
singleQuotedText ::= character - "'"
expressionText ::= character - '{' - '}'
identifierStart ::= esIdentifierStart
identifierPart ::= esIdentifierPart | '-'

; Unicode
; Any unicode code point
character ::=

; ECMAScript
; See “IdentifierStart”: <https://tc39.es/ecma262/#prod-IdentifierStart>
esIdentifierStart ::=
; See “IdentifierPart”: <https://tc39.es/ecma262/#prod-IdentifierPart>
esIdentifierPart ::=
; See “Whitespace”: <https://tc39.es/ecma262/#prod-WhiteSpace>
esWhitespace ::=

Errors

In gnostic mode, expressions are parsed with micromark-extension-mdx-expression, which also throws certain errors.

Unexpected end of file $at, expected $expect

This error occurs for many different reasons if something was opened but not closed (source: micromark-extension-mdx-jsx, rule id: unexpected-eof).

Some examples are:

<
</
<a
<a:
<a.
<a b
<a b:
<a b=
<a b="
<a b='
<a b={
<a/

Unexpected character $at, expected $expect

This error occurs for many different reasons if an unexpected character is seen (source: micromark-extension-mdx-jsx, rule id: unexpected-character).

Some examples are:

<.>
</.>
<a?>
<a:+>
<a./>
<a b!>
<a b:1>
<a b=>
<a/->

Tokens

Many tokens are used:

• mdxJsxFlowTag for the whole JSX tag (<a>)
• mdxJsxTextTag ^
• mdxJsxFlowTagMarker for the tag markers (<, >)
• mdxJsxTextTagMarker ^
• mdxJsxFlowTagClosingMarker for the / marking a closing tag (</a>)
• mdxJsxTextTagClosingMarker ^
• mdxJsxFlowTagSelfClosingMarker for the / marking a self-closing tag (<a/>)
• mdxJsxTextTagSelfClosingMarker ^
• mdxJsxFlowTagName for the whole tag name (a:b in <a:b>)
• mdxJsxTextTagName ^
• mdxJsxFlowTagNamePrimary for the first name (a in <a:b>)
• mdxJsxTextTagNamePrimary ^
• mdxJsxFlowTagNameMemberMarker for the . marking in members (<a.b>)
• mdxJsxTextTagNameMemberMarker ^
• mdxJsxFlowTagNameMember for member names (b in <a:b>)
• mdxJsxTextTagNameMember ^
• mdxJsxFlowTagNamePrefixMarker for the : between primary and local (<a:b>)
• mdxJsxTextTagNamePrefixMarker ^
• mdxJsxFlowTagNameLocal for the local name (b in <a:b>)
• mdxJsxTextTagNameLocal ^
• mdxJsxFlowTagExpressionAttribute for whole expression attributes (<a {...b}>)
• mdxJsxTextTagExpressionAttribute ^
• mdxJsxFlowTagExpressionAttributeMarker for {, } in expression attributes
• mdxJsxTextTagExpressionAttributeMarker ^
• mdxJsxFlowTagExpressionAttributeValue for chunks of what’s inside expression attributes
• mdxJsxTextTagExpressionAttributeValue ^
• mdxJsxFlowTagAttribute for a whole normal attribute (<a b>)
• mdxJsxTextTagAttribute ^
• mdxJsxFlowTagAttributeName for the whole name of an attribute (b:c in <a b:c>)
• mdxJsxTextTagAttributeName ^
• mdxJsxFlowTagAttributeNamePrimary for the first name of an attribute (b in <a b:c>)
• mdxJsxTextTagAttributeNamePrimary ^
• mdxJsxFlowTagAttributeNamePrefixMarker for the : between primary and local (<a b:c>)
• mdxJsxTextTagAttributeNamePrefixMarker ^
• mdxJsxFlowTagAttributeNameLocal for the local name of an attribute (c in <a b:c>)
• mdxJsxTextTagAttributeNameLocal ^
• mdxJsxFlowTagAttributeInitializerMarker for the = between an attribute name and value
• mdxJsxTextTagAttributeInitializerMarker ^
• mdxJsxFlowTagAttributeValueLiteral for a string attribute value (<a b="">)
• mdxJsxTextTagAttributeValueLiteral ^
• mdxJsxFlowTagAttributeValueLiteralMarker for the quotes around a string attribute value (" or ')
• mdxJsxTextTagAttributeValueLiteralMarker ^
• mdxJsxFlowTagAttributeValueLiteralValue for chunks of what’s inside string attribute values
• mdxJsxTextTagAttributeValueLiteralValue ^
• mdxJsxFlowTagAttributeValueExpression for an expression attribute value (<a b={1}>)
• mdxJsxTextTagAttributeValueExpression ^
• mdxJsxFlowTagAttributeValueExpressionMarker for the { and } of expression attribute values
• mdxJsxTextTagAttributeValueExpressionMarker ^
• mdxJsxFlowTagAttributeValueExpressionValue for chunks of what’s inside expression attribute values
• mdxJsxTextTagAttributeValueExpressionValue ^

Related

• micromark/micromark — the smallest commonmark-compliant markdown parser that exists
• micromark/micromark-extension-mdx — micromark extension to support MDX
• micromark/micromark-extension-mdxjs — micromark extension to support MDX.js
• micromark/micromark-extension-mdx-expression — micromark extension to support MDX (or MDX.js) expressions
• micromark/micromark-extension-mdxjs-esm — micromark extension to support MDX.js import/exports
• micromark/micromark-extension-mdx-md — micromark extension to support misc MDX changes
• syntax-tree/mdast-util-mdx — mdast utility to support all of MDX
• syntax-tree/mdast-util-mdxjs — mdast utility to support all of MDX.js

Contribute

See contributing.md in micromark/.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