spec.txt

# MDX

> 🪦 **Archived**: this document is not maintained.
> This document was made jointly with `micromark`,
> which was later also turned into `markdown-rs`.
> At present,
> I don’t have the bandwidth to maintain 2 reference parsers
> *and* a spec.

> Markdown 💛 JSX

> This document is currently in progress.
> See also [micromark][], [cmsm][], and [mdxjs][].

## Contents

## Background

### What is MDX?

MDX is the combination of [Markdown][commonmark] with [JSX][].
This document defines a syntax for MDX (without JavaScript, [MDXjs][] does
that) by describing how to parse it.

### Who created MDX?

The idea of combining [Markdown][commonmark], [JavaScript][], and [JSX][] was
a collaborative effort by [Guillermo Rauch][mdx-rauchg] (**[@rauchg][]**),
[James K. Nelson][mdx-jamesknelson] (**[@jamesknelson][]**), [John
Otander][mdx-johno] (**[@johno][]**), Tim Neutkens (**[@timneutkens][]**),
Brent Jackson (**[@jxnblk][]**), Jessica Stokes (**[@ticky]**), and more.
Markdown was [created by John Gruber][md] (**[@gruber][]**).
[CommonMark by John McFarlane et al.][commonmark] (**[@jgm][]**) is a popular
variant.
JSX was [created by Sebastian Markbåge et al.][jsx] (**[@sebmarkbage][]**) at
Facebook, Inc.

### Why MDX?

Markdown does not have a syntax for custom components.
MDX solves this.

There are many languages objectively better than Markdown, however, Markdown
is great because:

*   It looks like what it means and is relatively easy to read
*   Although images are [confusing][], most stuff is relatively simple to write
*   It’s loose and ambiguous: it may not work but you won’t get an error (great
    for someone posting a comment to a forum if they forgot an asterisk)

Markdown *does* have a way to extend it, HTML, but that has drawbacks:

*   HTML in Markdown is naïve, how it’s parsed sometimes doesn’t make sense
*   HTML is unsafe by default, so it’s sometimes (partially) unsupported
*   HTML and Markdown don’t mix well, resulting in confusing rules such as
    blank lines or `markdown="1"` attributes
*   HTML is coupled with browsers, Markdown is useful for other things too

The frontend world has an alternative to HTML: JSX.
JSX is great, amongst other things, because:

*   It has a relatively familiar syntax (like XML)
*   It’s agnostic to semantics and intended for compilers (can have any
    domain-specific meaning)
*   It’s strict and unambiguous (great if an editor forgot a slash somewhere, as
    they’ll get an error early, instead of a book going to print with broken
    stuff in it)

## Overview

This document first talks about the MDX syntax for authors, in the following
section.
Further sections define the syntax in-depth and for developers.
The appendix includes sections on notable differences from Markdown and JSX,
and a list of common MDX gotchas.

## MDX

This section explains MDX for authors.

### Hello World

The smallest MDX example looks like this:

```markdown
# Hello, world!
```

It displays a heading saying “Hello, world!” on the page.
With MDX you can add components:

```jsx
<MyComponent># Hello, world!</MyComponent>
```

MDX syntax can be boiled down to being JSX in Markdown.
It’s a superset of Markdown syntax that supports JSX.

### Markdown

Traditionally, Markdown is used to generate HTML.
Many developers like writing markup in Markdown as it often looks more like
what’s intended and it is typically terser.
Instead of the following HTML:

```html
<blockquote>
  <p>A block quote with <em>some</em> emphasis.</p>
</blockquote>
```

You can write the equivalent in Markdown (or MDX) like so:

```markdown
> A block quote with _some_ emphasis.
```

Markdown is good for **content**.
MDX supports [most standard Markdown syntax][markdown-deviations].
It’s important to understand Markdown in order to learn MDX.

### JSX

Recently, more and more developers have started using [JSX][] to generate HTML
markup.
JSX is typically combined with a frontend framework like React or Vue.
These frameworks add support for components, which let you change repeating
things like the following markup:

```html
<h2>Hello, Venus!</h2>
<h2>Hello, Mars!</h2>
```

…to JSX (or MDX) like this:

```jsx
<Welcome name="Venus" />
<Welcome name="Mars" />
```

JSX is good for **components**.
It makes repeating things more clear and allows for separation of concerns.
MDX supports [most standard JSX syntax][jsx-deviations].

### MDX

MDX is the combination of Markdown and JSX, for example, like so:

````mdx
<MyComponent>> Block quote</MyComponent>

<MyCodeComponent>
  ```html
  <!doctype html>
  ```
</MyCodeComponent>

<MyOtherComponent>
  # Heading<Footnote id="1" />

  - List
  - Items
</MyOtherComponent>

<Image
  alt='Photo of Lilo sitting in a tiny box'
  src='lilo.png'
