🎉 initiate project *astro_rewrite*

2023-07-19 21:31:30 +02:00 · 2023-07-19 21:31:30 +02:00 · 2ba37bfbe3
commit 2ba37bfbe3
parent ffd4d5e86c
8658 changed files with 2268794 additions and 2538 deletions
--- a/node_modules/micromark-extension-mdx-expression/dev/index.d.ts
+++ b/node_modules/micromark-extension-mdx-expression/dev/index.d.ts
@ -0,0 +1,21 @@
+import type {Program} from 'estree'
+
+export {mdxExpression, type Options} from './lib/syntax.js'
+
+declare module 'micromark-util-types' {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface Token {
+    estree?: Program
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface TokenTypeMap {
+    mdxFlowExpression: 'mdxFlowExpression'
+    mdxFlowExpressionMarker: 'mdxFlowExpressionMarker'
+    mdxFlowExpressionChunk: 'mdxFlowExpressionChunk'
+
+    mdxTextExpression: 'mdxTextExpression'
+    mdxTextExpressionMarker: 'mdxTextExpressionMarker'
+    mdxTextExpressionChunk: 'mdxTextExpressionChunk'
+  }
+}
--- a/node_modules/micromark-extension-mdx-expression/dev/index.js
+++ b/node_modules/micromark-extension-mdx-expression/dev/index.js
@ -0,0 +1,5 @@
+/**
+ * @typedef {import('./lib/syntax.js').Options} Options
+ */
+
+export {mdxExpression} from './lib/syntax.js'
--- a/node_modules/micromark-extension-mdx-expression/dev/lib/syntax.d.ts
+++ b/node_modules/micromark-extension-mdx-expression/dev/lib/syntax.d.ts
@ -0,0 +1,46 @@
+/**
+ * Create an extension for `micromark` to enable MDX expression syntax.
+ *
+ * @param {Options | null | undefined} [options]
+ *   Configuration (optional).
+ * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions` to enable MDX
+ *   expression syntax.
+ */
+export function mdxExpression(options?: Options | null | undefined): Extension
+export type Acorn = import('micromark-util-events-to-acorn').Acorn
+export type AcornOptions = import('micromark-util-events-to-acorn').AcornOptions
+export type Extension = import('micromark-util-types').Extension
+export type State = import('micromark-util-types').State
+export type TokenizeContext = import('micromark-util-types').TokenizeContext
+export type Tokenizer = import('micromark-util-types').Tokenizer
+/**
+ * Configuration (optional).
+ */
+export type Options = {
+  /**
+   * Acorn parser to use (optional).
+   */
+  acorn?: Acorn | null | undefined
+  /**
+   * Configuration for acorn (default: `{ecmaVersion: 2020, locations: true,
+   * sourceType: 'module'}`).
+   *
+   * All fields except `locations` can be set.
+   */
+  acornOptions?: AcornOptions | null | undefined
+  /**
+   * Whether to add `estree` fields to tokens with results from acorn.
+   */
+  addResult?: boolean | null | undefined
+  /**
+   * Undocumented option to parse only a spread (used by
+   * `micromark-extension-mdx-jsx` to parse spread attributes).
+   */
+  spread?: boolean | null | undefined
+  /**
+   * Undocumented option to disallow empty attributes (used by
+   * `micromark-extension-mdx-jsx` to prohobit empty attribute values).
+   */
+  allowEmpty?: boolean | null | undefined
+}
--- a/node_modules/micromark-extension-mdx-expression/dev/lib/syntax.js
+++ b/node_modules/micromark-extension-mdx-expression/dev/lib/syntax.js
@ -0,0 +1,223 @@
+/**
+ * @typedef {import('micromark-util-events-to-acorn').Acorn} Acorn
+ * @typedef {import('micromark-util-events-to-acorn').AcornOptions} AcornOptions
+ * @typedef {import('micromark-util-types').Extension} Extension
+ * @typedef {import('micromark-util-types').State} State
+ * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
+ * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
+ */
+
+/**
+ * @typedef Options
+ *   Configuration (optional).
+ * @property {Acorn | null | undefined} [acorn]
+ *   Acorn parser to use (optional).
+ * @property {AcornOptions | null | undefined} [acornOptions]
+ *   Configuration for acorn (default: `{ecmaVersion: 2020, locations: true,
+ *   sourceType: 'module'}`).
+ *
+ *   All fields except `locations` can be set.
+ * @property {boolean | null | undefined} [addResult=false]
+ *   Whether to add `estree` fields to tokens with results from acorn.
+ * @property {boolean | null | undefined} [spread=false]
+ *   Undocumented option to parse only a spread (used by
+ *   `micromark-extension-mdx-jsx` to parse spread attributes).
+ * @property {boolean | null | undefined} [allowEmpty=true]
+ *   Undocumented option to disallow empty attributes (used by
+ *   `micromark-extension-mdx-jsx` to prohobit empty attribute values).
+ */
+
+import {factoryMdxExpression} from 'micromark-factory-mdx-expression'
+import {factorySpace} from 'micromark-factory-space'
+import {markdownLineEnding, markdownSpace} from 'micromark-util-character'
+import {codes} from 'micromark-util-symbol/codes.js'
+import {types} from 'micromark-util-symbol/types.js'
+import {ok as assert} from 'uvu/assert'
+
+/**
+ * Create an extension for `micromark` to enable MDX expression syntax.
+ *
+ * @param {Options | null | undefined} [options]
+ *   Configuration (optional).
+ * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions` to enable MDX
+ *   expression syntax.
+ */
+export function mdxExpression(options) {
+  const options_ = options || {}
+  const addResult = options_.addResult
+  const acorn = options_.acorn
+  // Hidden: `micromark-extension-mdx-jsx` supports expressions in tags,
+  // and one of them is only “spread” elements.
+  // It also has expressions that are not allowed to be empty (`<x y={}/>`).
+  // Instead of duplicating code there, this are two small hidden feature here
+  // to test that behavior.
+  const spread = options_.spread
+  let allowEmpty = options_.allowEmpty
+  /** @type {AcornOptions} */
+  let acornOptions
+
+  if (allowEmpty === null || allowEmpty === undefined) {
+    allowEmpty = true
+  }
+
+  if (acorn) {
+    if (!acorn.parseExpressionAt) {
+      throw new Error(
+        'Expected a proper `acorn` instance passed in as `options.acorn`'
+      )
+    }
+
+    acornOptions = Object.assign(
+      {ecmaVersion: 2020, sourceType: 'module'},
+      options_.acornOptions
+    )
+  } else if (options_.acornOptions || options_.addResult) {
+    throw new Error('Expected an `acorn` instance passed in as `options.acorn`')
+  }
+
+  return {
+    flow: {
+      [codes.leftCurlyBrace]: {tokenize: tokenizeFlowExpression, concrete: true}
+    },
+    text: {[codes.leftCurlyBrace]: {tokenize: tokenizeTextExpression}}
+  }
+
+  /**
+   * MDX expression (flow).
+   *
+   * ```markdown
+   * > | {Math.PI}
+   *     ^^^^^^^^^
+   * ```
+   *
+   * @this {TokenizeContext}
+   * @type {Tokenizer}
+   */
+  function tokenizeFlowExpression(effects, ok, nok) {
+    const self = this
+
+    return start
+
+    /**
+     * Start of an MDX expression (flow).
+     *
+     * ```markdown
+     * > | {Math.PI}
+     *     ^
+     * ```
+     *
+     * @type {State}
+     */
+    function start(code) {
+      // To do: in `markdown-rs`, constructs need to parse the indent themselves.
+      // This should also be introduced in `micromark-js`.
+      assert(code === codes.leftCurlyBrace, 'expected `{`')
+      return before(code)
+    }
+
+    /**
+     * After optional whitespace, before expression.
+     *
+     * ```markdown
+     * > | {Math.PI}
+     *     ^
+     * ```
+     *
+     * @type {State}
+     */
+    function before(code) {
+      return factoryMdxExpression.call(
+        self,
+        effects,
+        after,
+        'mdxFlowExpression',
+        'mdxFlowExpressionMarker',
+        'mdxFlowExpressionChunk',
+        acorn,
+        acornOptions,
+        addResult,
+        spread,
+        allowEmpty
+      )(code)
+    }
+
+    /**
+     * After expression.
+     *
+     * ```markdown
+     * > | {Math.PI}
+     *              ^
+     * ```
+     *
+     * @type {State}
+     */
+    function after(code) {
+      return markdownSpace(code)
+        ? factorySpace(effects, end, types.whitespace)(code)
+        : end(code)
+    }
+
+    /**
+     * After expression, after optional whitespace.
+     *
+     * ```markdown
+     * > | {Math.PI}␠␊
+     *               ^
+     * ```
+     *
+     * @type {State}
+     */
+    function end(code) {
+      return code === codes.eof || markdownLineEnding(code)
+        ? ok(code)
+        : nok(code)
+    }
+  }
+
+  /**
+   * MDX expression (text).
+   *
+   * ```markdown
+   * > | a {Math.PI} c.
+   *       ^^^^^^^^^
+   * ```
+   *
+   * @this {TokenizeContext}
+   * @type {Tokenizer}
+   */
+  function tokenizeTextExpression(effects, ok) {
+    const self = this
+
+    return start
+
+    /**
+     * Start of an MDX expression (text).
+     *
+     * ```markdown
+     * > | a {Math.PI} c.
+     *       ^
+     * ```
+     *
+     *
+     * @type {State}
+     */
+    function start(code) {
+      assert(code === codes.leftCurlyBrace, 'expected `{`')
+      return factoryMdxExpression.call(
+        self,
+        effects,
+        ok,
+        'mdxTextExpression',
+        'mdxTextExpressionMarker',
+        'mdxTextExpressionChunk',
+        acorn,
+        acornOptions,
+        addResult,
+        spread,
+        allowEmpty,
+        true
+      )(code)
+    }
+  }
+}
--- a/node_modules/micromark-extension-mdx-expression/index.d.ts
+++ b/node_modules/micromark-extension-mdx-expression/index.d.ts
@ -0,0 +1,21 @@
+import type {Program} from 'estree'
+
+export {mdxExpression, type Options} from './lib/syntax.js'
+
+declare module 'micromark-util-types' {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface Token {
+    estree?: Program
+  }
+
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+  interface TokenTypeMap {
+    mdxFlowExpression: 'mdxFlowExpression'
+    mdxFlowExpressionMarker: 'mdxFlowExpressionMarker'
+    mdxFlowExpressionChunk: 'mdxFlowExpressionChunk'
+
+    mdxTextExpression: 'mdxTextExpression'
+    mdxTextExpressionMarker: 'mdxTextExpressionMarker'
+    mdxTextExpressionChunk: 'mdxTextExpressionChunk'
+  }
+}
--- a/node_modules/micromark-extension-mdx-expression/index.js
+++ b/node_modules/micromark-extension-mdx-expression/index.js
@ -0,0 +1,5 @@
+/**
+ * @typedef {import('./lib/syntax.js').Options} Options
+ */
+
+export {mdxExpression} from './lib/syntax.js'
--- a/node_modules/micromark-extension-mdx-expression/lib/syntax.d.ts
+++ b/node_modules/micromark-extension-mdx-expression/lib/syntax.d.ts
@ -0,0 +1,46 @@
+/**
+ * Create an extension for `micromark` to enable MDX expression syntax.
+ *
+ * @param {Options | null | undefined} [options]
+ *   Configuration (optional).
+ * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions` to enable MDX
+ *   expression syntax.
+ */
+export function mdxExpression(options?: Options | null | undefined): Extension
+export type Acorn = import('micromark-util-events-to-acorn').Acorn
+export type AcornOptions = import('micromark-util-events-to-acorn').AcornOptions
+export type Extension = import('micromark-util-types').Extension
+export type State = import('micromark-util-types').State
+export type TokenizeContext = import('micromark-util-types').TokenizeContext
+export type Tokenizer = import('micromark-util-types').Tokenizer
+/**
+ * Configuration (optional).
+ */
+export type Options = {
+  /**
+   * Acorn parser to use (optional).
+   */
+  acorn?: Acorn | null | undefined
+  /**
+   * Configuration for acorn (default: `{ecmaVersion: 2020, locations: true,
+   * sourceType: 'module'}`).
+   *
+   * All fields except `locations` can be set.
+   */
+  acornOptions?: AcornOptions | null | undefined
+  /**
+   * Whether to add `estree` fields to tokens with results from acorn.
+   */
+  addResult?: boolean | null | undefined
+  /**
+   * Undocumented option to parse only a spread (used by
+   * `micromark-extension-mdx-jsx` to parse spread attributes).
+   */
+  spread?: boolean | null | undefined
+  /**
+   * Undocumented option to disallow empty attributes (used by
+   * `micromark-extension-mdx-jsx` to prohobit empty attribute values).
+   */
+  allowEmpty?: boolean | null | undefined
+}
--- a/node_modules/micromark-extension-mdx-expression/lib/syntax.js
+++ b/node_modules/micromark-extension-mdx-expression/lib/syntax.js
@ -0,0 +1,220 @@
+/**
+ * @typedef {import('micromark-util-events-to-acorn').Acorn} Acorn
+ * @typedef {import('micromark-util-events-to-acorn').AcornOptions} AcornOptions
+ * @typedef {import('micromark-util-types').Extension} Extension
+ * @typedef {import('micromark-util-types').State} State
+ * @typedef {import('micromark-util-types').TokenizeContext} TokenizeContext
+ * @typedef {import('micromark-util-types').Tokenizer} Tokenizer
+ */
+
+/**
+ * @typedef Options
+ *   Configuration (optional).
+ * @property {Acorn | null | undefined} [acorn]
+ *   Acorn parser to use (optional).
+ * @property {AcornOptions | null | undefined} [acornOptions]
+ *   Configuration for acorn (default: `{ecmaVersion: 2020, locations: true,
+ *   sourceType: 'module'}`).
+ *
+ *   All fields except `locations` can be set.
+ * @property {boolean | null | undefined} [addResult=false]
+ *   Whether to add `estree` fields to tokens with results from acorn.
+ * @property {boolean | null | undefined} [spread=false]
+ *   Undocumented option to parse only a spread (used by
+ *   `micromark-extension-mdx-jsx` to parse spread attributes).
+ * @property {boolean | null | undefined} [allowEmpty=true]
+ *   Undocumented option to disallow empty attributes (used by
+ *   `micromark-extension-mdx-jsx` to prohobit empty attribute values).
+ */
+
+import {factoryMdxExpression} from 'micromark-factory-mdx-expression'
+import {factorySpace} from 'micromark-factory-space'
+import {markdownLineEnding, markdownSpace} from 'micromark-util-character'
+/**
+ * Create an extension for `micromark` to enable MDX expression syntax.
+ *
+ * @param {Options | null | undefined} [options]
+ *   Configuration (optional).
+ * @returns {Extension}
+ *   Extension for `micromark` that can be passed in `extensions` to enable MDX
+ *   expression syntax.
+ */
+export function mdxExpression(options) {
+  const options_ = options || {}
+  const addResult = options_.addResult
+  const acorn = options_.acorn
+  // Hidden: `micromark-extension-mdx-jsx` supports expressions in tags,
+  // and one of them is only “spread” elements.
+  // It also has expressions that are not allowed to be empty (`<x y={}/>`).
+  // Instead of duplicating code there, this are two small hidden feature here
+  // to test that behavior.
+  const spread = options_.spread
+  let allowEmpty = options_.allowEmpty
+  /** @type {AcornOptions} */
+  let acornOptions
+  if (allowEmpty === null || allowEmpty === undefined) {
+    allowEmpty = true
+  }
+  if (acorn) {
+    if (!acorn.parseExpressionAt) {
+      throw new Error(
+        'Expected a proper `acorn` instance passed in as `options.acorn`'
+      )
+    }
+    acornOptions = Object.assign(
+      {
+        ecmaVersion: 2020,
+        sourceType: 'module'
+      },
+      options_.acornOptions
+    )
+  } else if (options_.acornOptions || options_.addResult) {
+    throw new Error('Expected an `acorn` instance passed in as `options.acorn`')
+  }
+  return {
+    flow: {
+      [123]: {
+        tokenize: tokenizeFlowExpression,
+        concrete: true
+      }
+    },
+    text: {
+      [123]: {
+        tokenize: tokenizeTextExpression
+      }
+    }
+  }
+
+  /**
+   * MDX expression (flow).
+   *
+   * ```markdown
+   * > | {Math.PI}
+   *     ^^^^^^^^^
+   * ```
+   *
+   * @this {TokenizeContext}
+   * @type {Tokenizer}
+   */
+  function tokenizeFlowExpression(effects, ok, nok) {
+    const self = this
+    return start
+
+    /**
+     * Start of an MDX expression (flow).
+     *
+     * ```markdown
+     * > | {Math.PI}
+     *     ^
+     * ```
+     *
+     * @type {State}
+     */
+    function start(code) {
+      // To do: in `markdown-rs`, constructs need to parse the indent themselves.
+      // This should also be introduced in `micromark-js`.
+
+      return before(code)
+    }
+
+    /**
+     * After optional whitespace, before expression.
+     *
+     * ```markdown
+     * > | {Math.PI}
+     *     ^
+     * ```
+     *
+     * @type {State}
+     */
+    function before(code) {
+      return factoryMdxExpression.call(
+        self,
+        effects,
+        after,
+        'mdxFlowExpression',
+        'mdxFlowExpressionMarker',
+        'mdxFlowExpressionChunk',
+        acorn,
+        acornOptions,
+        addResult,
+        spread,
+        allowEmpty
+      )(code)
+    }
+
+    /**
+     * After expression.
+     *
+     * ```markdown
+     * > | {Math.PI}
+     *              ^
+     * ```
+     *
+     * @type {State}
+     */
+    function after(code) {
+      return markdownSpace(code)
+        ? factorySpace(effects, end, 'whitespace')(code)
+        : end(code)
+    }
+
+    /**
+     * After expression, after optional whitespace.
+     *
+     * ```markdown
+     * > | {Math.PI}␠␊
+     *               ^
+     * ```
+     *
+     * @type {State}
+     */
+    function end(code) {
+      return code === null || markdownLineEnding(code) ? ok(code) : nok(code)
+    }
+  }
+
+  /**
+   * MDX expression (text).
+   *
+   * ```markdown
+   * > | a {Math.PI} c.
+   *       ^^^^^^^^^
+   * ```
+   *
+   * @this {TokenizeContext}
+   * @type {Tokenizer}
+   */
+  function tokenizeTextExpression(effects, ok) {
+    const self = this
+    return start
+
+    /**
+     * Start of an MDX expression (text).
+     *
+     * ```markdown
+     * > | a {Math.PI} c.
+     *       ^
+     * ```
+     *
+     *
+     * @type {State}
+     */
+    function start(code) {
+      return factoryMdxExpression.call(
+        self,
+        effects,
+        ok,
+        'mdxTextExpression',
+        'mdxTextExpressionMarker',
+        'mdxTextExpressionChunk',
+        acorn,
+        acornOptions,
+        addResult,
+        spread,
+        allowEmpty,
+        true
+      )(code)
+    }
+  }
+}
--- a/node_modules/micromark-extension-mdx-expression/node_modules/.bin/uvu
+++ b/node_modules/micromark-extension-mdx-expression/node_modules/.bin/uvu
@ -0,0 +1 @@
+../../../uvu/bin.js
--- a/node_modules/micromark-extension-mdx-expression/package.json
+++ b/node_modules/micromark-extension-mdx-expression/package.json
@ -0,0 +1,69 @@
+{
+  "name": "micromark-extension-mdx-expression",
+  "version": "1.0.8",
+  "description": "micromark extension to support MDX or MDX JS expressions",
+  "license": "MIT",
+  "keywords": [
+    "micromark",
+    "micromark-extension",
+    "mdx",
+    "mdxjs",
+    "expression",
+    "js",
+    "javascript",
+    "es",
+    "ecmascript",
+    "markdown",
+    "unified"
+  ],
+  "repository": "https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression",
+  "bugs": "https://github.com/micromark/micromark-extension-mdx-expression/issues",
+  "funding": [
+    {
+      "type": "GitHub Sponsors",
+      "url": "https://github.com/sponsors/unifiedjs"
+    },
+    {
+      "type": "OpenCollective",
+      "url": "https://opencollective.com/unified"
+    }
+  ],
+  "author": "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)",
+  "contributors": [
+    "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)"
+  ],
+  "sideEffects": false,
+  "type": "module",
+  "main": "index.js",
+  "types": "dev/index.d.ts",
+  "files": [
+    "dev/",
+    "lib/",
+    "index.d.ts",
+    "index.js"
+  ],
+  "exports": {
+    "development": "./dev/index.js",
+    "default": "./index.js"
+  },
+  "dependencies": {
+    "@types/estree": "^1.0.0",
+    "micromark-factory-mdx-expression": "^1.0.0",
+    "micromark-factory-space": "^1.0.0",
+    "micromark-util-character": "^1.0.0",
+    "micromark-util-events-to-acorn": "^1.0.0",
+    "micromark-util-symbol": "^1.0.0",
+    "micromark-util-types": "^1.0.0",
+    "uvu": "^0.5.0"
+  },
+  "scripts": {
+    "build": "micromark-build"
+  },
+  "xo": false,
+  "typeCoverage": {
+    "atLeast": 100,
+    "detail": true,
+    "strict": true,
+    "ignoreCatch": true
+  }
+}
--- a/node_modules/micromark-extension-mdx-expression/readme.md
+++ b/node_modules/micromark-extension-mdx-expression/readme.md
@ -0,0 +1,392 @@
+# micromark-extension-mdx-expression
+
+[![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]
+
+[micromark][] extension to support [MDX][mdxjs] expressions (`{Math.PI}`).
+
+## Contents
+
+*   [What is this?](#what-is-this)
+*   [When to use this](#when-to-use-this)
+*   [Install](#install)
+*   [Use](#use)
+*   [API](#api)
+    *   [`mdxExpression(options?)`](#mdxexpressionoptions)
+    *   [Options](#options)
+*   [Authoring](#authoring)
+*   [Syntax](#syntax)
+*   [Errors](#errors)
+    *   [Unexpected end of file in expression, expected a corresponding closing brace for `{`](#unexpected-end-of-file-in-expression-expected-a-corresponding-closing-brace-for-)
+    *   [Could not parse expression with acorn: Unexpected content after expression](#could-not-parse-expression-with-acorn-unexpected-content-after-expression)
+    *   [Could not parse expression with acorn: $error](#could-not-parse-expression-with-acorn-error)
+*   [Tokens](#tokens)
+*   [Types](#types)
+*   [Compatibility](#compatibility)
+*   [Security](#security)
+*   [Related](#related)
+*   [Contribute](#contribute)
+*   [License](#license)
+
+## What is this?
+
+This package contains an extension that adds support for the expression syntax
+enabled by [MDX][mdxjs] to [`micromark`][micromark].
+These extensions are used inside MDX.
+
+This package can be made aware or unaware of JavaScript syntax.
+When unaware, expressions could include Rust or variables or whatnot.
+
+## When to use this
+
+This project is useful when you want to support expressions in markdown.
+
+You can use this extension when you are working with [`micromark`][micromark].
+To support all MDX features, use
+[`micromark-extension-mdxjs`][micromark-extension-mdxjs] instead.
+
+When you need a syntax tree, combine this package with
+[`mdast-util-mdx-expression`][mdast-util-mdx-expression].
+
+All these packages are used in [`remark-mdx`][remark-mdx], which focusses on
+making it easier to transform content by abstracting these internals away.
+
+When you are using [`mdx-js/mdx`][mdxjs], all of this is already included.
+
+## Install
+
+This package is [ESM only][esm].
+In Node.js (version 16+), install with [npm][]:
+
+```sh
+npm install micromark-extension-mdx-expression
+```
+
+In Deno with [`esm.sh`][esmsh]:
+
+```js
+import {mdxExpression} from 'https://esm.sh/micromark-extension-mdx-expression@1'
+```
+
+In browsers with [`esm.sh`][esmsh]:
+
+```html
+<script type="module">
+  import {mdxExpression} from 'https://esm.sh/micromark-extension-mdx-expression@1?bundle'
+</script>
+```
+
+## Use
+
+```js
+import {Parser} from 'acorn'
+import acornJsx from 'acorn-jsx'
+import {micromark} from 'micromark'
+import {mdxExpression} from 'micromark-extension-mdx-expression'
+
+// Unaware of JavaScript (“agnostic”) (balanced braces):
+const output = micromark('a {1 + 1} b', {extensions: [mdxExpression()]})
+
+console.log(output)
+
+// Aware of JavaScript:
+micromark('a {!} b', {extensions: [mdxExpression({acorn: Parser.extend(acornJsx())})]})
+```
+
+Yields:
+
+```html
+<p>a  b</p>
+```
+
+```txt
+[1:5: Could not parse expression with acorn: Unexpected token] {
+  reason: 'Could not parse expression with acorn: Unexpected token',
+  line: 1,
+  column: 5,
+  source: 'micromark-extension-mdx-expression',
+  ruleId: 'acorn',
+  position: {
+    start: { line: 1, column: 5, offset: 4 },
+    end: { line: null, column: null }
+  }
+}
+```
+
+…which is useless: go to a syntax tree with
+[`mdast-util-from-markdown`][mdast-util-from-markdown] and
+[`mdast-util-mdx-expression`][mdast-util-mdx-expression] instead.
+
+## API
+
+This package exports the identifier [`mdxExpression`][api-mdx-expression].
+There is no default export.
+
+The export map supports the [`development` condition][development].
+Run `node --conditions development module.js` to get instrumented dev code.
+Without this condition, production code is loaded.
+
+### `mdxExpression(options?)`
+
+Create an extension for `micromark` to enable MDX expression syntax.
+
+###### Parameters
+
+*   `options` ([`Options`][api-options], optional)
+    — configuration
+
+###### Returns
+
+Extension for `micromark` that can be passed in `extensions` to enable MDX
+expression syntax ([`Extension`][micromark-extension]).
+
+### Options
+
+Configuration (TypeScript type).
+
+###### Fields
+
+*   `acorn` ([`Acorn`][acorn], optional)
+    — acorn parser to use
+*   `acornOptions` ([`AcornOptions`][acorn-options], default:
+    `{ecmaVersion: 2020, locations: true, sourceType: 'module'}`)
+    — configuration for acorn; all fields except `locations` can be set
+*   `addResult` (`boolean`, default: `false`)
+    — whether to add `estree` fields to tokens with results from acorn
+
+<!-- Note: `spread` and `allowEmpty` are intentionally not documented. -->
+
+## Authoring
+
+When authoring markdown with JavaScript, keep in mind that MDX is a whitespace
+sensitive and line-based language, while JavaScript is insensitive to
+whitespace.
+This affects how markdown and JavaScript interleave with eachother in MDX.
+For more info on how it works, see [§ Interleaving][mdxjs-interleaving] on the
+MDX site.
+
+## Syntax
+
+This extension supports MDX both aware and unaware to JavaScript (respectively
+gnostic and agnostic).
+Depending on whether acorn is passed, either valid JavaScript must be used in
+expressions, or arbitrary text (such as Rust code or so) can be used.
+
+There are two types of expressions: in text (inline, span) or in flow (block).
+They start with `{`.
+
+Depending on whether `acorn` is passed, expressions are either parsed in several
+tries until whole JavaScript is found (as in, nested curly braces depend on JS
+expression nesting), or they are counted and must be balanced.
+
+Expressions end with `}`.
+
+For flow (block) expressions, optionally markdown spaces (` ` or `\t`) can occur
+after the closing brace, and finally a markdown line ending (`\r`, `\n`) or the
+end of the file must follow.
+
+While markdown typically knows no errors, for MDX it is decided to instead
+throw on invalid syntax.
+
+```markdown
+Here is an expression in a heading:
+
+## Hello, {1 + 1}!
+
+In agnostic mode, balanced braces can occur: {a + {b} + c}.
+
+In gnostic mode, the value of the expression must be JavaScript, so
+this would fail: {!}.
+But, in gnostic mode, braces can be in comments, strings, or in other
+places: {1 /* { */ + 2}.
+
+The previous examples were text (inline, span) expressions, they can
+also be flow (block):
+
+{
+  1 + 1
+}
+
+This is incorrect, because there are further characters:
+
+{
+  1 + 1
+}!
+
+Blank lines cannot occur in text, because markdown has already split them in
+separate constructs, so this is incorrect: {1 +
+
+1}
+
+
+In flow, you can have blank lines:
+
+{
+  1 +
+
+  2
+}
+```
+
+## Errors
+
+### Unexpected end of file in expression, expected a corresponding closing brace for `{`
+
+This error occurs if a `{` was seen without a `}` (source:
+`micromark-extension-mdx-expression`, rule id: `unexpected-eof`).
+For example:
+
+```markdown
+a { b
+```
+
+### Could not parse expression with acorn: Unexpected content after expression
+
+This error occurs when there is more content after a JS expression (source:
+`micromark-extension-mdx-expression`, rule id: `acorn`).
+For example:
+
+```markdown
+a {"b" "c"} d
+```
+
+### Could not parse expression with acorn: $error
+
+This error occurs if acorn crashes (source: `micromark-extension-mdx-expression`,
+rule id: `acorn`).
+For example:
+
+```markdown
+a {var b = "c"} d
+```
+
+## Tokens
+
+Two tokens are used, `mdxFlowExpression` and `mdxTextExpression`, to reflect
+flow and text expressions.
+
+They include:
+
+*   `lineEnding` for the markdown line endings `\r`, `\n`, and `\r\n`
+*   `mdxFlowExpressionMarker` and `mdxTextExpressionMarker` for the braces
+*   `whitespace` for markdown spaces and tabs in blank lines
+*   `mdxFlowExpressionChunk` and `mdxTextExpressionChunk` for chunks of
+    expression content
+
+## Types
+
+This package is fully typed with [TypeScript][].
+It exports the additional type [`Options`][api-options].
+
+## Compatibility
+
+Projects maintained by the unified collective are compatible with all maintained
+versions of Node.js.
+As of now, that is Node.js 16+.
+Our projects sometimes work with older versions, but this is not guaranteed.
+
+These extensions work with `micromark` version 3+.
+
+## Security
+
+This package is safe.
+
+## Related
+
+*   [`micromark-extension-mdxjs`][micromark-extension-mdxjs]
+    — support all MDX syntax
+*   [`mdast-util-mdx-expression`][mdast-util-mdx-expression]
+    — support MDX expressions in mdast
+*   [`remark-mdx`][remark-mdx]
+    — support all MDX syntax in remark
+
+## Contribute
+
+See [`contributing.md` in `micromark/.github`][contributing] 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]
+
+<!-- Definitions -->
+
+[build-badge]: https://github.com/micromark/micromark-extension-mdx-expression/workflows/main/badge.svg
+
+[build]: https://github.com/micromark/micromark-extension-mdx-expression/actions
+
+[coverage-badge]: https://img.shields.io/codecov/c/github/micromark/micromark-extension-mdx-expression.svg
+
+[coverage]: https://codecov.io/github/micromark/micromark-extension-mdx-expression
+
+[downloads-badge]: https://img.shields.io/npm/dm/micromark-extension-mdx-expression.svg
+
+[downloads]: https://www.npmjs.com/package/micromark-extension-mdx-expression
+
+[size-badge]: https://img.shields.io/bundlephobia/minzip/micromark-extension-mdx-expression.svg
+
+[size]: https://bundlephobia.com/result?p=micromark-extension-mdx-expression
+
+[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/micromark/micromark/discussions
+
+[npm]: https://docs.npmjs.com/cli/install
+
+[esmsh]: https://esm.sh
+
+[license]: https://github.com/micromark/micromark-extension-mdx-expression/blob/main/license
+
+[author]: https://wooorm.com
+
+[contributing]: https://github.com/micromark/.github/blob/main/contributing.md
+
+[support]: https://github.com/micromark/.github/blob/main/support.md
+
+[coc]: https://github.com/micromark/.github/blob/main/code-of-conduct.md
+
+[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
+
+[typescript]: https://www.typescriptlang.org
+
+[development]: https://nodejs.org/api/packages.html#packages_resolving_user_conditions
+
+[micromark]: https://github.com/micromark/micromark
+
+[micromark-extension]: https://github.com/micromark/micromark#syntaxextension
+
+[micromark-extension-mdxjs]: https://github.com/micromark/micromark-extension-mdxjs
+
+[mdast-util-mdx-expression]: https://github.com/syntax-tree/mdast-util-mdx-expression
+
+[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
+
+[remark-mdx]: https://mdxjs.com/packages/remark-mdx/
+
+[mdxjs]: https://mdxjs.com
+
+[mdxjs-interleaving]: https://mdxjs.com/docs/what-is-mdx/#interleaving
+
+[acorn]: https://github.com/acornjs/acorn
+
+[acorn-options]: https://github.com/acornjs/acorn/blob/96c721dbf89d0ccc3a8c7f39e69ef2a6a3c04dfa/acorn/dist/acorn.d.ts#L16
+
+[api-mdx-expression]: #mdxexpressionoptions
+
+[api-options]: #options