{"maintainers":[{"name":"anonymous","email":"johnotander@gmail.com"},{"name":"anonymous","email":"timneutkens@icloud.com"},{"name":"anonymous","email":"tituswormer@gmail.com"},{"name":"anonymous","email":"remcohaszing@gmail.com"}],"keywords":["jsx","markdown","mdx","remark"],"dist-tags":{"ci":"2.0.0-ci.53","next":"2.0.0-rc.2","latest":"3.1.1"},"author":{"name":"John Otander","email":"johnotander@gmail.com","url":"https://johno.com"},"description":"MDX compiler","readme":"# `@mdx-js/mdx`\n\n[![Build][build-badge]][build]\n[![Coverage][coverage-badge]][coverage]\n[![Downloads][downloads-badge]][downloads]\n[![Size][size-badge]][size]\n[![Sponsors][sponsors-badge]][collective]\n[![Backers][backers-badge]][collective]\n[![Chat][chat-badge]][chat]\n\nMDX compiler.\n\n\n\n## Contents\n\n* [What is this?](#what-is-this)\n* [When should I use this?](#when-should-i-use-this)\n* [Install](#install)\n* [Use](#use)\n* [API](#api)\n * [`compile(file, options?)`](#compilefile-options)\n * [`compileSync(file, options?)`](#compilesyncfile-options)\n * [`createProcessor(options?)`](#createprocessoroptions)\n * [`evaluate(file, options)`](#evaluatefile-options)\n * [`evaluateSync(file, options)`](#evaluatesyncfile-options)\n * [`nodeTypes`](#nodetypes)\n * [`run(code, options)`](#runcode-options)\n * [`runSync(code, options)`](#runsynccode-options)\n * [`CompileOptions`](#compileoptions)\n * [`EvaluateOptions`](#evaluateoptions)\n * [`Fragment`](#fragment)\n * [`Jsx`](#jsx)\n * [`JsxDev`](#jsxdev)\n * [`ProcessorOptions`](#processoroptions)\n * [`RunOptions`](#runoptions)\n * [`UseMdxComponents`](#usemdxcomponents)\n* [Types](#types)\n* [Architecture](#architecture)\n* [Compatibility](#compatibility)\n* [Security](#security)\n* [Contribute](#contribute)\n* [License](#license)\n\n## What is this?\n\nThis package is a compiler that turns MDX into JavaScript.\nIt can also evaluate MDX code.\n\n## When should I use this?\n\nThis is the core compiler for turning MDX into JavaScript which gives you the\nmost control.\nIf you’re using a bundler (Rollup, esbuild, webpack), a site builder (Next.js),\nor build system (Vite) which comes with a bundler, you’re better off using an\nintegration: see [§ Integrations][integrations].\n\n## Install\n\nThis package is [ESM only][esm].\nIn Node.js (version 16+), install with [npm][]:\n\n```sh\nnpm install @mdx-js/mdx\n```\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```tsx\nimport {compile} from 'https://esm.sh/@mdx-js/mdx@3'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\n```\n\n## Use\n\nSay we have an MDX document, `example.mdx`:\n\n```mdx\nexport function Thing() {\n return <>World!\n}\n\n# Hello, \n```\n\n…and some code in `example.js` to compile `example.mdx` to JavaScript:\n\n```tsx\nimport fs from 'node:fs/promises'\nimport {compile} from '@mdx-js/mdx'\n\nconst compiled = await compile(await fs.readFile('example.mdx'))\n\nconsole.log(String(compiled))\n```\n\nYields roughly:\n\n```tsx\nimport {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'\n\nexport function Thing() {\n return _jsx(_Fragment, {children: 'World!'})\n}\n\nfunction _createMdxContent(props) {\n const _components = {h1: 'h1', ...props.components}\n return _jsxs(_components.h1, {children: ['Hello, ', _jsx(Thing, {})]})\n}\n\nexport default function MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || {}\n return MDXLayout\n ? _jsx(MDXLayout, {...props, children: _jsx(_createMdxContent, {...props})})\n : _createMdxContent(props)\n}\n```\n\nSee [§ Using MDX][using-mdx] for more on how MDX work and how to use the result.\n\n## API\n\nThis package exports the following identifiers:\n[`compile`][api-compile],\n[`compileSync`][api-compile-sync],\n[`createProcessor`][api-create-processor],\n[`evaluate`][api-evaluate],\n[`evaluateSync`][api-evaluate-sync],\n[`nodeTypes`][api-node-types],\n[`run`][api-run], and\n[`runSync`][api-run-sync].\nThere is no default export.\n\n### `compile(file, options?)`\n\nCompile MDX to JS.\n\n###### Parameters\n\n* `file` ([`Compatible` from `vfile`][vfile-compatible])\n — MDX document to parse\n* `options` ([`CompileOptions`][api-compile-options], optional)\n — compile configuration\n\n###### Returns\n\nPromise to compiled file ([`Promise`][vfile]).\n\n###### Examples\n\nThe input value for `file` can be many different things.\nYou can pass a `string`, `Uint8Array` in UTF-8, [`VFile`][vfile], or anything\nthat can be given to `new VFile`.\n\n```tsx\nimport {compile} from '@mdx-js/mdx'\nimport {VFile} from 'vfile'\n\nawait compile(':)')\nawait compile(Buffer.from(':-)'))\nawait compile({path: 'path/to/file.mdx', value: '🥳'})\nawait compile(new VFile({path: 'path/to/file.mdx', value: '🤭'}))\n```\n\nThe output `VFile` can be used to access more than the generated code:\n\n```tsx\nimport {compile} from '@mdx-js/mdx'\nimport remarkPresetLintConsistent from 'remark-preset-lint-consistent' // Lint rules to check for consistent markdown.\nimport {reporter} from 'vfile-reporter'\n\nconst file = await compile('*like this* or _like this_?', {remarkPlugins: [remarkPresetLintConsistent]})\n\nconsole.error(reporter(file))\n```\n\nYields:\n\n```text\n 1:16-1:27 warning Emphasis should use `*` as a marker emphasis-marker remark-lint\n\n⚠ 1 warning\n```\n\n### `compileSync(file, options?)`\n\nSynchronously compile MDX to JS.\n\nWhen possible please use the async [`compile`][api-compile].\n\n###### Parameters\n\n* `file` ([`Compatible` from `vfile`][vfile-compatible])\n — MDX document to parse\n* `options` ([`CompileOptions`][api-compile-options], optional)\n — compile configuration\n\n###### Returns\n\nCompiled file ([`VFile`][vfile]).\n\n### `createProcessor(options?)`\n\nCreate a processor to compile markdown or MDX to JavaScript.\n\n> **Note**: `format: 'detect'` is not allowed in `ProcessorOptions`.\n\n###### Parameters\n\n* `options` ([`ProcessorOptions`][api-processor-options], optional)\n — process configuration\n\n###### Returns\n\nProcessor ([`Processor` from `unified`][unified-processor]).\n\n### `evaluate(file, options)`\n\n[Compile][api-compile] and [run][api-run] MDX.\n\nWhen you trust your content, `evaluate` can work.\nWhen possible, use [`compile`][api-compile], write to a file, and then run with\nNode or use one of the [§ Integrations][integrations].\n\n> ☢️ **Danger**: it’s called **evaluate** because it `eval`s JavaScript.\n\n###### Parameters\n\n* `file` ([`Compatible` from `vfile`][vfile-compatible])\n — MDX document to parse\n* `options` ([`EvaluateOptions`][api-evaluate-options], **required**)\n — configuration\n\n###### Returns\n\nPromise to a module ([`Promise` from\n`mdx/types.js`][mdx-types-module]).\n\nThe result is an object with a `default` field set to the component;\nanything else that was exported is available too.\nFor example, assuming the contents of `example.mdx` from [§ Use][use] was in\n`file`, then:\n\n```tsx\nimport {evaluate} from '@mdx-js/mdx'\nimport * as runtime from 'react/jsx-runtime'\n\nconsole.log(await evaluate(file, runtime))\n```\n\n…yields:\n\n```tsx\n{Thing: [Function: Thing], default: [Function: MDXContent]}\n```\n\n###### Notes\n\nCompiling (and running) MDX takes time.\n\nIf you are live-rendering a string of MDX that often changes using a virtual DOM\nbased framework (such as React), one performance improvement is to call the\n`MDXContent` component yourself.\nThe reason is that the `evaluate` creates a new function each time, which cannot\nbe diffed:\n\n```diff\n const {default: MDXContent} = await evaluate('…')\n\n-\n+MDXContent(props)\n```\n\n### `evaluateSync(file, options)`\n\nCompile and run MDX, synchronously.\n\nWhen possible please use the async [`evaluate`][api-evaluate].\n\n> ☢️ **Danger**: it’s called **evaluate** because it `eval`s JavaScript.\n\n###### Parameters\n\n* `file` ([`Compatible` from `vfile`][vfile-compatible])\n — MDX document to parse\n* `options` ([`EvaluateOptions`][api-evaluate-options], **required**)\n — configuration\n\n###### Returns\n\nModule ([`MDXModule` from `mdx/types.js`][mdx-types-module]).\n\n### `nodeTypes`\n\nList of node types made by `mdast-util-mdx`, which have to be passed\nthrough untouched from the mdast tree to the hast tree (`Array`).\n\n### `run(code, options)`\n\nRun code compiled with `outputFormat: 'function-body'`.\n\n> ☢️ **Danger**: this `eval`s JavaScript.\n\n###### Parameters\n\n* `code` ([`VFile`][vfile] or `string`)\n — JavaScript function body to run\n* `options` ([`RunOptions`][api-run-options], **required**)\n — configuration\n\n###### Returns\n\nPromise to a module ([`Promise` from\n`mdx/types.js`][mdx-types-module]);\nthe result is an object with a `default` field set to the component;\nanything else that was exported is available too.\n\n###### Example\n\nOn the server:\n\n```tsx\nimport {compile} from '@mdx-js/mdx'\n\nconst code = String(await compile('# hi', {outputFormat: 'function-body'}))\n// To do: send `code` to the client somehow.\n```\n\nOn the client:\n\n```tsx\nimport {run} from '@mdx-js/mdx'\nimport * as runtime from 'react/jsx-runtime'\n\nconst code = '' // To do: get `code` from server somehow.\n\nconst {default: Content} = await run(code, {...runtime, baseUrl: import.meta.url})\n\nconsole.log(Content)\n```\n\n…yields:\n\n```tsx\n[Function: MDXContent]\n```\n\n### `runSync(code, options)`\n\nRun code, synchronously.\n\nWhen possible please use the async [`run`][api-run].\n\n> ☢️ **Danger**: this `eval`s JavaScript.\n\n###### Parameters\n\n* `code` ([`VFile`][vfile] or `string`)\n — JavaScript function body to run\n* `options` ([`RunOptions`][api-run-options], **required**)\n — configuration\n\n###### Returns\n\nModule ([`MDXModule` from `mdx/types.js`][mdx-types-module]).\n\n### `CompileOptions`\n\nConfiguration for `compile` (TypeScript type).\n\n`CompileOptions` is the same as [`ProcessorOptions`][api-processor-options]\nwith the exception that the `format` option supports a `'detect'` value,\nwhich is the default.\nThe `'detect'` format means to use `'md'` for files with an extension in\n`mdExtensions` and `'mdx'` otherwise.\n\n###### Type\n\n```tsx\n/**\n * Configuration for `compile`\n */\ntype CompileOptions = Omit & {\n /**\n * Format of `file` (default: `'detect'`).\n */\n format?: 'detect' | 'md' | 'mdx' | null | undefined\n}\n```\n\n### `EvaluateOptions`\n\nConfiguration for `evaluate` (TypeScript type).\n\n`EvaluateOptions` is the same as [`CompileOptions`][api-compile-options],\nexcept that the options `baseUrl`, `jsx`, `jsxImportSource`, `jsxRuntime`,\n`outputFormat`, `pragma`, `pragmaFrag`, `pragmaImportSource`, and\n`providerImportSource` are not allowed, and that\n[`RunOptions`][api-run-options] are also used.\n\n###### Type\n\n```tsx\n/**\n * Configuration for `evaluate`.\n */\ntype EvaluateOptions = Omit<\n CompileOptions,\n | 'baseUrl' // Note that this is also in `RunOptions`.\n | 'jsx'\n | 'jsxImportSource'\n | 'jsxRuntime'\n | 'outputFormat'\n | 'pragma'\n | 'pragmaFrag'\n | 'pragmaImportSource'\n | 'providerImportSource'\n> &\n RunOptions\n```\n\n### `Fragment`\n\nRepresent the children, typically a symbol (TypeScript type).\n\n###### Type\n\n```ts\ntype Fragment = unknown\n```\n\n### `Jsx`\n\nCreate a production element (TypeScript type).\n\n###### Parameters\n\n* `type` (`unknown`)\n — element type: `Fragment` symbol, tag name (`string`), component\n* `properties` (`Properties`)\n — element properties and `children`\n* `key` (`string` or `undefined`)\n — key to use\n\n###### Returns\n\nElement from your framework (`JSX.Element`).\n\n### `JsxDev`\n\nCreate a development element (TypeScript type).\n\n###### Parameters\n\n* `type` (`unknown`)\n — element type: `Fragment` symbol, tag name (`string`), component\n* `properties` (`Properties`)\n — element properties and `children`\n* `key` (`string` or `undefined`)\n — key to use\n* `isStaticChildren` (`boolean`)\n — whether two or more children are passed (in an array), which is whether\n `jsxs` or `jsx` would be used\n* `source` (`Source`)\n — info about source\n* `self` (`unknown`)\n — context object (`this`)\n\n### `ProcessorOptions`\n\nConfiguration for `createProcessor` (TypeScript type).\n\n###### Fields\n\n* `SourceMapGenerator` (`SourceMapGenerator` from [`source-map`][source-map],\n optional)\n — add a source map (object form) as the `map` field on the resulting file\n\n Expand example
\n\n Assuming `example.mdx` from [§ Use][use] exists, then:\n\n ```tsx\n import fs from 'node:fs/promises'\n import {compile} from '@mdx-js/mdx'\n import {SourceMapGenerator} from 'source-map'\n\n const file = await compile(\n {path: 'example.mdx', value: await fs.readFile('example.mdx')},\n {SourceMapGenerator}\n )\n\n console.log(file.map)\n ```\n\n …yields:\n\n ```tsx\n {\n file: 'example.mdx',\n mappings: ';;aAAaA,QAAQ;YAAQ;;;;;;;;iBAE3B',\n names: ['Thing'],\n sources: ['example.mdx'],\n version: 3\n }\n ```\n\n Expand example
\n\n Say we have a module `example.js`:\n\n ```tsx\n import {compile} from '@mdx-js/mdx'\n\n const code = 'export {number} from \"./data.js\"\\n\\n# hi'\n const baseUrl = 'https://a.full/url' // Typically `import.meta.url`\n\n console.log(String(await compile(code, {baseUrl})))\n ```\n\n …now running `node example.js` yields:\n\n ```tsx\n import {jsx as _jsx} from 'react/jsx-runtime'\n export {number} from 'https://a.full/data.js'\n function _createMdxContent(props) { /* … */ }\n export default function MDXContent(props = {}) { /* … */ }\n ```\n\n Expand example
\n\n Say we had some MDX that references a component that can be passed or\n provided at runtime:\n\n ```mdx\n **Note**: some stuff.\n ```\n\n And a module to evaluate that:\n\n ```tsx\n import fs from 'node:fs/promises'\n import {evaluate} from '@mdx-js/mdx'\n import * as runtime from 'react/jsx-runtime'\n\n const path = 'example.mdx'\n const value = await fs.readFile(path)\n const MDXContent = (await evaluate({path, value}, {...runtime, baseUrl: import.meta.url})).default\n\n console.log(MDXContent({}))\n ```\n\n …running that would normally (production) yield:\n\n ```text\n Error: Expected component `NoteIcon` to be defined: you likely forgot to import, pass, or provide it.\n at _missingMdxReference (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :27:9)\n at _createMdxContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :15:20)\n at MDXContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :9:9)\n at main (…/example.js:11:15)\n ```\n\n …but if we add `development: true` to our example:\n\n ```diff\n @@ -7,6 +7,6 @@\n import fs from 'node:fs/promises'\n -import * as runtime from 'react/jsx-runtime'\n +import * as runtime from 'react/jsx-dev-runtime'\n import {evaluate} from '@mdx-js/mdx'\n\n const path = 'example.mdx'\n const value = await fs.readFile(path)\n -const MDXContent = (await evaluate({path, value}, {...runtime, baseUrl: import.meta.url})).default\n +const MDXContent = (await evaluate({path, value}, {development: true, ...runtime, baseUrl: import.meta.url})).default\n\n console.log(MDXContent({}))\n ```\n\n …and we’d run it again, we’d get:\n\n ```text\n Error: Expected component `NoteIcon` to be defined: you likely forgot to import, pass, or provide it.\n It’s referenced in your code at `1:9-1:21` in `example.mdx`\n provide it.\n at _missingMdxReference (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :27:9)\n at _createMdxContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :15:20)\n at MDXContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :9:9)\n at main (…/example.js:11:15)\n ```\n\n Expand example
\n\n ```tsx\n compile('…') // Seen as MDX.\n compile('…', {format: 'mdx'}) // Seen as MDX.\n compile('…', {format: 'md'}) // Seen as markdown.\n ```\n\n Expand example
\n\n If `file` is the contents of `example.mdx` from [§ Use][use], then:\n\n ```tsx\n compile(file, {jsx: true})\n ```\n\n …yields this difference:\n\n ```diff\n -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'\n +/*@jsxRuntime automatic*/\n +/*@jsxImportSource react*/\n\n export function Thing() {\n - return _jsx(_Fragment, {children: 'World'})\n + return <>World!\n }\n\n function _createMdxContent(props) {\n const _components = {\n h1: 'h1',\n ...props.components\n }\n - return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]})\n + return <_components.h1>{\"Hello \"}\n }\n\n export default function MDXContent(props = {}) {\n const {wrapper: MDXLayout} = props.components || {}\n return MDXLayout\n - ? _jsx(MDXLayout, {\n - ...props,\n - children: _jsx(_createMdxContent, props)\n - })\n + ? <_createMdxContent {...props} />\n : _createMdxContent(props)\n }\n }\n ```\n\n Expand example
\n\n If `file` is the contents of `example.mdx` from [§ Use][use], then:\n\n ```tsx\n compile(file, {jsxImportSource: 'preact'})\n ```\n\n …yields this difference:\n\n ```diff\n -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'\n +import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from 'preact/jsx-runtime'\n ```\n\n Expand example
\n\n If `file` is the contents of `example.mdx` from [§ Use][use], then:\n\n ```tsx\n compile(file, {jsxRuntime: 'classic'})\n ```\n\n …yields this difference:\n\n ```diff\n -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'\n +import React from 'react'\n\n export function Thing() {\n - return _jsx(_Fragment, {children: 'World'})\n + return React.createElement(React.Fragment, null, 'World!')\n }\n …\n ```\n\n Expand example
\n\n With a module `example.js`:\n\n ```tsx\n import {compile} from '@mdx-js/mdx'\n\n const code = 'export const no = 3.14\\n\\n# hi {no}'\n\n console.log(String(await compile(code, {outputFormat: 'program'}))) // Default.\n console.log(String(await compile(code, {outputFormat: 'function-body'})))\n ```\n\n …yields:\n\n ```tsx\n import {jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'\n export const no = 3.14\n function _createMdxContent(props) { /* … */ }\n export default function MDXContent(props = {}) { /* … */ }\n ```\n\n ```tsx\n 'use strict'\n const {Fragment: _Fragment, jsx: _jsx} = arguments[0]\n const no = 3.14\n function _createMdxContent(props) { /* … */ }\n function MDXContent(props = {}) { /* … */ }\n return {no, default: MDXContent}\n ```\n\n The `'program'` format will use import statements to import the runtime (and\n optionally provider) and use an export statement to yield the `MDXContent`\n component.\n\n The `'function-body'` format will get the runtime (and optionally provider)\n from `arguments[0]`, rewrite export statements, and use a return statement to\n yield what was exported.\n\n Expand example
\n\n If `file` is the contents of `example.mdx` from [§ Use][use], then:\n\n ```tsx\n compile(file, {\n jsxRuntime: 'classic',\n pragma: 'preact.createElement',\n pragmaFrag: 'preact.Fragment',\n pragmaImportSource: 'preact/compat'\n })\n ```\n\n …yields this difference:\n\n ```diff\n -import React from 'react'\n +import preact from 'preact/compat'\n\n export function Thing() {\n - return React.createElement(React.Fragment, null, 'World!')\n + return preact.createElement(preact.Fragment, null, 'World!')\n }\n …\n ```\n\n Expand example
\n\n If `file` is the contents of `example.mdx` from [§ Use][use], then:\n\n ```tsx\n compile(file, {providerImportSource: '@mdx-js/react'})\n ```\n\n …yields this difference:\n\n ```diff\n import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'\n +import {useMDXComponents as _provideComponents} from '@mdx-js/react'\n\n export function Thing() {\n return _jsx(_Fragment, {children: 'World'})\n }\n\n function _createMdxContent(props) {\n const _components = {\n h1: 'h1',\n + ..._provideComponents(),\n ...props.components\n }\n return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]})\n }\n\n export default function MDXContent(props = {}) {\n - const {wrapper: MDXLayout} = props.components || {}\n + const {wrapper: MDXLayout} = {\n + ..._provideComponents(),\n + ...props.components\n + }\n\n return MDXLayout\n ? _jsx(MDXLayout, {...props, children: _jsx(_createMdxContent, {})})\n : _createMdxContent()\n ```\n\n Expand example
\n\n ```tsx\n import recmaMdxIsMdxComponent from 'recma-mdx-is-mdx-component'\n\n await compile(file, {recmaPlugins: [recmaMdxIsMdxComponent]})\n ```\n\n Expand example
\n\n ```tsx\n import rehypeKatex from 'rehype-katex' // Render math with KaTeX.\n import remarkMath from 'remark-math' // Support math like `$so$`.\n\n await compile(file, {rehypePlugins: [rehypeKatex], remarkPlugins: [remarkMath]})\n\n await compile(file, {\n // A plugin with options:\n rehypePlugins: [[rehypeKatex, {strict: true, throwOnError: true}]],\n remarkPlugins: [remarkMath]\n })\n ```\n\n Expand example
\n\n ```tsx\n import remarkFrontmatter from 'remark-frontmatter' // YAML and such.\n import remarkGfm from 'remark-gfm' // Tables, footnotes, strikethrough, task lists, literal URLs.\n\n await compile(file, {remarkPlugins: [remarkGfm]}) // One plugin.\n await compile(file, {remarkPlugins: [[remarkFrontmatter, 'toml']]}) // A plugin with options.\n await compile(file, {remarkPlugins: [remarkGfm, remarkFrontmatter]}) // Two plugins.\n await compile(file, {remarkPlugins: [[remarkGfm, {singleTilde: false}], remarkFrontmatter]}) // Two plugins, first w/ options.\n ```\n\n Expand example
\n\n ```tsx\n compile({value: '…'}, {remarkRehypeOptions: {clobberPrefix: 'comment-1'}})\n ```\n\n