/>

<also-component {attribute expression} />

<math value={attribute value expression} />

{
  block expression
}

The sum of `1 + 1` as calculated by an inline expression is {1 + 1}.
````

### Syntax

The syntax of MDX within Markdown is formally defined by how to parse in [§ 4
Parsing][parsing] and in further sections, relatively formally in [§ 7.1
Syntax][syntax]), and informally by example here.

As MDX is not tied to HTML or JavaScript, the following examples do not show
output examples in HTML, but instead show whether they are okay, or whether they
crash.

For ease of reading, block elements will be capitalized, whereas span elements
will be lowercase, in the following examples.
But, casing does not affect parsing.

#### Block

A block of MDX is an element or expression that is both the first thing on its
opening line, and the last thing on its closing line.

A self-closing block tag:

```mdx
<Component />
```

The start and end can be on different lines:

```mdx
<Component
/>
```

An arbitrary number of lines can be between the start and end:

```mdx
<Component

/>
```

This also applies to elements with opening and closing tags:

```mdx
<Component>


</Component>
```

Expressions can also be blocks:

```mdx
{


}
```

Parent containers of components don’t count when figuring out if something is
the first or last thing, such as in a block quote, a list, or in another block
component:

```mdx
> <Component />

- <Component />

<Parent>
  <Child />
</Parent>
```

#### Span

A span of MDX is an element or expression that is not a block: it’s either not
the first thing, or the last thing, or both:

```mdx
This span is preceded by other things: <component />

<component /> This span is followed by other things.

These rules also apply to expressions ({ such as this one }).
```

#### Content

An MDX block element can contain further Markdown blocks, whereas an MDX span
element can contain further Markdown spans.

On a single line:

```mdx
<Component>> Block quote</Component>
```

With generous whitespace:

```mdx
<Component>
> Block quote
</Component>
```

With indentation:

```mdx
<Component>
  > Block quote
</Component>
```

Spans cannot contain blocks:

```mdx
<component>> this is not a block quote</component>, because it’s not in a block
element.

Nor is this a <component># heading</component>
```

Blocks will create paragraphs:

```mdx
<Component>**Strongly important paragraph in a component**.</Component>

This <component>**is strongly important text in a component**</component> in a
paragraph.
```

Which gets a bit confusing if you are expected HTML semantics (to MDX, elements
don’t have semantics, so `h2` has no special meaning):

```mdx
<h2>And this is a paragraph in a heading!</h2>
```

MDX expressions can contain arbitrary data, with the exception that there must
be a matching number opening braces (c:{) and closing braces (c:}):

```mdx
{
  This is a fine expression: no opening or closing braces
}

So is this: {{{}}}.

And this, an expression with extra closing braces after it: {}}}.
```

This example is incorrect, as there are not enough closing braces:

```mdx
{{{}.
```

#### Closing MDX

MDX elements and expressions must be closed, and what closes them must be in an
expected place:

This example is incorrect, an unclosed tag:

```mdx
<Component>
```

This example is incorrect, because the “closing” tag is in fenced code.

````mdx
<Component>

```js
</Component>
```
````

This example is incorrect, because the “closing” tag is outside of the block
quote:

```mdx
> <Component>

</Component>
```

This example is incorrect, because the “closing” tag is not in the paragraph:

```mdx
A span component <component>

</component>
```

This example is incorrect, because the “closing” tag is in a different
paragraph:

```mdx
<component>This is one paragraph, with an inline opening tag.

This is another paragraph, with an inline closing tag</component>.
```

The same rules apply to expressions:

```mdx
{This is all fine…

…but because there is a dot after the closing brace, it’s not a block, which
results in two paragraphs, which means that the first paragraph has an unclosed
expression}.
```

#### Attributes

MDX elements can have three types of attributes.

Attribute expressions:

```mdx
<Component {attribute expression} />
```

Boolean attributes:

```mdx
<Component boolean another />
```

Or initialized attributes, with a value.

```mdx
<Component key="value" other="more" />
```

Attribute values can also use single quotes:

```mdx
<Component quotes='single quotes: also known as apostrophes' />
```

Finally, attribute value expressions can be used with braces:

```mdx
<Component data={attribute value expression} />
```

#### Names

Element names are optional, which is a feature called “fragments”:

```mdx
<>Fragment block with a paragraph</>

A <>fragment span</> in a paragraph.
```

The syntax of the name of an element follows the syntax of variables in
JavaScript, and dashes are also allowed (but not at the start):

```mdx
This is fine: <π />.

Also fine: <a‌b /> (there’s a zero-width non-joiner in there).

Dashes are <c-d /> fine too!
```

Names can be prefixed with a namespace using a colon:

```mdx
<svg:rect />
```

Similar to namespaces, dots can be used to access methods from objects:

```mdx
<org.acme.example />
```

(Namespaces and methods cannot be combined).

#### Keys

Similar to names, keys of attributes also follow the same syntax as JavaScript
variables, and dashes are also allowed:

```mdx
This is all fine: <x π a‌b c-d />.
```

And namespaces can also be used:

```mdx
This is all fine: <z xml:lang="de" />.
```

(Methods don’t work for keys).

#### Whitespace

Whitespace is mostly optional, except between two identifiers (such as the
name and a key, or between two keys):

```mdx
This is fine: <x/>.
Also fine: <x{attribute expression}/>.
Fine too: <v w=""x=''y z/>.
```

Most places accept whitespace:

```mdx
A bit much, but sure: < w / >.
< x >Go ahead< / x >
< z do your = 'thing' >
```

## Parsing

The states of the [MDX state machine][] have certain effects, such as that they
create tokens in the [stack][] and [consume][] characters.
The purpose of the state machine is to tokenize.
The stack is used by adapters.

The [MDX adapter][] handles tokens, which has further effects, such as
validating whether they are conforming and figuring out when parsing is done.
The purpose of the adapter is to handle the results of the tokenizer.

To parse MDX is to feed the [input character][] to the [state][] of the state
machine, and when not [settled][], repeat this step.

If parsing [crashed][] with a label the content is nonsensical and the document
cannot be processed.
Without label, no MDX was found.

How MDX, whether it’s found or not, is handled is intentionally undefined and
left up to the host parser.
When to feed an [c:EOF] is similarly undefined.

Host parsers must not support indented code and autlinks, as those conflict with
MDX.

### Characters

A character is a Unicode code point and is represented as a four to six digit
hexadecimal number, prefixed with `U+` (**\[UNICODE]**).

#### Character groups

[Whitespace](#) is any character defined as [`WhiteSpace`][es-whitespace]
(**\[JavaScript]**).

[Identifier start](#) is any character defined as
[`IdentifierStart`][es-identifier-start], with the restriction that unicode
escape sequences do not apply (**\[JavaScript]**).

[Identifier](#) is any character defined as
[`IdentifierPart`][es-identifier-part], with the restriction that unicode escape
sequences do not apply (**\[JavaScript]**).

#### Conceptual characters

An [c:EOF](#) character is a conceptual character (as in, not real character)
representing the lack of any further characters in the input.

### Infra

The [input stream](#) consists of the characters pushed into it.

The [input character](#) is the first character in the [input stream][] that has
not been consumed.
Initially, the input character is the first character in the input.
Finally, when all character are consumed, the input character is an [c:EOF][].

The [stack](#) is a list of tokens that are open, initially empty.
The [current token](#) is the last token in the [stack][].

The [value](#) of a token are all characters in the [input stream][] from where
the token was [enter][]ed (including) to where it [exit][]ed (excluding).

The [element stack](#) is a list of elements that are open, initially empty.
The [current element](#) is the last element in the [element stack][].

[Settled](#) is used to signal when parsing is done, whether it was a success
or not, and is initially off.
[Crashed](#) is used to signal when parsing is unsuccessful, and is initially
off.

The [state](#) is the way a character is handled.

A variable is declared with `let`, cleared with `unset`, or changed with
`set` (to set a value), `increment` (to add a numeric value), `decrement` (to
subtract a numeric value), `append` (to add a string value), `push` (to add a
value to a list), or `pop` (to remove a value from the end of a list).

Which values are used are left to the host programming language, but this
definition requires compatibility with **\[JSON]** for primitives (strings,
numbers, booleans, and null) and structured types (objects and arrays).

The [shared space](#) is an object.
`size`, `sizeOpen`, `currentAttribute`, and `currentTag` are variables in the
[shared space][].
These variables are available globally to all states and adapters.
Other variables are available locally to a state or adapter and not shared.

To [dedent](#) is to remove up to X initial c:HT or c:SP characters from each
non-initial line in the given value, where X is the minimum number of c:HT or
c:SP characters of all non-initial lines that contain other characters.

To [decode](#) is to parse character references as defined in “Character
reference state” of § 12.2 Parsing HTML documents (**\[HTML]**).

### Effects

The [MDX state machine][] and [MDX adapter][] have certain common effects.

#### Switch

To [switch](#) to a state is to wait for a character in the given state.

#### Consume

To [consume](#) the [input character][] is to move on from it to the next
character in the [input stream][].

#### Enter

To [enter](#) a token is to push a new token of the given type to the [stack][],
making it the [current token][].

#### Exit

To [exit](#) is to pop the [current token][] from the [stack][].

#### Done

[Done](#) is used to mark parsing as [settled][].

#### Crash

[Crash](#) is used to mark parsing as [settled][] and [crashed][].
When crashing with a given label, crashing causes a parse error.

## State machine

The [MDX state machine](#) is used to tokenize MDX blocks and MDX spans.
Blocks (also known as flow) make up the structure of the document (such as
headings), whereas spans (also known as text or inline) make up the
intra-paragraph parts of the flow (such as emphasis).

The initial state varies based on whether flow or text is parsed, and is
respectively either s:before-mdx-block or s:before-mdx-span.

The final state is switched to by the [MDX adapter][], which right before
completion will [switch][] to either s:after-mdx-block or s:after-mdx-span.

### Before MDX block state

*   ↪ **c:HT**\
    ↪ **c:SP**

    [Consume][]
*   ↪ **Anything else**

    [Switch][] to s:before-mdx-span

### Before MDX span state

*   ↪ **c:<**\
    ↪ **c:{**

    [Switch][] to s:data
*   ↪ **Anything else**

    [Crash][]

### After MDX block state

*   ↪ **c:HT**\
    ↪ **c:SP**

    [Consume][]
*   ↪ **[c:EOF][]**\
    ↪ **c:LF**\
    ↪ **c:CR**

    [Done][]
*   ↪ **Anything else**

    [Crash][]

### After MDX span state

[Done][]

### Data state

*   ↪ **c:<**

    [Switch][] to s:before-name, [enter][] `'tag'`, and [consume][]
*   ↪ **c:{**

    [Switch][] to s:expression, [enter][] `'expression'`, let `size` be `1`, and
    [consume][]
*   ↪ **Anything else**

    [Switch][] to s:text and [enter][] `'text'`

### Before name state

*   ↪ **c:/**

    [Switch][] to s:before-closing-tag-name, [enter][] `'closingSlash'`,
    [consume][], and [exit][]
*   ↪ **c:>**

    [Switch][] to s:data, [enter][] `'name'`, [exit][], [consume][], and
    [exit][]
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **[Identifier start][]**

    [Switch][] to s:primary-name, [enter][] `'name'`, [enter][] `'primaryName'`,
    and [consume][]
*   ↪ **Anything else**

    [Crash][] `'before name'`

### Before closing tag name state

*   ↪ **c:>**

    [Switch][] to s:data, [enter][] `'name'`, [exit][], [consume][], and
    [exit][]
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **[Identifier start][]**

    [Switch][] to s:primary-name, [enter][] `'name'`, [enter][] `'primaryName'`,
    and [consume][]
*   ↪ **Anything else**

    [Crash][] `'before name'`

### Primary name state

*   ↪ **c:-**\
    ↪ **[Identifier][]**

    [Consume][]
*   ↪ **c:.**\
    ↪ **c:/**\
    ↪ **c::**\
    ↪ **c:>**\
    ↪ **c:{**\
    ↪ **[Whitespace][]**

    [Switch][] to s:after-primary-name and [exit][]
*   ↪ **Anything else**

    [Crash][] `'in name'`

### After primary name state

*   ↪ **c:.**

    [Switch][] to s:before-member-name and [consume][]
*   ↪ **c::**

    [Switch][] to s:before-local-name and [consume][]
*   ↪ **c:/**\
    ↪ **c:>**\
    ↪ **c:{**\
    ↪ **[Identifier start][]**

    [Switch][] to s:before-attribute and [exit][]
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **Anything else**

    [Crash][] `'after name'`

### Before member name state

*   ↪ **[Identifier start][]**

    [Switch][] to s:member-name, [enter][] `'memberName'`, and [consume][]
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **Anything else**

    [Crash][] `'before member name'`

### Member name state

*   ↪ **c:-**\
    ↪ **[Identifier][]**

    [Consume][]
*   ↪ **c:.**\
    ↪ **c:/**\
    ↪ **c:>**\
    ↪ **c:{**\
    ↪ **[Whitespace][]**

    [Switch][] to s:after-member-name and [exit][]
*   ↪ **Anything else**

    [Crash][] `'in member name'`

### After member name state

*   ↪ **c:.**

    [Switch][] to s:before-member-name and [consume][]
*   ↪ **c:/**\
    ↪ **c:>**\
    ↪ **c:{**\
    ↪ **[Identifier start][]**

    [Switch][] to s:before-attribute and [exit][]
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **Anything else**

    [Crash][] `'after member name'`

### Before local name state

*   ↪ **[Identifier start][]**

    [Switch][] to s:local-name, [enter][] `'localName'`, and [consume][]
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **Anything else**

    [Crash][] `'before local name'`

### Local name state

*   ↪ **c:-**\
    ↪ **[Identifier][]**

    [Consume][]
*   ↪ **c:/**\
    ↪ **c:>**\
    ↪ **c:{**\
    ↪ **[Whitespace][]**

    [Switch][] to s:after-local-name, [exit][], and [exit][]
*   ↪ **Anything else**

    [Crash][] `'in local name'`

### After local name state

*   ↪ **c:/**\
    ↪ **c:>**\
    ↪ **c:{**\
    ↪ **[Identifier start][]**

    [Switch][] to s:before-attribute
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **Anything else**

    [Crash][] `'after local name'`

### Before attribute state

*   ↪ **c:/**

    [Switch][] to s:self-closing, [enter][] `'selfClosingSlash'`, [consume][],
    and [exit][]
*   ↪ **c:>**

    [Switch][] to s:data, [consume][], and [exit][]
*   ↪ **c:{**

    [Switch][] to s:attribute-expression, [enter][] `'attributeExpression'`, let
    `size` be `1`, and [consume][]
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **[Identifier start][]**

    [Switch][] to s:attribute-name, [enter][] `'attributeName'`, and [consume][]
*   ↪ **Anything else**

    [Crash][] `'before attribute name'`

### Attribute expression state

*   ↪ **[c:EOF][]**

    [Crash][] `'in attribute expression'`
*   ↪ **c:{**

    Increment `size` by `1` and [consume][]
*   ↪ **c:}**

    If `size` is:

    *   ↪ **`1`**

        [Switch][] to s:before-attribute, unset `size`, [consume][], and
        [exit][]
    *   ↪ **Anything else**

        Decrement `size` by `1` and [consume][]
*   ↪ **Anything else**

    [Consume][]

### Attribute name state

*   ↪ **c:-**\
    ↪ **[Identifier start][]**

    [Consume][]
*   ↪ **c:/**\
    ↪ **c::**\
    ↪ **c:=**\
    ↪ **c:>**\
    ↪ **c:{**\
    ↪ **[Whitespace][]**

    [Switch][] to s:after-attribute-name and [exit][]
*   ↪ **Anything else**

    [Crash][] `'in attribute name'`

### After attribute name state

*   ↪ **c::**

    [Switch][] to s:before-attribute-local-name and [consume][]
*   ↪ **c:=**

    [Switch][] to s:before-attribute-value and [consume][]
*   ↪ **c:/**\
    ↪ **c:>**\
    ↪ **c:{**\
    ↪ **[Identifier start][]**

    [Switch][] to s:before-attribute
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **Anything else**

    [Crash][] `'after attribute name'`

### Before attribute local name state

*   ↪ **[Identifier start][]**

    [Switch][] to s:attribute-local-name, [enter][] `'attributeLocalName'`, and
    [consume][]
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **Anything else**

    [Crash][] `'before local attribute name'`

### Attribute local name state

*   ↪ **c:-**\
    ↪ **[Identifier start][]**

    [Consume][]
*   ↪ **c:/**\
    ↪ **c:=**\
    ↪ **c:>**\
    ↪ **c:{**\
    ↪ **[Whitespace][]**

    [Switch][] to s:after-attribute-local-name and [exit][]
*   ↪ **Anything else**

    [Crash][] `'in local attribute name'`

### After attribute local name state

*   ↪ **c:=**

    [Switch][] to s:before-attribute-value and [consume][]
*   ↪ **c:/**\
    ↪ **c:>**\
    ↪ **c:{**\
    ↪ **[Identifier start][]**

    [Switch][] to s:before-attribute
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **Anything else**

    [Crash][] `'after local attribute name'`

### Before attribute value state

*   ↪ **c:"**

    [Switch][] to s:attribute-value-double-quoted, [enter][] `'attributeValue'`,
    and [consume][]
*   ↪ **c:'**

    [Switch][] to s:attribute-value-single-quoted, [enter][] `'attributeValue'`,
    and [consume][]
*   ↪ **c:{**

    [Switch][] to s:attribute-value-expression, [enter][]
    `'attributeValueExpression'`, let `size` be `1`, and [consume][]
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **Anything else**

    [Crash][] `'before attribute value'`

### Attribute value double quoted state

*   ↪ **[c:EOF][]**

    [Crash][] `'in attribute value'`
*   ↪ **c:"**

    [Switch][] to s:before-attribute, [consume][], and [exit][]
*   ↪ **Anything else**

    [Consume][]

### Attribute value single quoted state

*   ↪ **[c:EOF][]**

    [Crash][] `'in attribute value'`
*   ↪ **c:'**

    [Switch][] to s:before-attribute, [consume][], and [exit][]
*   ↪ **Anything else**

    [Consume][]

### Attribute value expression state

*   ↪ **[c:EOF][]**

    [Crash][] `'in attribute value expression'`
*   ↪ **c:{**

    Increment `size` by `1` and [consume][]
*   ↪ **c:}**

    If `size` is:

    *   ↪ **`1`**

        [Switch][] to s:before-attribute, unset `size`, [consume][], and
        [exit][]
    *   ↪ **Anything else**

        Decrement `size` by `1` and [consume][]
*   ↪ **Anything else**

    [Consume][]

### Self-closing state

*   ↪ **c:>**

    [Switch][] to s:data, [consume][], and [exit][]
*   ↪ **[Whitespace][]**

    [Consume][]
*   ↪ **Anything else**

    [Crash][] `'after self-closing slash'`

### Expression state

*   ↪ **[c:EOF][]**

    [Crash][] `'in attribute value expression'`
*   ↪ **c:{**

    Increment `size` by `1` and [consume][]
*   ↪ **c:}**

    If `size` is:

    *   ↪ **`1`**

        [Switch][] to s:data, unset `size`, [consume][], and [exit][]
    *   ↪ **Anything else**

        Decrement `size` by `1` and [consume][]
*   ↪ **Anything else**

    [Consume][]

### Text state

*   ↪ **[c:EOF][]**

    [Crash][] `'in element'`
*   ↪ **c:<**\
    ↪ **c:{**

    [Switch][] to s:data and [exit][]
*   ↪ **c:`**

    [Switch][] to s:accent-quoted-open, let `sizeOpen` be `1`, and [consume][]
*   ↪ **c:~**

    [Switch][] to s:tilde-quoted-open, let `sizeOpen` be `1`, and [consume][]
*   ↪ **Anything else**

    [Consume][]

### Accent quoted open state

*   ↪ **[c:EOF][]**

    [Crash][] `'in code'`
*   ↪ **c:`**

    Increment `sizeOpen` by `1` and [consume][]
*   ↪ **Anything else**

    [Switch][] to s:accent-quoted and [consume][]

### Accent quoted state

*   ↪ **[c:EOF][]**

    [Crash][] `'in code'`
*   ↪ **c:`**

    [Switch][] to s:accent-quoted-close, let `size` be `1`, and [consume][]
*   ↪ **Anything else**

    [Consume][]

### Accent quoted close state

*   ↪ **c:`**

    Increment `sizeOpen` by `1` and [consume][]
*   ↪ **Anything else**

    If `size` is:

    *   ↪ **`sizeOpen`**

        [Switch][] to s:text, unset `sizeOpen`, and unset `size`
    *   ↪ **Anything else**

        [Switch][] to s:accent-quoted and unset `size`

### Tilde quoted open state

*   ↪ **[c:EOF][]**

    [Crash][] `'in code'`
*   ↪ **c:~**

    Increment `sizeOpen` by `1` and [consume][]
*   ↪ **Anything else**

    [Switch][] to s:tilde-quoted and [consume][]

### Tilde quoted state

*   ↪ **[c:EOF][]**

    [Crash][] `'in code'`
*   ↪ **c:~**

    [Switch][] to s:tilde-quoted-close, let `size` be `1`, and [consume][]
*   ↪ **Anything else**

    [Consume][]

### Tilde quoted close state

*   ↪ **c:~**

    Increment `sizeOpen` by `1` and [consume][]
*   ↪ **Anything else**

    If `size` is:

    *   ↪ **`sizeOpen`**

        [Switch][] to s:text, unset `sizeOpen`, and unset `size`
    *   ↪ **Anything else**

        [Switch][] to s:tilde-quoted and unset `size`

## Adapter

The [MDX adapter](#) handles tokens from the [MDX state machine], which has
further effects, such as validating whether they are conforming and figuring out
when parsing is done.

Adapters are defined to handle a token either when a token [enter][]s right
before it’s pushed to the stack, or when a token [exit][]s right after it’s
popped off the stack.

The adapters does not define how to construct a syntax tree, but does provide
the essentials for that.
Constructing syntax trees, whether abstract or concrete, is intentionally
undefined.

### Enter `'tag'` adapter

1.  Let `currentTag` be a new object
1.  Let `name` of `currentTag` be `null`
1.  Let `close` of `currentTag` be `false`
1.  Let `selfClosing` of `currentTag` be `false`

### Enter `'closingSlash'` adapter

If there is no [current element][], [crash][] `'before name'` (**note**: a
closing tag with no open elements)

### Enter `'attributeExpression'` adapter

If `close` of `currentTag` is `true`, [crash][] `'on closing tag after name'`
(**note**: a closing tag with an attribute)

### Enter `'attributeName'` adapter

If `close` of `currentTag` is `true`, [crash][] `'on closing tag after name'`
(**note**: a closing tag with an attribute)

### Enter `'selfClosingSlash'` adapter

If `close` of `currentTag` is `true`, [crash][] `'on closing tag before tag
end'` (**note**: a self-closing closing tag)

### Exit `'closingSlash'` adapter

Let `close` of `currentTag` be `true`

### Exit `'primaryName'` adapter

Let `name` of `currentTag` be the [value][] of [current token][]

### Exit `'memberName'` adapter

Append c:. and the [value][] of [current token][] to `name` of `currentTag`

### Exit `'localName'` adapter

Append c:: and the [value][] of [current token][] to `name` of `currentTag`

### Exit `'name'` adapter

If `close` of `currentTag` is `true` and `name` of `currentTag` is not the same
as `name` of [current element][], [crash][] `'on closing tag after name'`
(**note**: mismatched tags)

### Exit `'attributeName'` adapter

1.  Let `currentAttribute` be a new object
1.  Let `name` of `currentAttribute` be the [value][] of [current token][]
1.  Let `value` of `currentAttribute` be `null`

### Exit `'attributeLocalName'` adapter

Append c:: and the [value][] of [current token][] to `name` of
`currentAttribute`

### Exit `'attributeValue'` adapter

Let `value` of `currentAttribute` be the [decode][]d [value][], excluding its
first and last characters, of [current token][]

### Exit `'attributeValueExpression'` adapter

Let `value` of `currentAttribute` be the [dedent][]ed [value][], excluding its
first and last characters, of [current token][]

### Exit `'attributeExpression'` adapter

1.  Let `currentAttribute` be a new object
1.  Let `type` of `currentAttribute` be `'mdxAttributeExpression'`
1.  Let `value` of `currentAttribute` be the [dedent][]ed [value][], excluding
    its first and last characters, of [current token][]

### Exit `'selfClosingSlash'` adapter

Let `selfClosing` of `currentTag` be `true`

### Exit `'tag'` adapter

> **Note**: if there is no [current element][], the [input character][] is the
> start of the element’s content.
> If `close` of `currentTag` is `true`, and there is a single value in
> the [element stack][], the first character of the token is the end of the
> element’s content.
> The content should be parsed further by the host parser to find nested MDX
> constructs.

1.  If `close` of `currentTag` is `true`, pop the [current element] from the
    [element stack][]
1.  Otherwise, if `selfClosing` of `currentTag` is `false`, push `currentTag` to
    the [element stack][]

Finally, if there is no [current element][], [switch][] to either
s:after-mdx-block or s:after-mdx-span, based on whether flow or text is parsed.

### Exit `'expression'` adapter

> **Note**: if there is no [current element][], the first character after the
> start of the token is the start of the expression’s content, and the last
> character before the end of the token is the end of the expression’s content.
> The content could be parsed by the host parser.

If there is no [current element][], [switch][] to either s:after-mdx-block or
s:after-mdx-span, based on whether flow or text is parsed.

## Appendix

### Syntax

The syntax of MDX is described in [W3C Backus–Naur form][w3c-bnf] 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
    [c:EOF][], c:LF, or c:CR)

The syntax of MDX is defined as follows, however, do note that interleaving
(mixing) of Markdown and MDX is defined elsewhere.

<!--syntax-->

### Deviations from Markdown

MDX adds constructs to Markdown but also prohibits certain normal Markdown
constructs.

#### HTML

Whether block or inline, HTML in Markdown is not supported.

Character data, processing instructions, declarations, and comments are not
supported at all.
Instead of HTML elements, use JSX elements.

Incorrect:

```markdown
# Hello, <span style=color:red>world</span>!
<!--To do: add message-->
<img>
```

Correct:

```markdown
# Hello, <span style='color:red'>world</span>!
<img />
```

#### Indented code

Indentation to create code blocks is not supported.
Instead, use fenced code blocks.

The reason for this change is so that elements can be indented.

Incorrect:

```markdown
    console.log(1)
```

Correct:

````markdown
```js
console.log(1)
```
````

#### Autolinks

Autolinks are not supported.
Instead, use links or references.

The reason for this change is because whether something is an element (whether
HTML or JSX) or an autolink is ambiguous (Markdown normally treats `<svg:rect>`,
`<xml:lang/>`, or `<svg:circle{...props}>` as links).

Incorrect:

```markdown
See <https://example.com> for more information
```

Correct:

```markdown
See [example.com](https://example.com) for more information.
```

#### Errors

Whereas all Markdown is valid, incorrect MDX will crash.

### Deviations from JSX

MDX removes certain constructs from JSX, because JSX is typically mixed with
JavaScript whereas MDX is usable without it.

#### Comments

JavaScript comments in JSX are not supported.

Incorrect:

```jsx
<hi/*comment!*//>
<hello// comment!
/>
```

Correct:

```jsx
<hi/>
<hello
/>
```

#### Element or fragment attribute values

JSX elements or JSX fragments as attribute values are not supported.

The reason for this change is that it would be confusing whether Markdown would
work.

Incorrect:

```jsx
<welcome name=<>Venus</> />
<welcome name=<span>Pluto</span> />
```

Correct:

```jsx
<welcome name='Mars' />
```

#### c:> and c:} are fine

JSX does not allow c:> or c:} literally in text, they need to be encoded as
character references.
There is no good reason for this (some JSX parsers agree with us and don’t crash
either).
In Markdown, c:> is used to start a block quote.
Therefore, in MDX, c:> and c:} are fine literally and don’t need to be encoded.

#### Expressions

JSX allows valid JavaScript inside expressions.
We support *anything* in braces.
Because JSX parses JavaScript, it knows when it sees a c:} whether it means the
end of the expression, or if there is more JavaScript after it.
As we don’t parse JavaScript, but do want to allow further braces in
expressions, we count opening braces (c:{) and expect just as many closing
braces (c:}) in expressions.

Incorrect:

```jsx
<punctuation
  data={{
    '{': false // Left curly brace
  }}
/>
```

Correct:

```jsx
<punctuation
  data={{
    '{': false, // Left curly brace
    '}': false // Right curly brace
  }}
/>
```

### Common MDX gotchas

Markdown *first* looks for blocks (such as a heading) and only later looks for
spans (such as emphasis) in those blocks.

This becomes a problem typically in the two cases listed below.
However, as MDX has parse errors, parsing will crash, and an error will be
presented.

#### Blank lines in JSX spans

Incorrect:

```markdown
The plot for the movie was, <span>wait for it…

…that she didn’t die!</span>
```

Correct:

```markdown
The plot for the movie was, <span>wait for it…
…that she didn’t die!</span>
```

#### c:> seen as block quote

Incorrect:

```markdown
Here’s a cute photo of my cat: <Image
  alt='Photo of Lilo sitting in a tiny box'
  src='lilo.png'
  /
>
```

Correct:

```markdown
Here’s a cute photo of my cat: <Image alt='Photo of Lilo sitting in a tiny box' src='lilo.png' />
```

Or as a block (c:> is fine in JSX blocks):

```markdown
Here’s a cute photo of my cat:

<Image
  alt='Photo of Lilo sitting in a tiny box'
  src='lilo.png'
  /
>
```

## References

*   **\[Markdown]**:
    [CommonMark][].
    J. MacFarlane, et al.
*   **\[HTML]**:
    [HTML standard][html].
    A. van Kesteren, et al.
    WHATWG.
*   **\[JavaScript]**:
    [ECMAScript language specification][javascript].
    Ecma International.
*   **\[JSON]**:
    [The JavaScript Object Notation (JSON) Data Interchange Format][json].
    T. Bray.
    IETF.
*   **\[UNICODE]**:
    [The Unicode standard][unicode].
    Unicode Consortium.

## Acknowledgments

Thanks to Gatsby, Inc. for funding the work to define MDX further.

## License

Copyright © 2020 Titus Wormer.
This work is licensed under a
[Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/).

<!--Definitions-->

[html]: https://html.spec.whatwg.org/multipage/

[javascript]: https://tc39.es/ecma262/

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

[json]: https://tools.ietf.org/html/rfc7159

[commonmark]: https://commonmark.org

[unicode]: https://www.unicode.org/versions/

[confusing]: https://twitter.com/gruber/status/1246489863932821512

[es-whitespace]: https://tc39.es/ecma262/#prod-WhiteSpace

[es-identifier-start]: https://tc39.es/ecma262/#prod-IdentifierStart

[es-identifier-part]: https://tc39.es/ecma262/#prod-IdentifierPart

[mdx-rauchg]: https://spectrum.chat/frontend/general/mdx-proposal~1021be59-2738-4511-aceb-c66921050b9a

[mdx-jamesknelson]: https://github.com/frontarm/mdx-util/tree/0f5f6d62bac4b83edc4bc3890dde3011079fa318

[mdx-johno]: https://github.com/mdx-js/mdx/tree/a96ede2c104084ae21efa8bd95319011e558ec9d

[md]: https://daringfireball.net/2004/03/introducing_markdown

[rauchg]: https://github.com/rauchg

[jamesknelson]: https://github.com/jamesknelson

[johno]: https://github.com/johno

[timneutkens]: https://github.com/timneutkens

[jxnblk]: https://github.com/jxnblk

[ticky]: https://github.com/ticky

[gruber]: https://github.com/gruber

[jgm]: https://github.com/jgm

[sebmarkbage]: https://github.com/sebmarkbage

[w3c-bnf]: https://www.w3.org/Notation.html

[mdxjs]: https://mdxjs.com

[micromark]: https://github.com/micromark/micromark

[cmsm]: https://github.com/micromark/common-markup-state-machine

[markdown-deviations]: #72-deviations-from-markdown

[jsx-deviations]: #73-deviations-from-jsx

[parsing]: #4-parsing

[syntax]: #71-syntax