[ { "path": ".editorconfig", "content": "root = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\nindent_size = 2\nindent_style = space\ninsert_final_newline = true\ntrim_trailing_whitespace = true\n" }, { "path": ".github/workflows/bb.yml", "content": "jobs:\n main:\n runs-on: ubuntu-latest\n steps:\n - uses: unifiedjs/beep-boop-beta@main\n with:\n repo-token: ${{secrets.GITHUB_TOKEN}}\nname: bb\non:\n issues:\n types: [closed, edited, labeled, opened, reopened, unlabeled]\n pull_request_target:\n types: [closed, edited, labeled, opened, reopened, unlabeled]\n" }, { "path": ".github/workflows/main.yml", "content": "jobs:\n small:\n env:\n PUPPETEER_SKIP_DOWNLOAD: 1\n name: test / ${{matrix.os}} / ${{matrix.node}}\n runs-on: ${{matrix.os}}\n steps:\n - uses: actions/checkout@v5\n with:\n fetch-depth: 0\n - uses: actions/setup-node@v4\n with:\n cache: npm\n node-version: ${{matrix.node}}\n - run: npm ci\n - run: npm run test-api\n strategy:\n matrix:\n include:\n - node: lts/iron\n os: ubuntu-latest\n node:\n - lts/*\n os:\n - macos-latest\n - windows-latest\n full:\n env:\n PUPPETEER_SKIP_DOWNLOAD: 1\n name: full build\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v5\n with:\n fetch-depth: 0\n - uses: actions/setup-node@v4\n with:\n cache: npm\n node-version: lts/*\n - run: npm ci\n - run: npm test\n - uses: codecov/codecov-action@v5\nname: main\non:\n - pull_request\n - push\n" }, { "path": ".github/workflows/website.yml", "content": "jobs:\n deploy:\n environment:\n name: Website\n url: ${{steps.deployment.outputs.page_url}}\n permissions:\n contents: read\n id-token: write\n pages: write\n # To do: replace w/ `ubuntu-latest` when upstream is solved:\n # .\n runs-on: ubuntu-22.04\n steps:\n - uses: actions/checkout@v5\n - uses: actions/setup-node@v4\n with:\n node-version: lts/*\n - run: npm ci\n - run: npm run docs\n - uses: actions/upload-pages-artifact@v4\n with:\n path: public\n - uses: actions/deploy-pages@v4\n id: deployment\nname: website\non:\n push:\n branches:\n - main\n" }, { "path": ".gitignore", "content": ".DS_Store\ncoverage/\nnode_modules/\n*.d.cts\n*.d.ts\n*.map\n*.tsbuildinfo\n/public/\n!/packages/mdx/lib/types.d.ts\n!/website/types.d.ts\n" }, { "path": ".prettierignore", "content": "node_modules/\ncoverage/\npublic/\n*.md\n*.mdx\n" }, { "path": ".vercelignore", "content": "node_modules/\n" }, { "path": "changelog.md", "content": "# Changelog\n\nSee [GitHub Releases][releases] for the changelog.\n\n[releases]: https://github.com/mdx-js/mdx/releases\n" }, { "path": "docs/.remarkrc.js", "content": "/**\n * @import {CheckFlag} from 'remark-lint-fenced-code-flag'\n * @import {Preset} from 'unified'\n */\n\nimport remarkPresetWooorm from 'remark-preset-wooorm'\nimport remarkLintFencedCodeFlag, {\n checkGithubLinguistFlag\n} from 'remark-lint-fenced-code-flag'\nimport remarkLintNoHtml from 'remark-lint-no-html'\nimport remarkValidateLinks from 'remark-validate-links'\n\n/** @type {Preset} */\nconst remarkPresetMdx = {\n plugins: [\n remarkPresetWooorm,\n [remarkLintFencedCodeFlag, check],\n [remarkLintNoHtml, false],\n [remarkValidateLinks, false]\n ]\n}\n\nexport default remarkPresetMdx\n\n/**\n * Check according to GitHub Linguist.\n *\n * @param {string} value\n * Language flag to check.\n * @returns {string | undefined}\n * Whether the flag is valid (`undefined`),\n * or a message to warn about (`string`).\n * @satisfies {CheckFlag}\n */\nfunction check(value) {\n // To do: investigate if we can change ` ```jsx ` -> ` ```js `?\n if (value === 'jsx' || value === 'mdx-invalid') return undefined\n return checkGithubLinguistFlag(value)\n}\n" }, { "path": "docs/404.mdx", "content": "import {Note} from './_component/note.jsx'\n\nexport {Home as default} from './_component/home.jsx'\nexport const navExclude = true\n\n# 404: Not found\n\nAww, snap.\nUnfortunately this page doesn’t exist.\nPerhaps you can find what you’re looking for [on GitHub][search]?\n\n\n **Note**: Did you come here from a website linking to it?\n Pretty sure this page used to exist?\n Please [open an issue](https://github.com/mdx-js/mdx/issues/new) to let us\n know so we can fix it!\n\n\n[search]: https://github.com/mdx-js/mdx/search\n" }, { "path": "docs/_asset/editor.jsx", "content": "/* @jsxRuntime automatic */\n/* @jsxImportSource react */\n\n/* eslint-disable unicorn/prefer-global-this */\n\n/**\n * @import {Grammar} from '@wooorm/starry-night'\n * @import {Node as EstreeNode, Program} from 'estree'\n * @import {Nodes as HastNodes, Root as HastRoot} from 'hast'\n * @import {Nodes as MdastNodes, Root as MdastRoot} from 'mdast'\n * @import {\n MdxJsxAttribute,\n MdxJsxAttributeValueExpression,\n MdxJsxExpressionAttribute\n * } from 'mdast-util-mdx-jsx'\n * @import {MDXModule} from 'mdx/types.js'\n * @import {ReactNode} from 'react'\n * @import {FallbackProps} from 'react-error-boundary'\n * @import {PluggableList} from 'unified'\n * @import {Node as UnistNode} from 'unist'\n */\n\n/**\n * @typedef DisplayProperties\n * Properties.\n * @property {Error} error\n * Error.\n *\n * @typedef EvalNok\n * Not OK.\n * @property {false} ok\n * Whether OK.\n * @property {Error} value\n * Error.\n *\n * @typedef EvalOk\n * OK.\n * @property {true} ok\n * Whether OK.\n * @property {ReactNode} value\n * Result.\n *\n * @typedef {EvalNok | EvalOk} EvalResult\n * Result.\n */\n\nimport {compile, nodeTypes, run} from '@mdx-js/mdx'\nimport {createStarryNight} from '@wooorm/starry-night'\nimport sourceCss from '@wooorm/starry-night/source.css'\nimport sourceJs from '@wooorm/starry-night/source.js'\nimport sourceJson from '@wooorm/starry-night/source.json'\nimport sourceMdx from '@wooorm/starry-night/source.mdx'\nimport sourceTs from '@wooorm/starry-night/source.ts'\nimport sourceTsx from '@wooorm/starry-night/source.tsx'\nimport textHtmlBasic from '@wooorm/starry-night/text.html.basic'\nimport textMd from '@wooorm/starry-night/text.md'\nimport {visit as visitEstree} from 'estree-util-visit'\nimport {toJsxRuntime} from 'hast-util-to-jsx-runtime'\nimport {useEffect, useState} from 'react'\nimport {Fragment, jsx, jsxs} from 'react/jsx-runtime'\nimport ReactDom from 'react-dom/client'\nimport {ErrorBoundary} from 'react-error-boundary'\nimport rehypeRaw from 'rehype-raw'\nimport remarkDirective from 'remark-directive'\nimport remarkFrontmatter from 'remark-frontmatter'\nimport remarkGfm from 'remark-gfm'\nimport remarkMath from 'remark-math'\nimport {removePosition} from 'unist-util-remove-position'\nimport {visit} from 'unist-util-visit'\nimport {VFile} from 'vfile'\n\nconst sample = `# Hello, world!\n\nBelow is an example of markdown in JSX.\n\n
\n Try and change the background color to \\`tomato\\`.\n
`\n\n/** @type {ReadonlyArray} */\nconst grammars = [\n sourceCss,\n sourceJs,\n sourceJson,\n sourceMdx,\n sourceTs,\n sourceTsx,\n textHtmlBasic,\n textMd\n]\n\n/** @type {Awaited>} */\nlet starryNight\n\nconst editor = document.querySelector('#js-editor')\n\nif (window.location.pathname === '/playground/' && editor) {\n const root = document.createElement('div')\n root.classList.add('playground')\n editor.after(root)\n init(root)\n}\n\n/**\n * @param {Element} main\n * DOM element.\n * @returns {undefined}\n * Nothing.\n */\nfunction init(main) {\n const root = ReactDom.createRoot(main)\n\n createStarryNight(grammars).then(\n /**\n * @returns {undefined}\n * Nothing.\n */\n function (x) {\n starryNight = x\n\n const missing = starryNight.missingScopes()\n if (missing.length > 0) {\n throw new Error('Unexpected missing required scopes: `' + missing + '`')\n }\n\n root.render()\n }\n )\n}\n\nfunction Playground() {\n const [directive, setDirective] = useState(false)\n const [evalResult, setEvalResult] = useState(\n // Cast to more easily use actual value.\n /** @type {unknown} */ (undefined)\n )\n const [development, setDevelopment] = useState(false)\n const [frontmatter, setFrontmatter] = useState(false)\n const [gfm, setGfm] = useState(false)\n const [formatMarkdown, setFormatMarkdown] = useState(false)\n const [generateJsx, setGenerateJsx] = useState(false)\n const [math, setMath] = useState(false)\n const [outputFormatFunctionBody, setOutputFormatFunctionBody] =\n useState(false)\n const [positions, setPositions] = useState(false)\n const [raw, setRaw] = useState(false)\n const [show, setShow] = useState('result')\n const [value, setValue] = useState(sample)\n\n useEffect(\n function () {\n go().then(\n function (ok) {\n setEvalResult({ok: true, value: ok})\n },\n /**\n * @param {Error} error\n * Error.\n * @returns {undefined}\n * Nothing.\n */\n function (error) {\n setEvalResult({ok: false, value: error})\n }\n )\n\n async function go() {\n /** @type {PluggableList} */\n const recmaPlugins = []\n /** @type {PluggableList} */\n const rehypePlugins = []\n /** @type {PluggableList} */\n const remarkPlugins = []\n\n if (directive) remarkPlugins.unshift(remarkDirective)\n if (frontmatter) remarkPlugins.unshift(remarkFrontmatter)\n if (gfm) remarkPlugins.unshift(remarkGfm)\n if (math) remarkPlugins.unshift(remarkMath)\n if (raw) rehypePlugins.unshift([rehypeRaw, {passThrough: nodeTypes}])\n\n const file = new VFile({\n basename: formatMarkdown ? 'example.md' : 'example.mdx',\n value\n })\n\n if (show === 'esast') recmaPlugins.push([captureEsast])\n if (show === 'hast') rehypePlugins.push([captureHast])\n if (show === 'mdast') remarkPlugins.push([captureMdast])\n /** @type {UnistNode | undefined} */\n let ast\n\n await compile(file, {\n development: show === 'result' ? false : development,\n jsx: show === 'code' || show === 'esast' ? generateJsx : false,\n outputFormat:\n show === 'result' || outputFormatFunctionBody\n ? 'function-body'\n : 'program',\n recmaPlugins,\n rehypePlugins,\n remarkPlugins\n })\n\n if (show === 'result') {\n /** @type {MDXModule} */\n const result = await run(String(file), {\n Fragment,\n jsx,\n jsxs,\n baseUrl: window.location.href\n })\n\n return (\n \n
{result.default({})}
\n \n )\n }\n\n if (ast) {\n return (\n 
\n              \n                {toJsxRuntime(\n                  starryNight.highlight(\n                    JSON.stringify(ast, undefined, 2),\n                    'source.json'\n                  ),\n                  {Fragment, jsx, jsxs}\n                )}\n              \n
\n )\n }\n\n // `show === 'code'`\n return (\n 
\n            \n              {toJsxRuntime(starryNight.highlight(String(file), 'source.js'), {\n                Fragment,\n                jsx,\n                jsxs\n              })}\n            \n
\n )\n\n function captureMdast() {\n /**\n * @param {MdastRoot} tree\n * Tree.\n * @returns {undefined}\n * Nothing.\n */\n return function (tree) {\n const clone = structuredClone(tree)\n if (!positions) cleanUnistTree(clone)\n ast = clone\n }\n }\n\n function captureHast() {\n /**\n * @param {HastRoot} tree\n * Tree.\n * @returns {undefined}\n * Nothing.\n */\n return function (tree) {\n const clone = structuredClone(tree)\n if (!positions) cleanUnistTree(clone)\n ast = clone\n }\n }\n\n function captureEsast() {\n /**\n * @param {Program} tree\n * Tree.\n * @returns {undefined}\n * Nothing.\n */\n return function (tree) {\n const clone = structuredClone(tree)\n if (!positions) visitEstree(clone, removeFromEstree)\n ast = clone\n }\n }\n }\n },\n [\n development,\n directive,\n frontmatter,\n gfm,\n generateJsx,\n formatMarkdown,\n math,\n outputFormatFunctionBody,\n positions,\n raw,\n show,\n value\n ]\n )\n\n const scope = formatMarkdown ? 'text.md' : 'source.mdx'\n // Cast to actual value.\n const compiledResult = /** @type {EvalResult | undefined} */ (evalResult)\n /** @type {ReactNode | undefined} */\n let display\n\n if (compiledResult) {\n if (compiledResult.ok) {\n display = compiledResult.value\n } else {\n display = (\n
\n

Could not compile code:

\n \n
\n )\n }\n }\n\n return (\n <>\n
\n
\n
\n
\n {toJsxRuntime(starryNight.highlight(value, scope), {\n Fragment,\n jsx,\n jsxs\n })}\n {/* Trailing whitespace in a `textarea` is shown, but not in a `div`\n with `white-space: pre-wrap`.\n Add a `br` to make the last newline explicit. */}\n {/\\n[ \\t]*$/.test(value) ?
: undefined}\n
\n \n
\n
\n
\n
\n Show\n \n
\n
\n Plugin\n \n \n \n \n \n
\n
\n Input format\n \n \n
\n\n
\n Output format\n \n \n
\n\n
\n Development\n \n \n
\n\n
\n JSX\n \n \n
\n\n
\n Tree\n \n
\n
\n
\n {display}\n \n )\n}\n\n/**\n *\n * @param {Readonly} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nfunction ErrorFallback(properties) {\n // type-coverage:ignore-next-line\n const error = /** @type {Error} */ (properties.error)\n return (\n
\n

Something went wrong:

\n \n \n
\n )\n}\n\n/**\n * @param {DisplayProperties} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nfunction DisplayError(properties) {\n return (\n 
\n      \n        {String(\n          properties.error.stack\n            ? properties.error.message + '\\n' + properties.error.stack\n            : properties.error\n        )}\n      \n
\n )\n}\n\n/**\n * @param {HastRoot | MdastRoot} node\n * mdast or hast root.\n * @returns {undefined}\n * Nothing.\n */\nfunction cleanUnistTree(node) {\n removePosition(node, {force: true})\n visit(node, cleanUnistNode)\n}\n\n/**\n * @param {HastNodes | MdastNodes | MdxJsxAttribute | MdxJsxAttributeValueExpression | MdxJsxExpressionAttribute} node\n * Node.\n * @returns {undefined}\n * Nothing.\n */\nfunction cleanUnistNode(node) {\n if (\n node.type === 'mdxJsxAttribute' &&\n 'value' in node &&\n node.value &&\n typeof node.value === 'object'\n ) {\n cleanUnistNode(node.value)\n }\n\n if (\n 'attributes' in node &&\n node.attributes &&\n Array.isArray(node.attributes)\n ) {\n for (const attribute of node.attributes) {\n removePosition(attribute, {force: true})\n cleanUnistNode(attribute)\n }\n }\n\n if (node.data && 'estree' in node.data && node.data.estree) {\n visitEstree(node.data.estree, removeFromEstree)\n }\n}\n\n/**\n * @param {EstreeNode} node\n * estree node.\n * @returns {undefined}\n * Nothing.\n */\nfunction removeFromEstree(node) {\n delete node.loc\n delete node.start\n delete node.end\n delete node.range\n}\n" }, { "path": "docs/_asset/index.css", "content": ":root {\n --sans:\n system-ui, -apple-system, blinkmacsystemfont, 'Segoe UI', helvetica, arial,\n sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';\n --mono:\n 'San Francisco Mono', 'Monaco', 'Consolas', 'Lucida Console',\n 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;\n --white: #fff;\n --black: #1b1f24;\n --gray-0: #f6f8fa;\n --gray-1: #eaeef2;\n --gray-2: #d0d7de;\n --gray-3: #afb8c1;\n --gray-4: #8c959f;\n --gray-5: #6e7781;\n --gray-6: #57606a;\n --gray-7: #424a53;\n --gray-8: #32383f;\n --gray-9: #24292f;\n --blue-0: #ddf4ff;\n --blue-5: #0969da;\n --blue-9: #002155;\n --green-0: #dafbe1;\n --green-5: #1a7f37;\n --green-9: #002d11;\n --yellow-0: #fff8c5;\n --yellow-5: #9a6700;\n --yellow-9: #3b2300;\n --orange-0: #fff1e5;\n --orange-5: #bc4c00;\n --orange-9: #471700;\n --red-0: #ffebe9;\n --red-5: #cf222e;\n --red-9: #4c0014;\n --purple-0: #fbefff;\n --purple-5: #8250df;\n --purple-9: #2e1461;\n --pink-0: #ffeff7;\n --pink-5: #bf3989;\n --pink-9: #4d0336;\n --coral-0: #fff0eb;\n --coral-5: #c4432b;\n --coral-9: #510901;\n --mdx-yellow: hsl(39deg 97% 58%);\n --hl: var(--blue-5);\n --fg: var(--black);\n --bg: var(--white);\n\n /* We manually add a blur on `::before` of the container, so no background needed. */\n --docsearch-container-background: transparent !important;\n --docsearch-footer-background: var(--white) !important;\n --docsearch-footer-shadow: 0 -1px 0 0 var(--gray-2) !important;\n --docsearch-highlight-color: var(--hl) !important;\n --docsearch-hit-color: var(--gray-7) !important;\n --docsearch-hit-shadow: inset 0 0 0 1px var(--gray-2) !important;\n /* This is actually used in a `background` field so does not have to be a gradient. */\n --docsearch-key-gradient: var(--gray-0) !important;\n --docsearch-key-pressed-shadow: none !important;\n --docsearch-key-shadow: inset 0 -1px 0 var(--gray-4) !important;\n --docsearch-modal-background: var(--white) !important;\n /* Card shadow: */\n --docsearch-modal-shadow:\n 0 0 0 0.2em rgb(3 102 214 / 0%), 0 13px 27px -5px rgb(50 50 93 / 25%),\n 0 8px 16px -8px rgb(0 0 0 / 30%), 0 -6px 16px -6px rgb(0 0 0 / 2.5%) !important;\n /* Use the regular color: */\n --docsearch-muted-color: var(--black) !important;\n --docsearch-primary-color: var(--hl) !important;\n --docsearch-searchbox-background: var(--white) !important;\n --docsearch-searchbox-focus-background: var(--gray-0) !important;\n --docsearch-searchbox-shadow: inset 0 0 0 2px var(--hl) !important;\n --docsearch-text-color: var(--black) !important;\n}\n\n* {\n box-sizing: border-box;\n}\n\nhtml {\n color-scheme: light dark;\n accent-color: var(--hl);\n -ms-text-size-adjust: 100%;\n -webkit-text-size-adjust: 100%;\n word-wrap: break-word;\n font-kerning: normal;\n font-family: var(--sans);\n font-feature-settings: 'kern', 'liga', 'clig', 'calt';\n line-height: calc(1em + 1ex);\n}\n\nbutton,\ninput {\n font-family: inherit;\n font-size: inherit;\n}\n\nkbd,\npre,\ncode,\n.playground-write,\n.playground-draw {\n font-family: var(--mono);\n font-feature-settings: normal;\n font-size: smaller;\n line-height: calc(1em + (1 / 0.8 * 1ex));\n}\n\nbody {\n margin: 0;\n background-color: var(--bg);\n color: var(--fg);\n}\n\nh1,\nh2,\nh3,\nh4,\nh5,\nh6,\nstrong,\nth {\n font-weight: 700;\n letter-spacing: 0.0125em;\n}\n\nsup {\n vertical-align: top;\n}\n\nmain {\n margin-block-start: calc(5.5 * (1em + 1ex));\n}\n\ndd,\n.content {\n padding-inline: calc(1em + 1ex);\n}\n\nlabel {\n display: block;\n}\n\nh1,\nh2,\nh3,\nh4,\nh5,\nh6,\nlabel,\np,\npre,\nol,\nul,\nhr,\ntable,\nblockquote,\n.block,\n.frame {\n margin-block: calc(1em + 1ex);\n}\n\nsummary {\n cursor: pointer;\n}\n\n.anchor {\n display: inline-block;\n width: calc(1em + 1ex);\n margin-inline-start: calc(-0.75 * (1em + 1ex));\n margin-inline-end: calc(-0.25 * (1em + 1ex));\n font-size: 1rem;\n}\n\na[name],\nh1,\nh2,\nh3,\nh4,\nh5,\nh6 {\n display: block;\n scroll-margin-block-start: 6rem;\n}\n\nh1,\nh2 {\n font-size: 2.5em;\n line-height: calc(1em + (1 / 2.5 * 1ex));\n margin-block: calc(1 / 2.5 * (1em + 1ex));\n}\n\n.head-article,\n.foot-article,\n.foot-site {\n position: relative;\n}\n\n.foot-site {\n background-color: var(--gray-0);\n}\n\n.foot-article,\n.foot-site {\n margin-block-start: calc(1 * (1em + 1ex));\n border-block-start: 1px solid var(--gray-2);\n}\n\n.head-article {\n margin-block-end: calc(1 * (1em + 1ex));\n}\n\n.navigation,\n.head-article {\n border-block-end: 1px solid var(--gray-2);\n}\n\n.article-row {\n display: flex;\n justify-content: space-between;\n}\n\n.article-row-start,\n.article-row-end {\n font-size: smaller;\n line-height: calc(1em + (1 / 0.8 * 1ex));\n flex-basis: 0;\n flex-grow: 1;\n}\n\n.article-row-end {\n margin-inline-start: auto;\n text-align: end;\n}\n\n.foot-site {\n padding-block: 1px;\n}\n\nh3 {\n font-size: 2em;\n line-height: calc(1em + (1 / 1.5 * 1ex));\n margin-block: calc(1 / 1.5 * (1em + 1ex));\n}\n\nh4 {\n font-size: 1.25em;\n line-height: calc(1em + (1 / 1.25 * 1ex));\n margin-block: calc(1 / 1.25 * (1em + 1ex));\n}\n\nh5,\nh6 {\n font-size: 1em;\n line-height: calc(1em + 1ex);\n margin-block: calc(1em + 1ex);\n}\n\nh6 {\n color: var(--gray-6);\n}\n\nimg,\nsvg {\n max-width: 100%;\n background-color: transparent;\n}\n\nimg[align='right'] {\n padding-inline-start: calc(1em + 1ex);\n}\n\nimg[align='left'] {\n padding-inline-end: calc(1em + 1ex);\n}\n\nkbd {\n background-color: var(--gray-0);\n border: 1px solid var(--gray-3);\n border-radius: 3px;\n box-shadow: inset 0 -1px 0 var(--gray-4);\n color: var(--gray-9);\n padding: 0.2em 0.4em;\n}\n\npre {\n word-wrap: normal;\n overflow: auto;\n font-size: inherit;\n}\n\nblockquote pre,\nli pre {\n margin-inline: 0;\n}\n\ncode {\n background-color: var(--gray-0);\n}\n\ncode {\n border-radius: 3px;\n padding-block: calc(0.33 * (1 / 0.8 * 1ex));\n padding-inline: calc(0.66 * (1 / 0.8 * 1ex));\n}\n\npre code {\n display: block;\n padding: calc(1em + 1ex) !important;\n white-space: pre;\n word-break: normal;\n overflow-x: auto;\n /* overflow: visible; */\n word-wrap: normal;\n\n mask-image: paint(squircle);\n --squircle-radius: 10px;\n border-radius: 10px;\n}\n\n.frame-tab-item {\n background-color: var(--gray-1);\n transition: 200ms;\n transition-property: color, background-color;\n}\n\npre code,\n.frame-body,\n.frame-tab-item-selected {\n background-color: #fafafa !important; /* Color from one-light */\n}\n\n.frame-body-box {\n padding: calc(1em + 1ex);\n}\n\n.frame-tab-item-dark.frame-tab-item-selected {\n background-color: #282c34 !important;\n color: var(--white);\n}\n\n.frame-body > pre:only-child {\n margin-block: 0;\n}\n\n.frame-tab-item-inactive {\n background-color: transparent;\n color: var(--gray-6);\n}\n\nhr {\n background-color: var(--gray-1);\n border: 0;\n border-radius: 3px;\n height: calc(0.25 * (1em + 1ex));\n}\n\ntable {\n border-collapse: collapse;\n border-spacing: 0;\n overflow: auto;\n width: 100%;\n font-variant-numeric: lining-nums;\n}\n\ntr {\n border-block-start: 1px solid var(--gray-3);\n}\n\ntr:nth-child(even) {\n background-color: hsl(210deg 17% 82% / 20%); /* gray-1 */\n}\n\ntd,\nth {\n border: 1px solid var(--gray-3);\n padding-block: calc(0.33 * (1 / 0.8 * 1ex));\n padding-inline: calc(0.66 * (1 / 0.8 * 1ex));\n}\n\nblockquote {\n color: var(--gray-6);\n margin-inline-start: 0;\n padding-inline-start: calc(1em + 1ex);\n position: relative;\n}\n\nblockquote::before {\n content: '';\n display: block;\n width: calc(0.25 * (1em + 1ex));\n height: 100%;\n background-color: var(--gray-1);\n border-radius: 3px;\n position: absolute;\n inset-inline-start: 0;\n}\n\nol,\nul {\n padding-inline-start: 0;\n}\n\nul {\n list-style-type: circle;\n}\n\nol {\n list-style-type: decimal;\n}\n\nul ul,\nol ul,\nul ol,\nol ol {\n margin-block: 0;\n}\n\nul ul {\n list-style-type: disc;\n}\n\nul ul ul {\n list-style-type: square;\n}\n\nol ol {\n list-style-type: lower-roman;\n}\n\nol ol ol {\n list-style-type: lower-alpha;\n}\n\nli {\n word-wrap: break-all;\n margin-block: calc(0.25 * (1em + 1ex));\n margin-inline-start: calc(1em + 1ex);\n}\n\n.task-list-item {\n list-style-type: none;\n margin-inline-start: 0;\n}\n\n.task-list-item input {\n margin: 0;\n margin-inline-end: calc(0.25 * (1em + 1ex));\n}\n\ndt {\n font-style: italic;\n margin-block-end: 0;\n}\n\ndt + dt {\n margin-block-start: 0;\n}\n\ndd {\n margin-block-start: 0;\n}\n\na {\n color: var(--hl);\n transition: 200ms;\n transition-property: color;\n}\n\na.alt {\n color: var(--purple-5);\n}\n\n.navigation a {\n display: block;\n color: inherit;\n text-decoration: none;\n}\n\na[aria-current],\na:hover,\na:focus {\n color: inherit;\n text-decoration: none;\n}\n\nnav a[aria-current],\nnav a:hover,\nnav a:focus {\n color: var(--hl);\n text-decoration: underline;\n}\n\nbutton,\na.cta {\n outline: 0;\n padding: calc(0.25 * (1em + 1ex)) calc(0.5 * (1em + 1ex));\n border-radius: 3px;\n border: 1px solid currentColor;\n color: var(--black);\n transition: 200ms;\n transition-property: color, background-color, border-color, box-shadow;\n font-weight: 400;\n background-color: transparent;\n}\n\na.cta:hover,\na.cta:focus,\na.cta:active,\nbutton:hover,\nbutton:focus,\nbutton:active {\n color: var(--hl);\n}\n\na.cta:active,\nbutton:active,\na.cta.active,\nbutton.active {\n background-color: var(--hl);\n border-color: var(--hl);\n color: var(--white);\n}\n\na.cta:active,\na.cta.active,\na.cta:focus,\nbutton.active,\nbutton:active,\nbutton:focus {\n box-shadow: 0 0 0 0.2em rgb(191 135 0 / 30%); /* --hl */\n}\n\na.cta.success,\nbutton.success {\n background-color: var(--green-5);\n border-color: var(--green-5);\n box-shadow: 0 0 0 0.2em rgb(26 127 55 / 30%); /* --green-5 */\n color: var(--white);\n}\n\n.content {\n width: 100%;\n max-width: calc(36 * (1em + 1ex));\n margin: calc(1 * (1em + 1ex)) auto;\n}\n\n.navigation {\n position: fixed;\n inset-inline: 0;\n inset-block-start: 0;\n display: flex;\n padding: calc(0.5 * (1em + 1ex));\n padding-top: calc(2 * (1em + 1ex));\n}\n\n.navigation::before,\n.DocSearch-Container::before {\n content: '';\n inset: 0;\n position: absolute;\n z-index: 2;\n background-image: radial-gradient(\n ellipse at 50% 0%,\n hsl(39deg 97% 88% / 90%) 0%,\n hsl(39deg 97% 96% / 90%) 100%\n );\n}\n\n.DocSearch li {\n margin: 0;\n}\n\n#banner {\n padding: calc(0.25 * (1em + 1ex));\n background-color: var(--mdx-yellow);\n color: var(--white);\n position: absolute;\n left: 0;\n top: 0;\n right: 0;\n text-align: center;\n z-index: 10;\n font-weight: bolder;\n letter-spacing: 1px;\n}\n\n.full-bleed {\n width: 100vw;\n position: relative;\n left: 50%;\n right: 50%;\n margin-left: -50vw;\n margin-right: -50vw;\n padding-inline: calc(1em + 1ex);\n}\n\n/* Note that the `backdrop-filter` itself is applied in light mode. */\n@supports (backdrop-filter: blur(1ex)) {\n .navigation::before,\n .DocSearch-Container::before {\n backdrop-filter: saturate(200%) blur(1ex);\n background-image: radial-gradient(\n ellipse at 50% 0%,\n hsl(39deg 97% 88% / 60%) 0%,\n hsl(39deg 97% 98% / 60%) 80%\n );\n }\n}\n\n.DocSearch-Modal,\n.navigation-primary,\n.navigation-secondary,\n.navigation-search,\n.navigation-tertiary {\n z-index: 3;\n}\n\n.navigation .icon {\n display: block;\n width: auto;\n height: calc(1em + 1ex);\n}\n\n.navigation-primary,\n.navigation-secondary,\n.navigation-tertiary,\n.navigation-primary h1,\n.navigation-secondary li,\n.navigation-tertiary li {\n margin: 0;\n}\n\n.navigation-primary,\n.navigation-secondary,\n.navigation-search,\n.navigation-tertiary {\n margin: 0;\n padding: calc(0.5 * (1em + 1ex));\n display: flex;\n list-style-type: none;\n}\n\n.navigation-search {\n padding: calc(0.25em + 0.25ex);\n}\n\n.DocSearch-Button {\n margin: 0 !important;\n}\n\n.navigation-primary h1,\n.navigation-secondary li,\n.navigation-tertiary li {\n padding: 0;\n}\n\n.navigation-primary h1 {\n font-size: 1em;\n border-bottom-width: 0;\n}\n\n.navigation-tertiary {\n justify-content: flex-end;\n}\n\n.navigation-secondary {\n z-index: 3;\n overflow-x: auto;\n overflow-y: hidden;\n flex: 1;\n flex-direction: row;\n align-items: stretch;\n flex-grow: 1;\n mask-image: linear-gradient(\n to right,\n transparent,\n black 2ex,\n black calc(100% - 2ex),\n transparent\n );\n}\n\n.navigation-secondary li {\n white-space: nowrap;\n}\n\n.navigation-secondary li + li {\n padding-inline-start: calc(0.5 * (1em + 1ex));\n}\n\n/* Some extra spacing because otherwise the blur is shown over it. */\n.navigation-secondary li:last-child {\n padding-inline-end: calc(0.5 * (1em + 1ex));\n}\n\n.navigation-secondary ol,\n.navigation-show-big {\n display: none;\n}\n\n.navigation-tertiary li + li {\n padding-inline-start: calc(0.5 * (1em + 1ex));\n}\n\n.skip-to-navigation {\n inset-block-start: 0;\n inset-inline-start: 0;\n}\n\n.skip-to-content,\n.skip-to-navigation {\n position: absolute;\n width: 1px;\n height: 1px;\n margin: 0;\n overflow: hidden;\n clip: rect(1px, 1px, 1px, 1px);\n}\n\n.skip-to-content:focus,\n.skip-to-navigation:focus {\n z-index: 4;\n width: auto;\n height: auto;\n clip: auto;\n background-color: var(--hl);\n color: var(--white);\n padding: calc(1em + 1ex);\n}\n\n.note {\n color: var(--gray-9);\n font-size: smaller;\n line-height: calc(1em + (1 / 0.8 * 1ex));\n padding-inline: calc(1 / 0.8 * (1em + 1ex));\n margin-block: calc(1 / 0.8 * (1em + 1ex));\n position: relative;\n z-index: 0;\n inset: 0;\n mask-image: paint(squircle);\n --squircle-radius: 10px;\n border-radius: 10px;\n border: 1px solid transparent;\n\n /* Actually the border color: */\n background-color: var(--purple-5);\n}\n\n.note::after {\n content: '';\n position: absolute;\n mask-image: paint(squircle);\n z-index: -1;\n background-color: hsl(9deg 64% 8%);\n inset: 0;\n --squircle-radius: 9px;\n border-radius: 9px;\n\n background-color: var(--purple-0);\n}\n\n.legacy {\n background-color: var(--gray-5);\n}\n\n.legacy::after {\n background-color: var(--gray-0);\n}\n\n.important {\n background-color: var(--red-5);\n}\n\n.important::after {\n background-color: var(--red-0);\n}\n\n.card {\n display: block;\n padding: calc(1 * (1em + 1ex));\n margin-block: calc(2 * (1em + 1ex));\n overflow: hidden;\n /* yellow */\n background-image:\n radial-gradient(\n ellipse at 0% 0%,\n rgb(252 180 45 / 5%) 20%,\n rgb(252 180 45 / 0%) 80%\n ),\n /* purple */\n radial-gradient(\n ellipse at 0% 100%,\n rgb(130 80 223 / 5%) 20%,\n rgb(130 80 223 / 0%) 80%\n );\n\n mask-image: paint(squircle);\n --squircle-radius: 20px;\n border-radius: 20px;\n}\n\n.emoji-list > ul {\n list-style-type: none;\n}\n\n.emoji-list > ul > li {\n margin-inline-start: 0;\n}\n\n.big {\n font-size: larger;\n line-height: calc(1em + (1 / 1.2 * 1ex));\n padding: calc(1 / 1.2 * (1em + 1ex));\n margin-block: calc(1 / 1.2 * (1em + 1ex));\n}\n\n.frame {\n /* gray-1 is used for unselected tabs, but gray-2 is really too much\n * This is a perfect mix between the two: */\n background-color: hsl(210, 20.5%, 88.8%);\n position: relative;\n\n mask-image: paint(squircle);\n --squircle-radius: 10px;\n border-radius: 10px;\n}\n\n.frame-resizeable {\n display: flex;\n flex-direction: column;\n overflow: auto;\n\n min-height: 10rem;\n height: 24rem;\n resize: vertical;\n}\n\n.frame-tab-bar {\n flex-shrink: 0;\n display: flex;\n flex-direction: row;\n align-items: stretch;\n margin-block-start: calc(1em + 1ex);\n list-style-type: none;\n margin: 0;\n padding: calc(0.25em + 0.25ex);\n padding-block-end: 0;\n}\n\n.frame-tab-bar-scroll {\n overflow-x: auto;\n overflow-y: hidden;\n mask-image: linear-gradient(\n to right,\n hsl(0deg 0% 100% / 30%),\n black calc(0.5 * (1em + 1ex)),\n black calc(100% - 0.5 * (1em + 1ex)),\n hsl(0deg 0% 100% / 30%)\n );\n}\n\n.frame-body {\n border-bottom-left-radius: 3px;\n border-bottom-right-radius: 3px;\n}\n\n.frame-body > pre {\n flex-grow: 1;\n display: flex;\n flex-direction: column;\n overflow: hidden;\n}\n\n.frame-body > pre > code {\n overflow-x: auto;\n overflow-y: auto;\n}\n\n.frame-tab-bar + pre,\n.frame-tab-bar + .highlight > pre {\n margin-block-start: 0;\n}\n\n.frame-tab-bar + pre code,\n.frame-tab-bar + .highlight > pre code {\n --squircle-radius: 0;\n border-top-left-radius: 0;\n border-top-right-radius: 0;\n}\n\n.frame-tab-item {\n font-family: var(--mono);\n font-size: smaller;\n line-height: calc(1em + (1 / 0.8 * 1ex));\n padding-block: calc(1 / 0.8 * 0.25 * (1em + 1ex));\n padding-inline: calc(1 / 0.8 * 0.5 * (1em + 1ex));\n margin: calc(1 / 0.8 * 0.25 * (1em + 1ex));\n margin-block-end: 0;\n border-top-left-radius: 2px;\n border-top-right-radius: 2px;\n white-space: nowrap;\n}\n\n.frame-tab-item-language {\n margin-left: auto;\n padding-inline: 0;\n}\n\n.code-frame .copy-button {\n position: absolute;\n inset-block-end: 0;\n inset-inline-end: 0;\n /* Lines it out nicely if there’s just one line of code. */\n margin: calc(0.618 * (1em + 1ex));\n backdrop-filter: saturate(200%) blur(1ex);\n}\n\n#markdown-for-thecomponent-era {\n font-weight: 600;\n}\n\n#markdown-for-thecomponent-era strong {\n color: var(--mdx-yellow);\n}\n\n.home hr {\n height: 0;\n background-color: transparent;\n}\n\n.home-preview {\n position: relative;\n border: 1px solid transparent;\n padding: calc(1em + 1ex);\n background-color: var(--gray-2);\n mask-image: paint(squircle);\n z-index: 0;\n --squircle-radius: 10px;\n border-radius: 10px;\n}\n\n.home-preview::after {\n content: '';\n position: absolute;\n inset: 0;\n z-index: -1;\n background-color: var(--bg);\n mask-image: paint(squircle);\n --squircle-radius: 9px;\n border-radius: 9px;\n}\n\n:is(.home-preview, .card, .frame-body, .nav-description, .big-columns > *)\n > :is(h1, h2, h3, h4, p, .block):first-child {\n margin-block-start: 0;\n}\n\n:is(.home-preview, .card, .frame-body, .nav-description, .big-columns > *)\n > :is(h1, h2, h3, h4, p, .block):last-child {\n margin-block-end: 0;\n}\n\n.home .anchor {\n display: none;\n}\n\n.snowfall {\n display: flex;\n align-items: flex-end;\n justify-content: center;\n}\n\n.snowfall-bar {\n flex-basis: 0;\n flex-grow: 1;\n margin: calc(0.125 * (1em + 1ex));\n background-color: var(--fg);\n}\n\ndetails {\n border: 1px solid var(--gray-2);\n padding: 1ex;\n border-radius: 3px;\n}\n\ndetails[open] {\n padding: calc(1em + 1ex);\n}\n\n.rehype-twoslash-completion-deprecated {\n opacity: 0.5;\n}\n\n.rehype-twoslash-popover-target {\n cursor: default;\n}\n\n.highlight:is(:hover, :focus-within) .rehype-twoslash-popover-target {\n background-color: var(--gray-2);\n}\n\n/* Wavy underline for errors. */\n.rehype-twoslash-error-target {\n background-repeat: repeat-x;\n background-position: bottom left;\n background-image: url('data:image/svg+xml,');\n}\n\n/* The content that will be shown in the tooltip. */\n.rehype-twoslash-popover {\n position: absolute;\n max-width: calc(45 * (1em + 1ex));\n padding: calc(0.5 * (1em + 1ex));\n margin: 0;\n background-color: var(--bg);\n border: 1px solid var(--gray-2);\n border-radius: 3px;\n}\n\n/* No padding if we have a padded code block (and perhaps more blocks) */\n.rehype-twoslash-popover:has(.rehype-twoslash-popover-code) {\n padding: 0;\n}\n\n.rehype-twoslash-popover-code {\n margin: 0;\n}\n\n.rehype-twoslash-popover-code > code {\n mask-image: none;\n border-radius: 0;\n}\n\n.rehype-twoslash-popover-description {\n background-color: var(--bg);\n padding: 0 1em;\n}\n\n@media (prefers-color-scheme: dark) {\n :root {\n --white: #f0f6fc;\n --black: #010409;\n --gray-0: var(--white);\n --gray-1: #c9d1d9;\n --gray-2: #b1bac4;\n --gray-3: #8b949e;\n --gray-4: #6e7681;\n --gray-5: #484f58;\n --gray-6: #30363d;\n --gray-7: #21262d;\n --gray-8: #161b22;\n --gray-9: #0d1117;\n --hl: var(--mdx-yellow);\n --fg: var(--white);\n --bg: var(--black);\n\n --docsearch-key-gradient: #eaeef2 !important;\n }\n\n .navigation-secondary a {\n display: initial;\n }\n\n .note {\n color: var(--gray-0);\n }\n\n .note::after {\n background-color: var(--purple-9);\n }\n\n .legacy::after {\n background-color: var(--gray-9);\n }\n\n .important::after {\n background-color: var(--red-9);\n }\n\n .navigation::before {\n background-image: radial-gradient(\n ellipse at 50% 0%,\n hsl(39deg 97% 12% / 90%) 0%,\n hsl(39deg 97% 4% / 90%) 100%\n );\n }\n\n /* Note that the `backdrop-filter` itself is applied in light mode. */\n @supports (backdrop-filter: blur(1ex)) {\n .navigation::before {\n background-image: radial-gradient(\n ellipse at 50% 0%,\n hsl(39deg 97% 12% / 60%) 0%,\n hsl(39deg 97% 4% / 60%) 90%\n );\n }\n }\n\n .card {\n /* yellow */\n background-image:\n radial-gradient(\n ellipse at 0% 0%,\n rgb(252 180 45 / 10%) 20%,\n rgb(252 180 45 / 0%) 80%\n ),\n /* purple */\n radial-gradient(\n ellipse at 0% 100%,\n rgb(130 80 223 / 10%) 20%,\n rgb(130 80 223 / 0%) 80%\n );\n }\n\n .foot-article,\n .foot-site {\n border-top-color: var(--gray-6);\n }\n\n .navigation,\n .head-article {\n border-bottom-color: var(--gray-6);\n }\n\n .home-preview {\n background-color: var(--gray-6);\n }\n\n .foot-site {\n background-color: var(--gray-8);\n }\n\n .highlight:is(:hover, :focus-within) .rehype-twoslash-popover-target {\n background-color: var(--gray-5);\n }\n\n .rehype-twoslash-popover {\n border-color: var(--gray-6);\n }\n\n h6 {\n color: var(--gray-3);\n }\n\n kbd {\n background-color: var(--black);\n border-color: var(--gray-6);\n box-shadow: inset 0 -1px 0 var(--gray-6);\n color: var(--gray-0);\n }\n\n code {\n background-color: var(--gray-6);\n }\n\n .frame {\n background-color: var(--gray-9);\n }\n\n .frame-tab-item {\n background-color: var(--gray-8);\n }\n\n pre code,\n .frame-body,\n .frame-tab-item-selected,\n .frame-tab-item-dark.frame-tab-item-selected {\n background-color: var(--gray-7) !important;\n }\n\n .frame-tab-item-inactive {\n background-color: transparent;\n color: var(--gray-3);\n }\n\n hr {\n background-color: var(--gray-6);\n }\n\n tr {\n background-color: var(--gray-9);\n border-top-color: var(--gray-6);\n }\n\n tr:nth-child(2n) {\n background-color: var(--gray-8);\n color: var(--white);\n }\n\n td,\n th {\n border-color: var(--gray-4);\n }\n\n blockquote {\n color: var(--gray-2);\n }\n\n blockquote::before {\n background-color: var(--gray-4);\n }\n\n a.cta,\n button {\n color: var(--gray-0);\n border-color: currentColor;\n background-color: transparent;\n }\n\n a.cta:hover,\n a.cta:focus,\n a.cta:active,\n button:hover,\n button:focus,\n button:active {\n border-color: var(--hl);\n }\n\n a.cta:active,\n button:active {\n background-color: var(--hl);\n color: var(--gray-0);\n }\n\n a.cta.success,\n button.success {\n background-color: var(--green-5);\n border-color: var(--green-5);\n color: var(--white);\n }\n\n details {\n border-color: var(--gray-6);\n }\n}\n\n@media (min-width: 22em) {\n #markdown-for-thecomponent-era {\n font-size: 2rem;\n line-height: calc(1em + (1 / 2 * 1ex));\n margin-block: calc(1 / 2 * (1em + 1ex));\n }\n}\n\n@media (min-width: 40em) {\n html {\n font-size: 1.125em;\n }\n\n .navigation-search {\n padding: calc(0.3em + 0.3ex);\n }\n\n #markdown-for-thecomponent-era {\n font-size: 3rem;\n line-height: calc(1em + (1 / 3 * 1ex));\n margin-block: calc(1 / 3 * (1em + 1ex));\n padding-block: calc(1 / 3 * (1em + 1ex));\n }\n\n .foot-article,\n .foot-site {\n margin-block-start: calc(2 * (1em + 1ex));\n }\n\n .head-article {\n margin-block-end: calc(2 * (1em + 1ex));\n }\n\n .foot-site {\n padding-block: calc(1 * (1em + 1ex));\n }\n\n .big {\n padding: calc(2 * (1em + 1ex));\n }\n\n .big.card {\n margin-block: calc(2 * (1em + 1ex));\n }\n}\n\n@media (min-width: 56em) {\n #markdown-for-thecomponent-era {\n font-size: 5rem;\n line-height: calc(1em + (1 / 5 * 1ex));\n margin-block: calc(1 / 5 * (1em + 1ex));\n padding-block: calc(2 * 1 / 5 * (1em + 1ex));\n }\n\n .playground {\n display: grid;\n grid-template-columns: 49% 49%;\n }\n}\n\n@media (min-width: 64em) {\n .navigation-show-big {\n display: block;\n }\n\n .big {\n padding: calc(1.66 * (1em + 1ex));\n }\n\n .big.card {\n margin-block: calc(1.66 * (1em + 1ex));\n }\n\n /* Assume they don’t scroll anymore. */\n .frame-tab-bar-scroll,\n .navigation-secondary {\n mask-image: initial;\n }\n}\n\n@media (min-width: 76em) {\n #markdown-for-thecomponent-era {\n font-size: 5.9rem;\n line-height: calc(1em + (1 / 6 * 1ex));\n margin-block: calc(1 / 6 * (1em + 1ex));\n }\n\n .big-columns {\n display: flex;\n justify-content: space-between;\n margin: 0 calc(-1 * (1em + 1ex));\n }\n\n .big-columns > * {\n width: calc(15 * (1em + 1ex));\n flex: 1;\n margin: 0 calc(1em + 1ex);\n }\n}\n\n.playground {\n min-height: 40rem;\n gap: calc(1em + 1ex);\n}\n\n.playground-area,\n.playground-controls,\n.playground-result {\n overflow: auto;\n border-radius: 1ex;\n padding: 1em;\n margin-block: calc(1em + 1ex);\n}\n\n.playground-area {\n background-color: rgba(255, 255, 255, 0.1);\n}\n\n.playground-controls,\n.playground-result {\n border: 1px solid rgba(255, 255, 255, 0.1);\n}\n\n.playground-inner {\n position: relative;\n max-width: 100%;\n overflow: hidden;\n min-height: calc(10 * (1em + 1ex));\n}\n\n.playground-write,\n.playground-draw {\n font-size: 14px;\n tab-size: 4;\n letter-spacing: normal;\n line-height: calc(1 * (1em + 1ex));\n white-space: pre-wrap;\n word-wrap: break-word;\n background: transparent;\n box-sizing: border-box;\n border: none;\n outline: none;\n margin: 0;\n padding: 0;\n width: 100%;\n height: 100%;\n overflow: hidden;\n resize: none;\n}\n\n.playground-write::selection {\n color: var(--fg);\n background-color: hsl(42.22deg 74.31% 57.25% / 66%);\n}\n\n.playground-write {\n position: absolute;\n top: 0;\n -webkit-print-color-adjust: exact;\n print-color-adjust: exact;\n color: transparent;\n caret-color: var(--hl);\n}\n\n.playground-controls fieldset {\n border: 0;\n padding: 0;\n margin-inline: 0;\n}\n\n.playground-controls fieldset[disabled] {\n opacity: 0.6;\n}\n\n.playground-controls label {\n font-size: smaller;\n display: block;\n margin-block: calc(0.5 * (1em + 1ex));\n}\n\n.playground-controls select {\n padding: 0.5ex;\n}\n\n/* Can’t have bold things; they mess with the textarea */\n.playground .pl-mh,\n.playground .pl-mh .pl-en,\n.playground .pl-ms {\n font-weight: normal !important;\n}\n" }, { "path": "docs/_asset/index.js", "content": "/* eslint-disable unicorn/prefer-query-selector */\n/// \n\nimport docsearch_ from '@docsearch/js'\nimport {computePosition, shift} from '@floating-ui/dom'\nimport copyToClipboard from 'copy-to-clipboard'\nimport {ok as assert} from 'devlop'\n\n// Squircles.\nif ('paintWorklet' in CSS) {\n // @ts-expect-error: TS doesn’t understand Houdini.\n CSS.paintWorklet.addModule(\n 'https://www.unpkg.com/css-houdini-squircle@0.2.1/squircle.min.js'\n )\n}\n\n// Copy buttons.\nconst copies = Array.from(document.querySelectorAll('button.copy-button'))\nconst copyTemplate = document.createElement('template')\nconst copiedTemplate = document.createElement('template')\ncopyTemplate.innerHTML = `\n Copy\n \n \n`\ncopiedTemplate.innerHTML = `\n Copied!\n \n`\nconst copyIcon = copyTemplate.content.querySelector('svg')\nconst copiedIcon = copiedTemplate.content.querySelector('svg')\nassert(copyIcon)\nassert(copiedIcon)\n\nfor (const copy of copies) {\n assert(copy instanceof HTMLButtonElement)\n copy.type = 'button'\n copy.replaceChildren(copyIcon.cloneNode(true))\n copy.addEventListener('click', oncopyonclick)\n}\n\nconst popoverTargets = /** @type {Array} */ (\n Array.from(document.querySelectorAll('.rehype-twoslash-popover-target'))\n)\n\nfor (const popoverTarget of popoverTargets) {\n /** @type {NodeJS.Timeout | number} */\n let timeout = 0\n\n popoverTarget.addEventListener('click', function () {\n popoverShow(popoverTarget)\n })\n\n popoverTarget.addEventListener('mouseenter', function () {\n clearTimeout(timeout)\n timeout = setTimeout(function () {\n popoverShow(popoverTarget)\n }, 300)\n })\n\n popoverTarget.addEventListener('mouseleave', function () {\n clearTimeout(timeout)\n })\n\n if (popoverTarget.classList.contains('rehype-twoslash-autoshow')) {\n popoverShow(popoverTarget)\n }\n}\n\n/**\n * @this {HTMLButtonElement}\n * Button element.\n * @returns {undefined}\n * Nothing.\n */\nfunction oncopyonclick() {\n assert(copyIcon)\n assert(copiedIcon)\n assert(this instanceof HTMLButtonElement)\n\n const value = this.dataset.value\n assert(value !== undefined)\n\n this.classList.add('success')\n this.replaceChildren(copiedIcon.cloneNode(true))\n\n copyToClipboard(value)\n\n setTimeout(() => {\n this.classList.remove('success')\n this.replaceChildren(copyIcon.cloneNode(true))\n }, 2000)\n}\n\n/**\n * @param {HTMLElement} popoverTarget\n * Popover target.\n * @returns {undefined}\n * Nothing.\n */\nfunction popoverShow(popoverTarget) {\n const id = popoverTarget.dataset.popoverTarget\n if (!id) return\n const popover = document.getElementById(id)\n if (!popover) return\n\n popover.showPopover()\n\n computePosition(popoverTarget, popover, {\n placement: 'bottom',\n middleware: [shift({padding: 5})]\n }).then(\n /**\n * @param {{x: number, y: number}} value\n */\n function (value) {\n popover.style.left = value.x + 'px'\n popover.style.top = value.y + 'px'\n }\n )\n}\n\n// Docsearch.\n// Note: types are wrong.\nconst docsearch = /** @type {import('@docsearch/js')['default']} */ (\n /** @type {unknown} */ (docsearch_)\n)\n\ndocsearch({\n appId: 'B0O9AAZ9L2',\n apiKey: '71f38eae605e3e6d500368617e32c19f',\n container: '#docsearch',\n indexName: 'mdxjs'\n})\n" }, { "path": "docs/_component/blog.jsx", "content": "/**\n * @import {ReactNode} from 'react'\n * @import {Item} from './sort.js'\n */\n\n/**\n * @typedef EntryProperties\n * Properties for `BlogEntry`.\n * @property {Readonly} item\n * Item.\n *\n * @typedef GroupProperties\n * Properties for `BlogGroup`.\n * @property {string | undefined} [className]\n * Class name.\n * @property {ReadonlyArray} items\n * Items.\n * @property {string | undefined} [sort]\n * Fields to sort on.\n */\n\nimport {apStyleTitleCase} from 'ap-style-title-case'\nimport {toJsxRuntime} from 'hast-util-to-jsx-runtime'\nimport React from 'react'\nimport {Fragment, jsx, jsxs} from 'react/jsx-runtime'\nimport {sortItems} from './sort.js'\n\nconst dateTimeFormat = new Intl.DateTimeFormat('en', {dateStyle: 'long'})\n\n/**\n * @param {Readonly} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nexport function BlogEntry(properties) {\n const {item} = properties\n const {data, name} = item\n const {matter = {}, meta = {}} = data\n const title = matter.title || meta.title\n const defaultTitle = apStyleTitleCase(\n name.replace(/\\/$/, '').split('/').pop()\n )\n const description = matter.description || meta.description\n const time = (\n meta.readingTime\n ? Array.isArray(meta.readingTime)\n ? meta.readingTime\n : [meta.readingTime, meta.readingTime]\n : []\n ).map(function (d) {\n return Math.ceil(d)\n })\n /** @type {string | undefined} */\n let timeLabel\n\n if (time.length > 1 && time[0] !== time[1]) {\n timeLabel = time[0] + '-' + time[1] + ' minutes'\n } else if (time[0]) {\n timeLabel = time[0] + ' minute' + (time[0] > 1 ? 's' : '')\n }\n\n return (\n
\n

\n {title || defaultTitle}\n

\n
\n {meta.descriptionHast ? (\n toJsxRuntime(meta.descriptionHast, {Fragment, jsx, jsxs})\n ) : description ? (\n

{description}

\n ) : undefined}\n \n Continue reading »\n \n
\n \n
\n {meta.author ? (\n <>\n By {meta.author}\n
\n \n ) : undefined}\n Reading time: {timeLabel}\n
\n {meta.published && typeof meta.published === 'object' ? (\n
\n \n Published on{' '}\n \n \n
\n ) : undefined}\n
\n \n )\n}\n\n/**\n * @param {Readonly} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nexport function BlogGroup(properties) {\n const {\n className,\n items,\n sort = 'navSortSelf,meta.title',\n ...rest\n } = properties\n const sorted = sortItems(items, sort)\n\n return (\n <>\n {sorted.map(function (d) {\n return \n })}\n \n )\n}\n" }, { "path": "docs/_component/foot-site.jsx", "content": "import React from 'react'\nimport {config} from '../_config.js'\n\nexport function FootSite() {\n return (\n
\n
\n \n
\n \n MDX is made with ❤️ in Amsterdam, Boise, and around the 🌏\n \n
\n This site does not track you.\n
\n MIT © 2017-{new Date().getFullYear()}\n
\n
\n \n Project on GitHub\n \n
\n \n Site on GitHub\n \n
\n \n Updates as RSS feed\n \n
\n \n Sponsor on OpenCollective\n \n
\n
\n \n
\n )\n}\n" }, { "path": "docs/_component/home.jsx", "content": "/**\n * @import {ReactNode} from 'react'\n * @import {Data} from 'vfile'\n * @import {Item} from './sort.js'\n */\n\n/**\n * @typedef {Exclude} Meta\n *\n * @typedef Properties\n * Properties.\n * @property {string} name\n * Name.\n * @property {ReactNode} children\n * Children.\n * @property {Item} navigationTree\n * Navigation tree.\n * @property {Meta} meta\n * Meta.\n */\n\nimport React from 'react'\nimport {FootSite} from './foot-site.jsx'\nimport {NavigationSite, NavigationSiteSkip} from './nav-site.jsx'\n\n/**\n * @param {Readonly} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nexport function Home(properties) {\n const {children, meta, name, navigationTree} = properties\n\n return (\n
\n \n
\n {meta.schemaOrg ? (\n \n ) : undefined}\n
\n
{children}
\n
\n \n
\n \n
\n )\n}\n" }, { "path": "docs/_component/icon/github.jsx", "content": "import React from 'react'\n\nexport function GitHub() {\n return (\n \n GitHub\n \n \n )\n}\n" }, { "path": "docs/_component/icon/mdx.jsx", "content": "import React from 'react'\n\nexport function Mdx() {\n return (\n \n MDX\n \n \n \n \n \n \n \n \n \n \n )\n}\n" }, { "path": "docs/_component/icon/open-collective.jsx", "content": "import React from 'react'\n\nexport function OpenCollective() {\n return (\n \n OpenCollective\n \n \n \n )\n}\n" }, { "path": "docs/_component/layout.jsx", "content": "/**\n * @import {ReactNode} from 'react'\n * @import {Data} from 'vfile'\n * @import {Item} from './sort.js'\n */\n\n/**\n * @typedef Properties\n * Properties.\n * @property {string} name\n * Name.\n * @property {Readonly} ghUrl\n * GitHub URL.\n * @property {Readonly | undefined} [meta]\n * Meta.\n * @property {Readonly} navigationTree\n * Navigation tree.\n * @property {ReactNode} children\n * Children.\n */\n\nimport React from 'react'\nimport {FootSite} from './foot-site.jsx'\nimport {NavigationSite, NavigationSiteSkip} from './nav-site.jsx'\nimport {sortItems} from './sort.js'\n\nconst dateTimeFormat = new Intl.DateTimeFormat('en', {dateStyle: 'long'})\n\n/**\n * @param {Readonly} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nexport function Layout(properties) {\n const {ghUrl, name, navigationTree} = properties\n const [self, parent] = findSelfAndParent(navigationTree) || []\n const navigationSortItems = parent\n ? parent.data.navigationSortItems\n : undefined\n const siblings = parent\n ? sortItems(\n parent.children,\n typeof navigationSortItems === 'string'\n ? navigationSortItems\n : undefined\n )\n : []\n const meta = (self ? self.data.meta : properties.meta) || {}\n const index = self ? siblings.indexOf(self) : -1\n const previous = index === -1 ? undefined : siblings[index - 1]\n const next = index === -1 ? undefined : siblings[index + 1]\n const metaAuthors = meta.authors || []\n const metaTime = (\n self\n ? accumulateReadingTime(self)\n : meta.readingTime\n ? Array.isArray(meta.readingTime)\n ? meta.readingTime\n : [meta.readingTime, meta.readingTime]\n : []\n ).map(function (d) {\n return d > 15 ? Math.round(d / 5) * 5 : Math.ceil(d)\n })\n /** @type {string | undefined} */\n let timeLabel\n\n if (metaTime.length > 1 && metaTime[0] !== metaTime[1]) {\n timeLabel = metaTime[0] + '-' + metaTime[1] + ' minutes'\n } else if (metaTime[0]) {\n timeLabel = metaTime[0] + ' minute' + (metaTime[0] > 1 ? 's' : '')\n }\n\n const up =\n parent && self && parent !== navigationTree ? (\n \n ) : undefined\n\n const back = previous ? (\n
\n Previous:\n
\n \n {entryToTitle(previous)}\n \n
\n ) : undefined\n\n const forward = next ? (\n \n ) : undefined\n\n const edit = (\n
\n Found a typo? Other suggestions?\n
\n Edit this page on GitHub\n
\n )\n\n const published =\n meta.published && typeof meta.published === 'object' ? (\n <>\n Published on{' '}\n \n \n ) : undefined\n\n const modified =\n meta.modified && typeof meta.modified === 'object' ? (\n <>\n Modified on{' '}\n \n \n ) : undefined\n\n const date =\n published || modified ? (\n
\n {published}\n {published && modified ?
: undefined}\n {modified}\n
\n ) : undefined\n\n const readingTime = timeLabel ? <>{timeLabel} read : undefined\n\n const creditsList = metaAuthors.map(function (d, i) {\n const href = d.github\n ? 'https://github.com/' + d.github\n : d.url || undefined\n return (\n \n {i ? ', ' : ''}\n {href ? {d.name} : d.name}\n \n )\n })\n\n const credits = creditsList.length > 0 ? <>By {creditsList} : undefined\n\n const info =\n readingTime || credits ? (\n <>\n {readingTime}\n {readingTime && credits ?
: undefined}\n {credits}\n \n ) : undefined\n\n const header =\n up || info ? (\n
\n {up ?
{up}
: undefined}\n {info ?
{info}
: undefined}\n
\n ) : undefined\n\n const tail =\n edit || date ? (\n
\n {edit ?
{edit}
: undefined}\n {date ?
{date}
: undefined}\n
\n ) : undefined\n\n const footer =\n back || forward ? (\n
\n {back ?
{back}
: undefined}\n {forward ?
{forward}
: undefined}\n
\n ) : undefined\n\n return (\n
\n \n
\n
\n {header ? (\n
\n
{header}
\n
\n ) : undefined}\n
{properties.children}
\n {footer || tail ? (\n
\n
\n {footer}\n {tail}\n
\n
\n ) : undefined}\n
\n \n
\n \n
\n )\n\n /**\n * @param {Item} item\n * Item.\n * @param {Item | undefined} [parent]\n * Parent.\n * @returns {[self: Item, parent: Item | undefined] | undefined}\n * Self and parent.\n */\n function findSelfAndParent(item, parent) {\n if (item.name === name) return [item, parent]\n\n let index = -1\n\n while (++index < item.children.length) {\n const result = findSelfAndParent(item.children[index], item)\n\n if (result) return result\n }\n }\n}\n\n/**\n * @param {Item} d\n * Item.\n * @returns {string | undefined}\n * Title.\n */\nfunction entryToTitle(d) {\n return d.data.matter?.title || d.data.meta?.title || undefined\n}\n\n/**\n * @param {Item} d\n * Item.\n * @returns {[number, number] | [number] | []}\n * Reading time.\n */\nfunction accumulateReadingTime(d) {\n const time = (d.data.meta || {}).readingTime\n /** @type {[number, number] | [number] | []} */\n const total = time ? (Array.isArray(time) ? time : [time, time]) : []\n\n let index = -1\n while (++index < d.children.length) {\n const childTime = accumulateReadingTime(d.children[index])\n if (childTime[0]) total[0] = (total[0] || 0) + childTime[0]\n if (childTime[1]) total[1] = (total[1] || 0) + childTime[1]\n }\n\n return total\n}\n" }, { "path": "docs/_component/nav-site.jsx", "content": "/**\n * @import {ReactNode} from 'react'\n * @import {Item} from './sort.js'\n */\n\n/**\n * @typedef Properties\n * Properties.\n * @property {string} name\n * Name.\n * @property {Readonly} navigationTree\n * Navigation tree.\n */\n\nimport React from 'react'\nimport {config} from '../_config.js'\nimport {GitHub} from './icon/github.jsx'\nimport {Mdx} from './icon/mdx.jsx'\nimport {OpenCollective} from './icon/open-collective.jsx'\nimport {NavigationGroup} from './nav.jsx'\n\nexport function NavigationSiteSkip() {\n return (\n \n Skip to navigation\n \n )\n}\n\n/**\n * @param {Readonly} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nexport function NavigationSite(properties) {\n const {name, navigationTree} = properties\n\n return (\n \n )\n}\n" }, { "path": "docs/_component/nav.jsx", "content": "// Augment vfile data:\n/// \n\n/**\n * @import {ElementContent} from 'hast'\n * @import {ReactNode} from 'react'\n * @import {Item} from './sort.js'\n */\n\n/**\n * @typedef ItemProperties\n * Properties for `NavigationItem`.\n * @property {boolean | undefined} [includeDescription=false]\n * Whether to include the description (default: `false`).\n * @property {boolean | undefined} [includePublished=false]\n * Whether to include the published date (default: `false`).\n * @property {Readonly} item\n * Item.\n * @property {string | undefined} [name]\n * Name.\n *\n * @typedef GroupOnlyProperties\n * Properties for `NavigationGroup`;\n * Other fields are passed to `NavigationItem`.\n * @property {string | undefined} [className]\n * Class name.\n * @property {ReadonlyArray} items\n * Items.\n * @property {string | undefined} [sort]\n * Fields to sort on.\n * @property {string | undefined} [name]\n * Name.\n *\n * @typedef {Omit & GroupOnlyProperties} GroupProperties\n * Properties for `NavigationGroup`.\n */\n\nimport {apStyleTitleCase} from 'ap-style-title-case'\nimport {toJsxRuntime} from 'hast-util-to-jsx-runtime'\nimport React from 'react'\nimport {Fragment, jsx, jsxs} from 'react/jsx-runtime'\nimport {sortItems} from './sort.js'\n\nconst dateTimeFormat = new Intl.DateTimeFormat('en', {dateStyle: 'long'})\n\n/**\n * @param {Readonly} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nexport function NavigationGroup(properties) {\n const {\n className,\n items,\n sort = 'navSortSelf,meta.title',\n ...rest\n } = properties\n\n return (\n
    \n {sortItems(items, sort).map(function (d) {\n return \n })}\n
\n )\n}\n\n/**\n * @param {Readonly} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nexport function NavigationItem(properties) {\n const {\n includeDescription,\n includePublished,\n item,\n name: activeName\n } = properties\n const {children, data = {}, name} = item\n const {matter = {}, meta = {}, navExcludeGroup, navigationSortItems} = data\n const title = matter.title || meta.title\n const defaultTitle = apStyleTitleCase(\n name.replace(/\\/$/, '').split('/').pop()\n )\n /** @type {ReactNode} */\n let description\n /** @type {string | undefined} */\n let published\n\n if (includeDescription) {\n if (meta.descriptionHast) {\n // Cast because we don’t expect doctypes.\n const children = /** @type {Array} */ (\n meta.descriptionHast.children\n )\n\n description = toJsxRuntime(\n {\n type: 'element',\n tagName: 'div',\n properties: {className: ['nav-description']},\n children\n },\n {Fragment, jsx, jsxs}\n )\n } else {\n description = matter.description || meta.description || undefined\n\n description &&= (\n
\n

{description}

\n
\n )\n }\n }\n\n const pub = matter.published || meta.published\n\n if (includePublished && pub) {\n published = dateTimeFormat.format(\n typeof pub === 'string' ? new Date(pub) : pub || undefined\n )\n }\n\n return (\n
  • \n {title ? (\n \n {title}\n \n ) : (\n defaultTitle\n )}\n {published ? ' — ' + published : undefined}\n {description || undefined}\n {!navExcludeGroup && children.length > 0 ? (\n \n ) : undefined}\n
    • \n )\n}\n" }, { "path": "docs/_component/note.jsx", "content": "/**\n * @import {ReactNode} from 'react'\n */\n\n/**\n * @typedef {'important' | 'info' | 'legacy'} NoteType\n * Type.\n *\n * @typedef Properties\n * Properties for `Note`.\n * @property {NoteType} type\n * Kind.\n * @property {Readonly} children\n * Children.\n */\n\nimport React from 'react'\n\n/** @type {Set} */\nconst known = new Set(['info', 'legacy', 'important'])\n\n/**\n * @param {Readonly} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nexport function Note(properties) {\n const {children, type} = properties\n const className = ['note']\n\n if (known.has(type)) className.push(type)\n else {\n throw new Error('Unknown note type `' + type + '`')\n }\n\n return
    {children}
    \n}\n" }, { "path": "docs/_component/snowfall.jsx", "content": "/**\n * @import {ReactNode} from 'react'\n */\n\n/**\n * @typedef Properties\n * Properties.\n * @property {string} color\n * Color.\n * @property {number} year\n * Year.\n */\n\nimport React from 'react'\n\nconst data = [6, 5, 2, 4.5, 1.5, 2.5, 2, 2.5, 1.5, 2.5, 3.5, 7]\n\n/**\n * @param {Readonly} properties\n * Properties.\n * @returns {ReactNode}\n * Element.\n */\nexport function Chart(properties) {\n return (\n
    \n {data.map(function (d) {\n return (\n \n )\n })}\n
    \n )\n}\n" }, { "path": "docs/_component/sort.js", "content": "/**\n * @import {Data} from 'vfile'\n */\n\n/**\n * @typedef Item\n * Item.\n * @property {string} name\n * Name.\n * @property {Readonly} data\n * Data.\n * @property {Array} children\n * Children.\n */\n\nimport dlv from 'dlv'\n\nconst collator = new Intl.Collator('en').compare\n\n/**\n * @param {ReadonlyArray} items\n * Items.\n * @param {string | undefined} [sortString]\n * Fields to sort on (default: `'navSortSelf,meta.title'`).\n * @returns {ReadonlyArray}\n * Items.\n */\nexport function sortItems(items, sortString = 'navSortSelf,meta.title') {\n /** @type {ReadonlyArray<[string, 'asc' | 'desc']>} */\n const fields = sortString.split(',').map(function (d) {\n const [field, order = 'asc'] = d.split(':')\n\n if (order !== 'asc' && order !== 'desc') {\n throw new Error('Cannot order as `' + order + '`')\n }\n\n return [field, order]\n })\n\n return [...items].sort(function (left, right) {\n let index = -1\n\n while (++index < fields.length) {\n const [field, order] = fields[index]\n /** @type {unknown} */\n let a = dlv(left.data, field)\n /** @type {unknown} */\n let b = dlv(right.data, field)\n\n // Dates.\n if (a && typeof a === 'object' && 'valueOf' in a) a = a.valueOf()\n if (b && typeof b === 'object' && 'valueOf' in b) b = b.valueOf()\n\n const score =\n typeof a === 'string' && typeof b === 'string'\n ? collator(a, b)\n : typeof a === 'number' && typeof b === 'number'\n ? a - b\n : (a === null || a === undefined) && (b === null || b === undefined)\n ? 0\n : a === null || a === undefined\n ? 1\n : b === null || b === undefined\n ? -1\n : 0\n\n if (score) return order === 'asc' ? score : -score\n }\n\n return 0\n })\n}\n" }, { "path": "docs/_config.js", "content": "const site = new URL('https://mdxjs.com')\nconst git = new URL('../', import.meta.url)\nconst gh = new URL('https://github.com/mdx-js/mdx/')\n\nexport const config = {\n author: 'MDX contributors',\n color: '#010409',\n gh,\n ghBlob: new URL('blob/main/', gh),\n ghTree: new URL('tree/main/', gh),\n git,\n input: new URL('docs/', git),\n oc: new URL('https://opencollective.com/unified'),\n output: new URL('public/', git),\n site,\n tags: ['mdx', 'markdown', 'jsx', 'oss', 'react'],\n title: 'MDX'\n}\n\n/** @type {Record} */\nexport const redirect = {\n '/about/index.html': '/community/about/',\n '/advanced/index.html': '/guides/',\n '/advanced/api/index.html': '/packages/mdx/#api',\n '/advanced/ast/index.html': '/packages/remark-mdx/#syntax-tree',\n '/advanced/components/index.html': '/docs/using-mdx/',\n '/advanced/contributing/index.html': '/community/contribute/',\n '/advanced/custom-loader/index.html': '/guides/frontmatter/',\n '/advanced/retext-plugins/index.html': '/docs/extending-mdx/#using-plugins',\n '/advanced/plugins/index.html': '/docs/extending-mdx/',\n '/advanced/runtime/index.html': '/packages/mdx/#evaluatefile-options',\n '/advanced/specification/index.html': '/packages/remark-mdx/#syntax-tree',\n '/advanced/sync-api/index.html': '/packages/mdx/#api',\n '/advanced/transform-content/index.html': '/packages/remark-mdx/',\n '/advanced/typescript/index.html': '/docs/getting-started/#types',\n '/advanced/writing-a-plugin/index.html': '/guides/frontmatter/',\n '/contributing/index.html': '/community/contribute/',\n '/editor-plugins/index.html': '/docs/getting-started/#editor',\n '/editors/index.html': '/docs/getting-started/#editor',\n '/getting-started/create-react-app/index.html': '/docs/getting-started/#vite',\n '/getting-started/gatsby/index.html': '/docs/getting-started/#gatsby',\n '/getting-started/next/index.html': '/docs/getting-started/#nextjs',\n '/getting-started/parcel/index.html': '/docs/getting-started/#parcel',\n '/getting-started/react-static/index.html': '/docs/getting-started/#vite',\n '/getting-started/table-of-components/index.html': '/table-of-components/',\n '/getting-started/typescript/index.html': '/docs/getting-started/#types',\n '/getting-started/webpack/index.html': '/docs/getting-started/#webpack',\n '/getting-started/index.html': '/docs/getting-started/',\n '/guides/custom-loader/index.html': '/guides/frontmatter/',\n '/guides/live-code/index.html':\n '/guides/syntax-highlighting/#syntax-highlighting-with-the-meta-field',\n '/guides/markdown-in-components/index.html': '/docs/what-is-mdx/',\n '/guides/math-blocks/index.html': '/guides/math/',\n '/guides/mdx-embed/index.html': '/guides/embed/#embeds-at-run-time',\n '/guides/table-of-contents/index.html': '/docs/extending-mdx/',\n '/guides/terminal/index.html': '/docs/getting-started/#ink',\n '/guides/vue/index.html': '/docs/getting-started/#vue',\n '/guides/wrapper-customization/index.html': '/docs/using-mdx/#layout',\n '/guides/writing-a-plugin/index.html':\n '/docs/extending-mdx/#creating-plugins',\n '/mdx/index.html': '/docs/what-is-mdx/',\n '/plugins/index.html': '/docs/extending-mdx/#using-plugins',\n '/projects/index.html': '/community/projects/',\n '/support/index.html': '/community/support/',\n '/syntax/index.html': '/docs/getting-started/#syntax',\n '/vue/index.html': '/docs/getting-started/#vue'\n}\n" }, { "path": "docs/blog/conf.mdx", "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n author: [\n {github: 'johno', name: 'John Otander'}\n ],\n modified: new Date('2025-01-27'),\n published: new Date('2020-07-31')\n}\n\n\n **Note**: This is an old blog post.\n The below is kept as is for historical purposes.\n\n\n# MDXConf\n\nMDXConf is a free and online conference for the MDX community.\nWhether you’re just learning about MDX or an expert, there’ll be something for\nyou! {/* more */}\n\nAugust 24th, 2020 at 8am PDT/3pm UST
    Online • Free\n\n## Watch\n\nThe conference is now over, but you can still watch the recordings!\n\n[Watch the talks →](https://egghead.io/playlists/mdx-conf-3fc2)\n\n## About\n\nJoin us for the first MDX conference!\nWe’ll stream it directly to you, for free.\n\nMDX has grown rapidly since the [first commit][] two and a half years ago.\nWe’d like to celebrate our accomplishments so far, and talk about what lies\nahead.\nWe’ve got lots of plans.\n\nLearn how MDX increases developer productivity, improves educational\ncontent authoring, and even peek behind the curtains to see how MDX works.\n\n## Speakers\n\n### Chris Biscardi\n\n![](https://github.com/ChristopherBiscardi.png?size=200)]\n\nKeynote: The past, present, and future of MDX\n\n### Monica Powell\n\n![](https://github.com/M0nica.png?size=200)\n\nMigrating to MDX\n\n### Laurie Barth\n\n![](https://github.com/laurieontech.png?size=200)\n\nMDX v2 syntax\n\n### Cole Bemis\n\n![](https://github.com/colebemis.png?size=200)\n\nDemystifying MDX\n\n### Prince Wilson\n\n![](https://github.com/maxcell.png?size=200)\n\nPersonal site playgrounds\n\n### Kathleen McMahon\n\n![](https://github.com/resource11.png?size=200)\n\nDigital gardening with MDX magic\n\n### Rodrigo Pombo\n\n![](https://github.com/pomber.png?size=200)\n\nThe X in MDX\n\n### Jonathan Bakebwa\n\n![](https://github.com/codebender828.png?size=200)\n\nMDX and Vue/Nuxt\n\n## Sign up\n\n\n **Note**: Sign up is closed.\n\n\n## FAQ\n\n### What if I can’t make it on August 24th?\n\nWe’ll miss you, but you won’t miss out!\nAll talks will be recorded and released the day of the conference.\nYou can catch up with the talks, or rewatch them, whenever convenient.\n\n### Will the talks be transcribed?\n\nYes.\n\n### Is there a code of conduct?\n\nAbsolutely.\nWe’re dedicated to providing a harassment-free experience for everyone.\nWe will not tolerate harassment of participants in any form.\nWe’ve adopted the [Party Corgi Network’s Code of Conduct][coc].\nWe will have moderators to ensure that the code of conduct is followed.\n\n### Do you have a different question?\n\nReach out to us.\n\n[coc]: https://github.com/partycorgi/partycorgi/blob/corgi/CODE_OF_CONDUCT.md\n\n[first commit]: https://github.com/mdx-js/mdx/commit/dee47dc20b08d534132e3b966cdccf3b88c7bca5\n" }, { "path": "docs/blog/custom-pragma.mdx", "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n author: [\n {github: 'christopherbiscardi', name: 'Chris Biscardi'}\n ],\n modified: new Date('2021-11-01'),\n published: new Date('2019-03-11')\n}\n\n\n **Note**: This is an old blog post.\n The steps described in it are no longer performed by MDX.\n It now uses an JavaScript AST first rather than generating a string of JSX.\n It is also no longer required for extra glue code, that combines MDX with a\n specific framework, to be used on the client.\n See [§ How MDX works](/docs/using-mdx/#how-mdx-works)\n and [¶ Architecture](/packages/mdx/#architecture) for more info.\n The below is kept as is for historical purposes.\n\n\n# Custom pragma\n\n`MDXTag`, for those that aren’t aware, is a critical piece in the way\nMDX replaces HTML primitives like `
    ` and `
    ` with custom React\nComponents.\n[I’ve previously\nwritten](https://www.christopherbiscardi.com/post/codeblocks-mdx-and-mdx-utils)\nabout the way `MDXTag` works when trying to replace the `
    ` tag\nwith a custom code component.\n[mdx-utils](https://github.com/ChristopherBiscardi/gatsby-mdx/blob/00769a1b72455f40843cd2f09ee34fd63b009fb2/packages/mdx-utils/index.js)\ncontains the methodology for pulling the props around appropriately\nthrough the `MDXTag` elements that are inbetween `pre` and `code`.\n\n{/* more */}\n\n```tsx\nexports.preToCodeBlock = preProps => {\n  if (\n    // children is MDXTag\n    preProps.children &&\n    // MDXTag props\n    preProps.children.props &&\n    // if MDXTag is going to render a \n    preProps.children.props.name === 'code'\n  ) {\n    // we have a 
     situation\n    const {\n      children: codeString,\n      props: {className, ...props}\n    } = preProps.children.props\n\n    return {\n      codeString: codeString.trim(),\n      language: className && className.split('-')[1],\n      ...props\n    }\n  }\n  return undefined\n}\n```\n\nSo `MDXTag` is a real Component in the middle of all of the other MDX\nrendered elements.\nAll of the code is included here for reference.\n\n```tsx\nimport React, {Component} from 'react'\n\nimport {withMDXComponents} from './mdx-provider'\n\nconst defaults = {\n  inlineCode: 'code',\n  wrapper: 'div'\n}\n\nclass MDXTag extends Component {\n  render() {\n    const {\n      name,\n      parentName,\n      props: childProps = {},\n      children,\n      components = {},\n      Layout,\n      layoutProps\n    } = this.props\n\n    const Component =\n      components[`${parentName}.${name}`] ||\n      components[name] ||\n      defaults[name] ||\n      name\n\n    if (Layout) {\n      return (\n        \n          {children}\n        \n      )\n    }\n\n    return {children}\n  }\n}\n\nexport default withMDXComponents(MDXTag)\n```\n\n`MDXTag` is used in the hast to estree conversion,\nwhich is the final step in the MDX AST pipeline.\nEvery renderable element is wrapped in an `MDXTag`, and `MDXTag` handles\nrendering the element later.\n\n```tsx\nreturn `${children}`\n```\n\n## A concrete example\n\nThe following MDX\n\n```mdx\n# a title\n\n    and such\n\ntesting\n```\n\nturns into the following React code\n\n```tsx\nexport default ({components, ...props}) => (\n  \n    {`a title`}{' '}\n    \n      {`and such `}\n    {' '}\n    {`testing`}\n  \n)\n```\n\nresulting in the following HTML\n\n```html\n
    \n  
    a title
    \n  
    \n    and such\n  
    \n  
    testing
    \n
    \n```\n\n## createElement\n\nWith the new approach, the above MDX transforms into this new React code\n\n```tsx\nconst layoutProps = {}\nexport default function MDXContent({components, ...props}) {\n  return (\n    \n      
    {`a title`}
    \n      
    \n        {`and such\n`}\n      
    \n      
    {`testing`}
    \n    \n  )\n}\n\nMDXContent.isMDXComponent = true\n```\n\nNotice how now the React elements are plainly readable without\nwrapping `MDXTag`.\n\nNow that we’ve cleaned up the intermediary representation, we need to\nmake sure that we have the same functionality as the old `MDXTag`.\nThis is done through a custom `createElement` implementation.\nTypically when using React, we use `React.createElement` to render the elements\non screen.\nThis is even true if you’re using JSX because JSX tags such as `
    ` compile\nto `createElement` calls.\nSo this time instead of using `React.createElement` we’ll be using our own.\n\nReproduced here is our `createElement` function and the logic for how\nwe decide whether or not MDX should take over the rendering of the\n`createElement` call.\n\n```tsx\nexport default function (type, props) {\n  const args = arguments\n  const mdxType = props && props.mdxType\n\n  if (typeof type === 'string' || mdxType) {\n    const argsLength = args.length\n\n    const createElementArgArray = new Array(argsLength)\n    createElementArgArray[0] = MDXCreateElement\n\n    const newProps = {}\n    for (let key in props) {\n      if (hasOwnProperty.call(props, key)) {\n        newProps[key] = props[key]\n      }\n    }\n    newProps.originalType = type\n    newProps[TYPE_PROP_NAME] = typeof type === 'string' ? type : mdxType\n\n    createElementArgArray[1] = newProps\n\n    for (let i = 2; i < argsLength; i++) {\n      createElementArgArray[i] = args[i]\n    }\n\n    return React.createElement.apply(null, createElementArgArray)\n  }\n\n  return React.createElement.apply(null, args)\n}\n```\n\n## Vue\n\nOne really cool application of the new output format using a custom\n`createElement` is that we can now write versions of it for Vue and other\nframeworks.\nSince the pragma insertion is the responsibility of the webpack (or other\nbundlers) loader, swapping the pragma can be an option in mdx-loader as long as\nwe have a Vue `createElement` to point to.\n"
  },
  {
    "path": "docs/blog/index.mdx",
    "content": "{\n  /**\n   * @import {Item} from '../_component/sort.js'\n   */\n\n  /**\n   * @typedef Props\n   * @property {Item} navigationTree\n   */\n}\n\nimport assert from 'node:assert/strict'\nimport {BlogGroup} from '../_component/blog.jsx'\n\nexport const info = {\n  author: [{name: 'MDX Contributors'}],\n  modified: new Date('2024-07-04'),\n  published: new Date('2021-11-01')\n}\nexport const navExcludeGroup = true\nexport const navigationSortItems = 'navSortSelf,meta.published:desc'\nexport const navSortSelf = 7\n\n# Blog\n\nThe latest news about MDX.\n\n{\n  (function () {\n    const navigationTree = props.navigationTree\n    const category = navigationTree.children.find(function (item) {\n      return item.name === '/blog/'\n    })\n    assert(category)\n\n    return (\n      \n    )\n  })()\n}\n"
  },
  {
    "path": "docs/blog/shortcodes.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'johno', name: 'John Otander'}\n  ],\n  modified: new Date('2021-11-01'),\n  published: new Date('2019-05-14')\n}\n\n\n  **Note**: This is an old blog post.\n  The features described in it are currently documented at\n  [§ MDX provider](/docs/using-mdx/#mdx-provider).\n  The below is kept as is for historical purposes.\n\n\n# Shortcodes\n\nAn exciting new feature in MDX v1 is global shortcodes.\nThis allows you to expose components to all of your documents in your app or\nwebsite.\nThis is a useful feature for common components like YouTube embeds, Twitter\ncards, or anything else frequently used in your documents.\n\n{/* more */}\n\nIf you have an application wrapper for your MDX documents\nyou can add in components with the `MDXProvider`:\n\n```tsx path=\"src/App.js\"\nimport React from 'react'\nimport {MDXProvider} from '@mdx-js/react'\nimport {TomatoBox, Twitter, YouTube} from './ui'\n\nconst shortcodes = {TomatoBox, Twitter, YouTube}\n\nexport default ({children}) => (\n  {children}\n)\n```\n\nThen, any MDX document that’s wrapped in `App` has access to `YouTube`,\n`Twitter`, and `TomatoBox`.\nShortcodes are nothing more than components, so you can reference them anywhere\nin an MDX document with JSX.\n\n```mdx path=\"example.mdx\"\n# Hello world!\n\nHere’s a YouTube shortcode:\n\n\n\nHere’s a YouTube shortcode wrapped in TomatoBox:\n\n\n  \n\n```\n\nThat’s it.\n🎉 🚀\n\nHuge thanks to [Chris Biscardi](https://christopherbiscardi.com)\nfor building out most of this functionality.\n"
  },
  {
    "path": "docs/blog/v1.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'johno', name: 'John Otander'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2019-04-11')\n}\n\n\n  **Note**: This is an old blog post.\n  [ZEIT is now Vercel](https://rauchg.com/2020/vercel).\n  An “`@mdx` pragma” is no longer needed.\n  The below is kept as is for historical purposes.\n\n\n# MDX goes stable\n\nIt’s been a year and a half since the first MDX commit and a year since MDX was\nfirst announced at ZEIT Day.\nMDX is a radical paradigm shift in how to write immersive content using\ncomponents.\nIt’s an open, [authorable format](https://johno.com/authorable-format) that\nmakes it *fun* to write again.\n\n{/* more */}\n\nSince announcing MDX we’ve been working on numerous bug fixes, new features,\nbetter parsing, and integration tests.\nNow, we think it’s ready.\n**We’re happy to finally release v1!**\n\n## 🎉 What’s new?\n\nHere’s a rough breakdown on what we’ve been working on:\n\n### Parsing\n\nMDX document parsing is significantly improved.\nWe won’t get into the nitty gritty here, but we’ve seen how MDX is used in\nreal-world projects, integrated the edge cases we came across into our test\nsuite, and now handle JSX, imports, and exports much more intuitively.\nPlease open an issue if you find a case we haven’t covered!😸\n\n### remark-mdx\n\n`remark-mdx` is the syntactic extension for MDX in remark.\nIt provides the parsing functionality for MDX as a\n*[remark](https://github.com/remarkjs/remark) plugin*.\nThat sounds a bit meta.\nWhat it means is that before we had the syntax parsing bits *in* the library\n(unusable from the outside), and now it’s externalized (usable from the\noutside).\nThis is useful if you want to inspect or transform MDX documents.\nFor example, it allows tools like prettier to use the exact same parser used by\nMDX core.\nOr you could use `remark-mdx` in combination with\n[remark-lint](https://github.com/remarkjs/remark-lint) to check your MDX.\n\n### Custom pragma\n\nWith v1 we’ve moved away from using `MDXTag` and are using a custom pragma which\nwraps `React.createElement`.\nWe decided to update this approach so the JSX output is more legible,\nlighterweight, and more customizable.\n**This means MDX can be used with any React, Vue, Preact, or any other library\nwith JSX support**.\n\nSpecial thanks to [@christopherbiscardi][christopherbiscardi]\nfor implementing this feature.\n\n[Read the blog post](/blog/custom-pragma/)\n\n### 📚 Documentation\n\n**Good libraries need great docs**, so we’ve been working on adding content and\nimproving the overall documentation website experience.\n\n* Search (thanks Algolia)\n* [Guides](/guides/)\n* [Automatic deployment via ZEIT][zeit]\n* [Custom Gatsby theme][gatsbyjs]\n* Reorganization of docs for intuitiveness\n* Full page rewrites to improve clarity\n\nSpecial thanks to [@jxnblk](https://github.com/jxnblks) and\n[@wooorm][wooorm] for their help improving the docs and\nupdating the build tooling.\n\n## Breaking changes\n\nIn order to make some improvements we were forced to introduce a few breaking\nchanges.\n**These were the result of real-world production testing and feedback**.\nThe community has evolved and we’ve come up with newer, better ideas over the\nlast year.\nWe have made sure the impact is small and have written a full migration guide.\n\n* 🚨`@mdx-js/tag` is replaced by `@mdx-js/react` and an `@mdx` pragma\n  — [migration guide](/migrating/v1#pragma)\n* MDXProvider now merges component contexts when nested\n  — [migration guide](/migrating/v1#mdxprovider)\n* React support now requires `>= 16.8` in `@mdx-js/react`\n  — [migration guide](/migrating/v1#react)\n\n[Read the full v1 migration guide](/migrating/v1)\n\n### Deprecations\n\nWe only needed to introduce one deprecation.\nThe `mdPlugins` and `hastPlugins` options have been renamed `remarkPlugins` and\n`rehypePlugins` respectively.\nFor the time being we will issue a warning when the old options are used.\nIn v2, the old options will be removed.\n\n## 📈 Growth\n\nA major release is always a good time to take a step back and reflect on what’s\nbeen happening in terms of growth and the greater community.\nThe ecosystem surrounding MDX has already grown larger than we ever dreamed.\nWe’ve also seen projects/products/application we never even imagined.\n\n### Numbers\n\n* **Downloads**: 125,000/week, 2.4M total\n* **Stars**: 6,200\n* **Contributors**: 50\n* **Pull requests**: 281\n* **Commits**: 670\n\nThe contributor growth is one of the most important aspects here as we have\nnumerous community members that are familiar with MDX internals.\nThis allows us to continually improve the project and spread the workload\nagainst an ever growing team of contributors.\n\n[See the contributor graph](https://github.com/mdx-js/mdx/graphs/contributors?from=2017-12-17\\&to=2019-04-11\\&type=c)\n\n### Ecosystem\n\n* [Prettier](https://prettier.io)\n* [Docz](https://docz.site)\n* [MDX Deck](https://github.com/jxnblk/mdx-deck)\n* [Next.js](https://nextjs.org)\n* [Gatsby][gatsbyjs]\n* [AST Explorer](https://astexplorer.net)\n* [Vue support (alpha)](/docs/getting-started/#vue)\n* [Demoboard](https://frontarm.com/demoboard/)\n* [Editors](/docs/getting-started/#editor)\n\n## 🛣 Roadmap\n\nWith v1 released we have a roadmap in place that we’ll continue working towards\nover the next 6 months or so in addition to bug fixes and parsing issues we\nmight encounter.\n\n* MDXs: [#454](https://github.com/mdx-js/mdx/issues/454)\n* Interleaving: [#195](https://github.com/mdx-js/mdx/issues/195)\n* Global shortcodes: [#508](https://github.com/mdx-js/mdx/pull/508)\n* Stable Vue support: [#238](https://github.com/mdx-js/mdx/issues/238)\n* Blocks: MDX WYSIWYG: [blocks/blocks][blocks]\n* MDX playground inspired by AST Explorer: [#220](https://github.com/mdx-js/mdx/issues/220)\n* New splash page: [#444](https://github.com/mdx-js/mdx/issues/444)\n* Showcase page: [#414](https://github.com/mdx-js/mdx/issues/414)\n\n### Vue support\n\nSupporting Vue is an important goal for MDX and is one of the primary reasons\nwe’ve rearchitected MDX to use custom pragma.\nWe’re delighted that **we now have an alpha version for Vue working**.\nWe’d love it if anyone from the Vue community wants to give it a try and provide\nfeedback.\n\n[See the Vue example](https://github.com/mdx-js/mdx/tree/36cb41b/examples/vue)\n\n### Blocks project\n\nOne of the key missing aspects of authoring MDX documents is the editing\nexperience.\nCurrently, there isn’t an approachable way to write MDX unless you enjoy working\nin a text editor and writing raw Markdown/code.\nWe’d like to solve that and have begun work on an MDX “blocks editor” that’s a\n**content-focused WYSIWYG**.\nNot to mention, we’ll be doing all that we can to make sure the editor is as\naccessible as it can be from the beginning.\n\nWhen we have a beta ready we will be open sourcing it and announcing, so stay\ntuned.\n\n[Check out the Blocks project][blocks]\n\n## unified collective\n\nMDX is part of the unified collective, which is an open source ecosystem for\ndealing with many sources of content.\nunified projects are used all over the web, and it would never be possible\nwithout financial support from our fine sponsors.\n\n* [ZEIT][] 🥇\n* [Gatsby][gatsbyjs] 🥇\n* [Holloway](https://www.holloway.com) 🥉\n* [Backers](https://opencollective.com/unified#budget) 🏆\n* [You?](https://opencollective.com/unified)👤\n\n## 🙏 Thanks\n\nWe’d like to say thanks to all our contributors and our happy users.\nSpecial thanks to\n[@wooorm][wooorm],\n[@silvenon](https://github.com/silvenon),\n[@timneutkens](https://github.com/timneutkens),\n[@ChristopherBiscardi][christopherbiscardi],\n[@jxnblk](https://github.com/jxnblk),\n[@alexandernanberg](https://github.com/alexandernanberg),\n[@jescalan](https://github.com/jescalan),\n[@Jarred-Sumner](https://github.com/Jarred-Sumner),\n[@leimonio](https://github.com/leimonio),\n[@ticky](https://github.com/ticky),\n[@jamesknelson](https://github.com/jamesknelson),\n[@pshrmn](https://github.com/pshrmn),\n[@rauchg](https://github.com/rauchg),\n[@joelhooks](https://github.com/joelhooks),\n[@jlengstorf](https://github.com/jlengstorf),\n[@johnlindquist](https://github.com/johnlindquist),\n[@kyleamathews](https://github.com/kyleamathews),\n[@kentcdodds](https://github.com/kentcdodds),\n[@wesbos](https://github.com/wesbos),\n[@rosew](https://github.com/rosew),\n[@pedronauck](https://github.com/pedronauck),\n[@tayiorbeii](https://github.com/tayiorbeii),\n[@nickbender](https://github.com/nickbender),\n[@ntaylor89](https://github.com/ntaylor89),\n[@mxstbr](https://github.com/mxstbr),\n[@manovotny](https://github.com/manovotny),\n[@xyc](https://github.com/xyc),\n[@filoxo](https://github.com/filoxo),\n[@millette](https://github.com/millette),\n[@hugmanrique](https://github.com/hugmanrique),\n[@johnsherrard](https://github.com/johnsherrard),\n[@sw-yx](https://github.com/sw-yx),\nand anyone we may have forgotten.\n\n[blocks]: https://github.com/blocks/blocks\n\n[christopherbiscardi]: https://github.com/christopherbiscardi\n\n[gatsbyjs]: https://gatsbyjs.org\n\n[wooorm]: https://github.com/wooorm\n\n[zeit]: https://zeit.co\n"
  },
  {
    "path": "docs/blog/v2.mdx",
    "content": "import {Note} from '../_component/note.jsx'\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2022-02-01')\n}\n\n\n  **Note**: This is an old blog post.\n  The below is kept as is for historical purposes.\n\n\n\n  **Note**: Info on how to migrate is available in our\n  [Version 2 migration guide][migrating].\n\n\n# MDX 2\n\nVersion 2 of MDX was released after years of hard work, and has many\nimprovements.\nHere are the highlights:\n\n{/* more */}\n\n
    \n  * 📝 **Improved syntax** makes it easier to use markdown in JSX\n  * 🧑‍💻 **JavaScript expressions** turn `{2 * Math.PI}` into {2 * Math.PI}\n  * 🔌 New **esbuild**, **Rollup**, and **Node.js** integrations\n  * ⚛️ **Any JSX runtime**: React, Preact, Vue, Emotion, you name it, they’re\n    all supported\n  * 🌳 **Improved AST** exposes more info in greater detail\n  * 🏃‍♀️ Compiles at least **25% faster**\n  * 🚴 Generated code runs twice as fast (**100% faster**)\n  * 🚄 Bundle size of `@mdx-js/mdx` is more than three times as small\n    (**250% smaller**)\n  * 🧵 …and much, so much more\n
    \n\nIt’s been 4 years since this project was announced.\n2½ since we released our stable version 1.\n**We’re proud to finally release v2!**\nLet’s dive in!\n\n## Contents\n\n* [Improvements to the MDX format](#improvements-to-the-mdx-format)\n* [Rollup, esbuild, and other integrations](#rollup-esbuild-and-other-integrations)\n* [Architectural improvements](#architectural-improvements)\n* [TypeScript](#typescript)\n* [Docs & site](#docs--site)\n* [Breaking changes](#breaking-changes)\n* [Thanks](#thanks)\n\n## Improvements to the MDX format\n\nWe’ve spent a lot of time thinking and trying out different ways to improve the\nformat.\nOriginally, the format was very close to how markdown, and HTML in markdown,\nworks.\nWe found that the old behavior often yielded unexpected results.\nIn version 2, we shift the format a little bit closer to how JS(X) works.\n\nTake for example this MDX file:\n\n```mdx chrome=no\n
    *hi*?
    \n\n
    \n  # hi?\n
    \n\n
    \n  
    \n\n    # hi?\n\n  
    \n
    \n```\n\n
    \n  
    \n    In version 1, that was equivalent to the following JSX:\n\n    ```tsx chrome=no\n    <>\n      
    *hi*?
    \n      
    \n        # hi?\n      
    \n      
    \n        
    \n          
    # hi?
    \n        
    \n      
    \n    \n    ```\n  
    \n\n  
    \n    In version 2, it’s equivalent to the following JSX:\n\n    ```tsx chrome=no\n    <>\n      
    hi?
    \n      
    \n        
    hi?
    \n      
    \n      
    \n        
    \n          
    hi?
    \n        
    \n      
    \n    \n    ```\n  
    \n
    \n\nWe believe it’s more intuitive that markdown “inlines” such as emphasis can form\nbetween tags on the same line (first `
    `), “blocks” such as headings can\nform if they’re on their own line (second `
    `), and indentation is allowed\nrather than forming code (third `
    `).\n\nWe also added support for JavaScript expressions, take for example:\n\n
    \n  
    \n    ```mdx path=\"expressions.mdx\"\n    export const authors = [\n      {name: 'Jane', email: 'hi@jane.com'},\n      {name: 'John', github: '@johno'}\n    ]\n    export const published = new Date('2022-02-01')\n\n    Written by: {new Intl.ListFormat('en').format(authors.map(d => d.name))}.\n\n    Published on: {new Intl.DateTimeFormat('en', {dateStyle: 'long'}).format(published)}.\n    ```\n  
    \n\n  
    \n    ```tsx path=\"equivalent.jsx\"\n    <>\n      
    Written by: Jane and John.
    \n      
    Published on: February 1, 2022.
    \n    \n    ```\n  
    \n
    \n\nAs the format moves a little further from markdown towards JSX, we’ve added\nsupport for loading “normal” markdown without our syntax extensions.\nIf you’re using our bundler integration `@mdx-js/loader` (or `@mdx-js/rollup`,\n`@mdx-js/esbuild`, or `@mdx-js/node-loader`, see next section), then that’ll\njust work: import `readme.mdx` and it’s seen as the MDX format, import\n`readme.md` and it’s seen as markdown, based on their extensions.\n\nThe MDX format is described in [§ What is MDX?][what]\n\n## Rollup, esbuild, and other integrations\n\nWhen we started out, Babel, webpack, and React were ubiquitous in the JavaScript\necosystem and we built MDX on them.\nFor version 2, we worked hard to make them optional.\nThey’re no longer required and MDX can more easily be used with other tools.\n\nOn the bundler side, we’ve added new integrations: `@mdx-js/esbuild` for\nesbuild (an extremely fast bundler) and `@mdx-js/rollup` for Rollup (a bundler\nthat’s also used in Vite and WMR).\nYou can even import MDX files directly in Node.js with our new\n`@mdx-js/node-loader`.\n\nOn the runtime side, we can now compile JSX away to normal JavaScript and\nno longer need framework-specific code to glue them together with MDX.\nNow any JSX runtime, whether [classic or automatic][jsx-runtime], is supported.\nThis means MDX can be used with React, Preact, Vue, Emotion, Theme UI, Ink, you\nname it, plus anything that’s yet to be invented!\n\nSee [§ Getting started][getting-started] for a quick start but also in-depth\ninfo on how to integrate MDX with many different tools.\n\n## Architectural improvements\n\nTo make the syntax of the MDX format better and to allow new integrations and\narbitrary JSX runtimes, we’ve rewritten almost everything.\nPart of that effort was [micromark][], which is another story, but it means\nwe’re fully CommonMark (and optionally GFM) compliant, while also understanding\nmore about MDX files.\n\nNow we can throw an early error when there’s a typo and point to exactly where\nit happened, instead of a later bundler like webpack complaining about an error\nin an intermediate, unrecognizable, and broken string of JavaScript.\nIt also means that we have a new AST which describes the MDX syntax in more\ndetail — we even expose the embedded JavaScript.\nThis detailed AST allows plugins to enhance MDX in powerful new ways.\nIt also helped solve edge cases where MDX would previously crash.\nAnd it let us drop Babel.\n\nThis new architecture results in **25% faster** compilation, generated code\nthat runs twice as fast (**100% faster**), and that the bundle size of\n`@mdx-js/mdx` is more than three times as small (**250% smaller**).\n\nSee [¶ Architecture in `@mdx-js/mdx`][architecture] for more on how our compiler\nworks.\nSee [§ Extending MDX][extending] for several plugins that use the new tree to\nenhance MDX, how to use them and other plugins, and how to create plugins.\n\n## TypeScript\n\nAll [`@mdx-js/*` packages][packages] are now fully typed with [TypeScript][]\nthrough JSDoc comments.\nThat means our APIs are exposed as TypeScript types but also that our projects\nare type safe internally.\n\nWe’ve published [`@types/mdx`][types-mdx], a types-only package that can be used\nwith any (community) integration.\nYou can use it, if you’re importing MDX files, to type those imported\ncomponents.\n\nSee [¶ TypeScript in § Getting started][ts] for more on how to use configure\nTypeScript.\n\n## Docs & site\n\nMDX is used and liked a lot.\nBefore version 1 we had amassed a total of **2.5m downloads**.\nNow we hit that number every week.\nOur core compiler `@mdx-js/mdx` is used in **61k projects**.\nOur GitHub repo has **11.6k stars**.\n\nMany people help, often with docs.\n85 contributors committed to our repo since version 1.\nWe’re grateful for these contributions and all those individual insights,\nbut over the years it did result in some inconsistencies and duplicated content.\n\nFor version 2, we rewrote our docs from beginning to end to tell a consistent\nstory for new users, folks that do complex AST and compiler stuff, and\nanyone in between.\n\nWe also made a new website.\nIt’s built on MDX of course, [unified][] itself, and [React Server Components\n(RSC)][rsc].\nWhile we dogfood the former two as they’re projects we maintain, and the\nlatter is extremely experimental, we think compiling things ahead of time and\nbetting on hybrid models, compared to completely server-side sites or completely\nclient-side apps, is the smart choice for us and the web’s future.\n\nOur new site is heavily optimized and fast, gorgeous (subjective but hey), has\nrich metadata, and scores very well in performance and accessibility review\ntools such as Lighthouse and axe.\n\nSee [§ Contribute][contribute] for more on how to help.\n\n## Breaking changes\n\nWhen you’re ready to migrate, please see the\n[Version 2 migration guide][migrating].\n\n## Thanks\n\nWe’d like to say thanks to all our contributors and our happy users.\nSpecial thanks to\nJohn Otander ([**@johno**](https://github.com/johno)),\nChristian Murphy ([**@ChristianMurphy**](https://github.com/ChristianMurphy)),\nJounQin ([**@JounQin**](https://github.com/JounQin)),\nJack Bates ([**@jablko**](https://github.com/jablko)),\nSam Chen ([**@chenxsan**](https://github.com/chenxsan)),\nSam Robbins ([**@samrobbins85**](https://github.com/samrobbins85)),\nRemco Haszing ([**@remcohaszing**](https://github.com/remcohaszing)),\nLB ([**@laurieontech**](https://github.com/laurieontech)),\nGabriel Kirkley ([**@gdgkirkley**](https://github.com/gdgkirkley)>),\nHung-I Wang ([**@Gowee**](https://github.com/Gowee)),\nIlham Wahabi ([**@iwgx**](https://github.com/iwgx)),\nKaito Sugimoto ([**@HelloRusk**](https://github.com/HelloRusk)),\nKarl Horky ([**@karlhorky**](https://github.com/karlhorky)),\nKatie Hughes ([**@glitteringkatie**](https://github.com/glitteringkatie)),\nLachlan Campbell ([**@lachlanjc**](https://github.com/lachlanjc)),\nMarcy Sutton ([**@marcysutton**](https://github.com/marcysutton)),\nMarius Gundersen ([**@mariusGundersen**](https://github.com/mariusGundersen)),\nMarius-Remus Mate,\nMark Skelton ([**@mskelton**](https://github.com/mskelton)),\nMartin V ([**@ndresx**](https://github.com/ndresx)),\nMatija Marohnić ([**@silvenon**](https://github.com/silvenon)),\nMichael Oliver ([**@michaeloliverx**](https://github.com/michaeloliverx)),\nMichaël De Boey ([**@MichaelDeBoey**](https://github.com/MichaelDeBoey)),\nMuescha ([**@muescha**](https://github.com/muescha)),\nNorviah ([**@Norviah**](https://github.com/Norviah)),\nPaul Scanlon ([**@PaulieScanlon**](https://github.com/PaulieScanlon)),\nPeter Mouland ([**@peter-mouland**](https://github.com/peter-mouland)),\nPrince Wilson ([**@maxcell**](https://github.com/maxcell)),\nRafael Almeida ([**@rafaelalmeidatk**](https://github.com/rafaelalmeidatk)),\nRodrez ([**@rodrez**](https://github.com/rodrez)),\nRongjian Zhang ([**@pd4d10**](https://github.com/pd4d10)),\nTaeheon Kim ([**@lonyele**](https://github.com/lonyele)),\nTom Parker-Shemilt ([**@palfrey**](https://github.com/palfrey)),\nTry Ajitiono ([**@imballinst**](https://github.com/imballinst)),\nYamagishi Kazutoshi ([**@ykzts**](https://github.com/ykzts)),\nYoav Kadosh ([**@ykadosh**](https://github.com/ykadosh)),\nYordis Prieto ([**@Yordis**](https://github.com/Yordis)),\nAdrian Foong ([**@adrfoong**](https://github.com/adrfoong)),\nDan Abramov ([**@gaearon**](https://github.com/gaearon)),\n[**@ihupoo**](https://github.com/ihupoo),\n[**@nikhog**](https://github.com/nikhog),\n[**@redallen**](https://github.com/redallen),\nAkshay Kadam ([**@deadcoder0904**](https://github.com/deadcoder0904)),\nя котик пур-пур ([**@mvasilkov**](https://github.com/mvasilkov)),\nAnders D. Johnson ([**@AndersDJohnson**](https://github.com/AndersDJohnson)),\nAndrew Aylett ([**@andrewaylett**](https://github.com/andrewaylett)),\nAnkeet Maini ([**@ankeetmaini**](https://github.com/ankeetmaini)),\nBiswas Nandamuri ([**@Biswas-N**](https://github.com/Biswas-N)),\nBret ([**@bcomnes**](https://github.com/bcomnes)),\nChris Chinchilla ([**@ChrisChinchilla**](https://github.com/ChrisChinchilla)),\nChristopher Biscardi ([**@ChristopherBiscardi**](https://github.com/ChristopherBiscardi)),\nDan Overton ([**@dan-overton**](https://github.com/dan-overton)),\nDomitrius ([**@domitriusclark**](https://github.com/domitriusclark)),\nDovi Winberger ([**@dowi**](https://github.com/dowi)),\nEmmie Päivärinta ([**@emmiep**](https://github.com/emmiep)),\nEugene Ghanizadeh ([**@loreanvictor**](https://github.com/loreanvictor)),\nand anyone we may have forgotten.\n\n[architecture]: /packages/mdx/#architecture\n\n[contribute]: /community/contribute/\n\n[extending]: /docs/extending-mdx/\n\n[getting-started]: /docs/getting-started/\n\n[jsx-runtime]: https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html\n\n[micromark]: https://github.com/micromark/micromark\n\n[migrating]: /migrating/v2/\n\n[packages]: /packages/\n\n[rsc]: https://reactjs.org/blog/2020/12/21/data-fetching-with-react-server-components.html\n\n[ts]: /docs/getting-started/#types\n\n[types-mdx]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/mdx\n\n[typescript]: https://www.typescriptlang.org\n\n[unified]: https://unifiedjs.com\n\n[what]: /docs/what-is-mdx/\n"
  },
  {
    "path": "docs/blog/v3.mdx",
    "content": "import {Note} from '../_component/note.jsx'\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2023-10-24')\n}\n\n\n  **Note**: Info on how to migrate is available in our\n  [Version 3 migration guide][migrating].\n\n\n# MDX 3\n\nVersion 3 already!\nThis major version contains a couple small changes.\nFor most folks, updating Node.js and plugins is all that’s needed!\n\n{/* more */}\n\n## Contents\n\n* [Breaking changes](#breaking-changes)\n* [Improvements to the MDX format](#improvements-to-the-mdx-format)\n  * [Adjacent block JSX and expressions in MDX](#adjacent-block-jsx-and-expressions-in-mdx)\n  * [Await in MDX](#await-in-mdx)\n  * [ES2024 in MDX](#es2024-in-mdx)\n* [Miscellaneous](#miscellaneous)\n* [Thanks](#thanks)\n\n## Breaking changes\n\nThe main breaking change is that Node.js 16 is now the minimum supported\nversion.\n\nAcross the ecosystem there were several small internal breaking changes.\nEverything’s released already.\nYou can update all plugins now.\nIf you ran into problems before, it should work now.\n\nWe also removed some infrequently used deprecated APIs.\nYou’re likely fine but gloss over the [v3 migration guide][migrating] if you\nget errors.\n\nImportant to note when you use your lesser-known but powerful `evaluate`, `run`,\nor `outputFormat: 'function-body'` APIs, please pass the `baseUrl` option.\nThat makes sure `import.meta.url`, `import`, and `export` work.\nYou’ll get a runtime error when those features are used otherwise.\n\n## Improvements to the MDX format\n\nThere’s also a few small improvements to the MDX format, some of which\ntechnically breaking.\n\n### Adjacent block JSX and expressions in MDX\n\nWe now accept block expressions right next to block JSX tags:\n\n```mdx chrome=no\n\n```\n\nPreviously, there was a syntax error, and you had to add a newline between the\nangle brackets and the braces.\n\n### Await in MDX\n\nWe now accept `await` syntax:\n\n```mdx\n{await Promise.resolve(42)}\n```\n\nMost frameworks don’t support promises.\nWhether this works depends on that.\n\nPreviously, there was a runtime error that `await` was used in a context where\nit wasn’t allowed.\n\n### ES2024 in MDX\n\nYou can now use modern JavaScript syntax in MDX.\nAcorn, used internally, is now instructed to use ES2024.\n\n## Miscellaneous\n\nI refactored all the docs.\nUpdating every use example where needed.\nI also wrote a guide on how to inject components from anywhere:\n[§ Injecting components][injecting-components].\n\nThe site is a lot faster.\nThere’s a nice improved playground too: [try it out! »][playground].\nWe also have proper syntax highlighting here, thanks to\n[`wooorm/markdown-tm-language`][markdown-tm-language]\nand [`wooorm/starry-night`][starry-night].\n\nThe generated JS code is a little cleaner (the JSX pragma comment is removed\nand objects are sorted where needed), it also uses spreads instead of\n`Object.assign`, there’s a `'use strict'` added when needed, and the\n`MDXContent` is exported immediately.\n\n## Thanks\n\nWe’d like to say thanks to all our contributors and our happy users.\nSpecial thanks to\n北雁云依 ([**@BeiyanYunyi**](https://github.com/BeiyanYunyi)),\nChristian Murphy ([**@ChristianMurphy**](https://github.com/ChristianMurphy)),\nJokcyLou ([**@Jokcy**](https://github.com/Jokcy)),\nMaël Nison ([**@arcanis**](https://github.com/arcanis)),\nAndreas Deininger ([**@deining**](https://github.com/deining)),\nRemco Haszing ([**@remcohaszing**](https://github.com/remcohaszing)),\nSébastien Lorber ([**@slorber**](https://github.com/slorber)),\nVíctor Fernández ([**@victor23k**](https://github.com/victor23k)),\nTitus Wormer ([**@wooorm**](https://github.com/wooorm)),\nand anyone we may have forgotten.\n\n[injecting-components]: /guides/injecting-components/\n\n[markdown-tm-language]: https://github.com/wooorm/markdown-tm-language\n\n[migrating]: /migrating/v3/\n\n[playground]: /playground/\n\n[starry-night]: https://github.com/wooorm/starry-night\n"
  },
  {
    "path": "docs/community/about.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2021-10-06')\n}\nexport const navSortSelf = 4\n\n# About\n\nThis article explains in short how MDX came to be and why it exists.\nIt also gives thanks to the people who’ve helped make it and inspired it.\n\n{/* more */}\n\n## What is MDX?\n\nMDX is the combination of markdown with JSX.\nSee [§ What is MDX?][what] for more info.\n\n## Why MDX?\n\nMarkdown does not have a syntax for custom components.\nMDX solves this.\n\nThere are many languages objectively better than markdown, however, markdown is\ngreat because:\n\n* It looks like what it means and is relatively easy to read\n* Although images are [confusing][], most stuff is relatively simple to write\n* It’s loose and ambiguous: it may not work but you won’t get an error (great\n  for someone posting a comment to a forum if they forgot an asterisk)\n\nMarkdown *does* have a way to extend it, HTML, but that has drawbacks:\n\n* HTML in markdown is naïve, how it’s parsed sometimes doesn’t make sense\n* HTML is unsafe by default, so it’s sometimes (partially) unsupported\n* HTML and markdown don’t mix well, resulting in confusing rules such as\n  blank lines or `markdown=\"1\"` attributes\n* HTML is coupled with browsers, markdown is useful for other things too\n\nThe frontend world has an alternative to HTML: JSX.\nJSX is great, amongst other things, because:\n\n* It has a relatively familiar syntax (like XML)\n* It’s agnostic to semantics and intended for compilers (can have any\n  domain-specific meaning)\n* It’s strict and unambiguous (great if an author forgot a slash somewhere, as\n  they’ll get an error early, instead of a book going to print with broken\n  stuff in it)\n\n## Who governs MDX?\n\nThe project is governed by the\n[unified collective][governance].\n\n## Who created MDX?\n\nThe idea of combining [markdown][commonmark], [JavaScript][], and [JSX][] was a\ncollaborative effort by\n[Guillermo Rauch][mdx-rauchg] (**[@rauchg][rauchg]**),\n[James K. Nelson][mdx-jamesknelson] (**[@jamesknelson][jamesknelson]**),\n[John Otander][mdx-johno] (**[@johno][johno]**),\nTim Neutkens (**[@timneutkens][timneutkens]**),\nBrent Jackson (**[@jxnblk][jxnblk]**),\nJessica Stokes (**[@ticky][ticky]**), and more.\n\nWhile everyone above was key to MDX, we want to stress the involvement of\n[John Otander][mdx-johno] (**[@johno][johno]**).\nJohn wrote most of the code for the first alpha and later stable version 1 of\nthis project!\n\n## Who designed the logo?\n\n[Logo designs][design] were created by [Evil Rabbit][] of [Vercel][].\n\n## What projects inspired MDX?\n\nThe following projects, languages, and articles helped shape MDX either in\nimplementation or inspiration.\n\nThe [markdown][] and [JSX][] languages inspired MDX.\nMarkdown was [created by John Gruber][markdown] (**[@gruber][gruber]**).\n[CommonMark][], the most popular markdown variant, by John McFarlane\n(**[@jgm][jgm]**) et al.\nJSX was created by Sebastian Markbåge (**[@sebmarkbage][sebmarkbage]**) et\nal. at Facebook, Inc.\n\nThe `@mdx-js/*` projects currently make heavy use of [unified][] (specifically\n[micromark][], [remark][] and [rehype][]) and [Acorn][].\nunified, remark, rehype, and related tools were created by Titus Wormer\n(**[@wooorm][wooorm]**) et al.\nAcorn by Marijn Haverbeke (**[@marijnh][marijnh]**) et al.\n\nThe following projects inspired `@mdx-js/*` originally:\n\n{/* Note: please keep the original project names intact: */}\n\n* [`jamesknelson/mdxc`](https://github.com/frontarm/mdx-util)\n* [`ticky/markdown-component-loader`](https://github.com/ticky/markdown-component-loader)\n* [`threepointone/markdown-in-js`](https://github.com/threepointone/markdown-in-js)\n* [`fazouane-marouane/remark-jsx`](https://github.com/remarkjs/remark-jsx)\n* [`mapbox/remark-react`](https://github.com/remarkjs/remark-react)\n* [`rx-ts/eslint-mdx`](https://github.com/mdx-js/eslint-mdx)\n\nThe following articles inspired `@mdx-js/*` originally:\n\n* [IA Markdown Content Blocks](https://github.com/iainc/Markdown-Content-Blocks)\n* [Idyll: Markup language for interactive documents](https://idyll-lang.org)\n\n[acorn]: https://github.com/acornjs/acorn\n\n[commonmark]: https://spec.commonmark.org/current/\n\n[confusing]: https://twitter.com/gruber/status/1246489863932821512\n\n[design]: https://github.com/mdx-js/design\n\n[evil rabbit]: https://evilrabb.it\n\n[governance]: https://github.com/unifiedjs/collective\n\n[gruber]: https://github.com/gruber\n\n[jamesknelson]: https://github.com/jamesknelson\n\n[javascript]: https://tc39.es/ecma262/\n\n[jgm]: https://github.com/jgm\n\n[johno]: https://github.com/johno\n\n[jsx]: https://facebook.github.io/jsx/\n\n[jxnblk]: https://github.com/jxnblk\n\n[marijnh]: https://github.com/marijnh\n\n[markdown]: https://daringfireball.net/2004/03/introducing_markdown\n\n[mdx-jamesknelson]: https://github.com/frontarm/mdx-util/tree/0f5f6d62bac4b83edc4bc3890dde3011079fa318\n\n[mdx-johno]: https://github.com/mdx-js/mdx/tree/a96ede2c104084ae21efa8bd95319011e558ec9d\n\n[mdx-rauchg]: https://spectrum.chat/frontend/general/mdx-proposal~1021be59-2738-4511-aceb-c66921050b9a\n\n[micromark]: https://github.com/micromark/micromark\n\n[rauchg]: https://github.com/rauchg\n\n[rehype]: https://github.com/rehypejs/rehype\n\n[remark]: https://github.com/remarkjs/remark\n\n[sebmarkbage]: https://github.com/sebmarkbage\n\n[ticky]: https://github.com/ticky\n\n[timneutkens]: https://github.com/timneutkens\n\n[unified]: https://unifiedjs.com\n\n[vercel]: https://vercel.com\n\n[what]: /docs/what-is-mdx/\n\n[wooorm]: https://github.com/wooorm\n"
  },
  {
    "path": "docs/community/contribute.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2018-11-04')\n}\nexport const navSortSelf = 2\n\n# Contribute\n\nThis article explains how to contribute to MDX.\nPlease read through the following guidelines.\n\n{/* more */}\n\n\n  **Important**: before participating in our community, please read our\n  [code of conduct][coc].\n  By interacting with this repository, organization, or community you agree to\n  abide by its terms.\n\n\n## Contributions\n\nThere’s several ways to contribute, not just by writing code.\nIf you have questions, see [§ Support][support].\nIf you can provide financial support, see [§ Sponsor][sponsor].\n\n### Improve docs\n\nAs a user you’re perfect for helping us improve our docs.\nTypo corrections, error fixes, better explanations, new examples, etcetera.\nAll MDX docs live in `docs/`.\n\nYou can run the docs locally, see [¶ Site][site] below.\n\n### Improve issues\n\nSome issues lack information, aren’t reproducible, or are just incorrect.\nYou can help by trying to make them easier to resolve.\nExisting issues might benefit from your unique experience or opinions.\n\n### Write code\n\nCode contributions are very welcome.\nIt’s probably a good idea to first post a question or open an issue to report a\nbug or suggest a new feature before creating a pull request.\n\n## Submitting an issue\n\n* The issue tracker is for issues.\n  Use discussions for support\n* Search the issue tracker (including closed issues) before opening a new\n  issue\n* Ensure you’re using the latest version of our packages\n* Use a clear and descriptive title\n* Include as much information as possible: steps to reproduce the issue,\n  error message, version, operating system, etcetera\n* The more time you put into an issue, the better we will be able to help you\n* The best issue report is a failing test proving it\n\n## Submitting a pull request\n\n* See [¶ Project][project] below for info on how the project is structured,\n  how to test, and how to build the site\n* Non-trivial changes are often best discussed in an issue first, to prevent\n  you from doing unnecessary work\n* For ambitious tasks, you should try to get your work in front of the\n  community for feedback as soon as possible\n* New features should be accompanied by tests and documentation\n* Don’t include unrelated changes\n* Test before submitting code by running `npm test`\n* Write a convincing description of why we should land your pull request:\n  it’s your job to convince us\n\n## Project\n\n### Structure\n\nMDX is a monorepo.\nAll packages are in `packages/`.\nDocumentation is in `docs/`.\n\n### Tests\n\nTo run the tests, first do `npm install`, then do `npm test`.\nThis ensures everything is okay, from code style to unit tests to types.\n\n### Site\n\nTo build the site, first do `npm install`, then do `npm run docs`.\nThis produces the website in `public/`.\n\n### Release\n\nTo release a new version, do:\n\n1. update `version`s of packages with a patch, minor, or major (make sure to\n   update dependency ranges on monorepo packages when needed):\n   ```sh\n   npm version minor --workspaces --no-git-tag-version\n   ```\n2. commit and tag using the version (without `v`) as the message:\n   ```sh\n   git commit --all --message 1.2.3 && git tag 1.2.3 && git push && git push --tags\n   ```\n3. release to the npm registry:\n   ```sh\n   npm publish --workspaces\n   ```\n4. add a changelog entry for the release on GitHub:\n   ```sh\n   open https://github.com/mdx-js/mdx/releases\n   ```\n\n## Resources\n\n* [Good first issues in the MDX repository](https://github.com/mdx-js/mdx/labels/good%20first%20issue%20👋)\n* [How to contribute to open source](https://opensource.guide/how-to-contribute/)\n* [Making your first contribution](https://medium.com/@vadimdemedes/making-your-first-contribution-de6576ddb190)\n* [Using pull requests](https://help.github.com/articles/about-pull-requests/)\n* [GitHub help](https://help.github.com)\n\n[coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md\n\n[project]: #project\n\n[site]: #site\n\n[sponsor]: /community/sponsor/\n\n[support]: /community/support/\n"
  },
  {
    "path": "docs/community/index.mdx",
    "content": "{\n  /**\n   * @import {Item} from '../_component/sort.js'\n   */\n\n  /**\n   * @typedef Props\n   * @property {Item} navigationTree\n   */\n}\n\nimport assert from 'node:assert/strict'\nimport {NavigationGroup} from '../_component/nav.jsx'\n\nexport const info = {\n  author: [{name: 'MDX Contributors'}],\n  modified: new Date('2024-07-04'),\n  published: new Date('2021-11-01')\n}\nexport const navSortSelf = 6\n\n# Community\n\nThese pages explain how to contribute, get help, sponsor us, share your work,\nand some background information.\n\n{\n  (function () {\n    const navigationTree = props.navigationTree\n    const category = navigationTree.children.find(function (item) {\n      return item.name === '/community/'\n    })\n    assert(category)\n\n    return (\n      \n    )\n  })()\n}\n"
  },
  {
    "path": "docs/community/projects.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'johno', name: 'John Otander'}\n  ],\n  modified: new Date('2021-11-01'),\n  published: new Date('2018-08-11')\n}\nexport const navSortSelf = 5\n\n# Projects\n\n\n  **Note**: have another project built with MDX?\n  Please send a PR to add it here!\n\n\nThis page lists community projects using MDX.\n\n{/* more */}\n\n## Apps\n\n* [demoboard][]: The simplest editor alive\n\n## Libraries\n\n* [ok-mdx][]: Browser-based MDX editor\n* [docz][]: Documentation framework\n* [mdx-deck][]: MDX-based presentation decks\n* [mdx-docs][]: Next-based documentation framework\n* [mdx-paper][]: MDX-based research articles\n* [spectacle-boilerplate-mdx][]: Boilerplate that facilitates using MDX with\n  Spectacle\n* [Charge][]: An opinionated, zero-config static site generator\n* [MDNEXT][]: An ecosystem of tools to get your NextJS + MDX projects blasting\n  off\n\n## Sites\n\n* This website!\n* [Prisma][]\n* [Max Stoiber’s Blog][mxstbr]\n\n## Other related links\n\n* [awesome-mdx][]\n* [MDX: content for kings and princesses][mdx-fairy-tale]\n\n[awesome-mdx]: https://github.com/transitive-bullshit/awesome-mdx\n\n[charge]: https://charge.js.org\n\n[demoboard]: https://frontarm.com/demoboard\n\n[docz]: https://www.docz.site/\n\n[mdnext]: https://github.com/domitriusclark/mdnext\n\n[mdx-deck]: https://github.com/jxnblk/mdx-deck\n\n[mdx-docs]: https://github.com/jxnblk/mdx-docs\n\n[mdx-fairy-tale]: https://github.com/DeveloperMode/mdx-fairy-tale\n\n[mdx-paper]: https://github.com/hubgit/mdx-paper\n\n[mxstbr]: https://mxstbr.com\n\n[ok-mdx]: https://github.com/jxnblk/ok-mdx\n\n[prisma]: https://www.prisma.io/docs\n\n[spectacle-boilerplate-mdx]: https://github.com/FormidableLabs/spectacle-boilerplate-mdx\n"
  },
  {
    "path": "docs/community/sponsor.mdx",
    "content": "export const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2021-10-06'),\n}\nexport const navSortSelf = 3\n\n# Sponsor\n\nThis article explains how to contribute financially to MDX.\n\n{/* more */}\n\nIt’s possible to support us financially by becoming a backer or sponsor of\nunified through either [Open Collective][oc] or [GitHub Sponsors][gh].\nWith this support, we can pay for project leadership, finance non-coding work,\nor for fun things for the community like getting stickers for contributors.\nYou’ll be helping unified’s maintainers manage and improve existing projects,\nand additionally support our work to develop new and exciting projects, such\nas [micromark][].\n\n{\n  \n    \n      \n      \n      \n      \n      \n    \n    \n    \n      \n      \n      \n      \n      \n      \n      \n      \n    \n      \n    \n  
    \n        Vercel

    \n        \n          		\n        Motif

    \n        \n          		\n        HashiCorp

    \n        \n          		\n        GitBook

    \n        \n          		\n        Gatsby

    \n        \n      
    \n        Netlify

    \n        {/* OC has a sharper image */}\n        \n          		\n        Coinbase

    \n        \n          		\n        ThemeIsle

    \n        \n          		\n        Expo

    \n        \n          		\n        Boost Note

    \n        \n          		\n        Markdown Space

    \n        \n          		\n        Holloway

    \n        \n          		\n      \n    
    \n        
    \n        You?\n        

    \n      
    \n}\n\n[gh]: https://github.com/sponsors/unifiedjs\n\n[micromark]: https://github.com/micromark/micromark\n\n[oc]: https://opencollective.com/unified\n"
  },
  {
    "path": "docs/community/support.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2019-07-03')\n}\nexport const navSortSelf = 1\n\n# Support\n\nThis article explains where to get help with MDX.\nPlease read through the following guidelines.\n\n{/* more */}\n\n\n  **Important**: before participating in our community, please read our\n  [code of conduct][coc].\n  By interacting with this repository, organization, or community you agree to\n  abide by its terms.\n\n\n## Asking quality questions\n\nQuestions can go to [GitHub Discussions][chat].\n\nHelp us help you!\nSpend time framing questions and add links and resources.\nSpending the extra time up front can help save everyone time in the long run.\nHere are some tips:\n\n* Read through [§ Getting started][getting-started]\n* [Talk to a duck!][rubberduck]\n* Don’t fall for the [XY problem][xy]\n* Search to find out if a similar question has been asked\n* Try to define what you need help with:\n  * Is there something in particular you want?\n  * What problem are you encountering and what steps have you taken to try\n    and fix it?\n  * Is there a concept you don’t understand?\n* Provide sample code, such as a [CodeSandbox][cs] or video, if possible\n* Screenshots can help, but if there’s important text such as code or error\n  messages in them, please also provide those as text\n* The more time you put into asking your question, the better we can help you\n\n[chat]: https://github.com/mdx-js/mdx/discussions\n\n[coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md\n\n[cs]: https://codesandbox.io\n\n[getting-started]: /docs/getting-started/\n\n[rubberduck]: https://rubberduckdebugging.com\n\n[xy]: https://meta.stackexchange.com/questions/66377/what-is-the-xy-problem/66378#66378\n"
  },
  {
    "path": "docs/docs/extending-mdx.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2021-10-06')\n}\nexport const navSortSelf = 4\n\n# Extending MDX\n\nThis article explains how to extend MDX content—specifically, how to *transform*\ncontent with plugins. {/* more */}\nSee [§ Using MDX][use] for how to pass components, props, and the layout.\nSee [§ Getting started][start] for how to integrate MDX into your project.\n\n## Contents\n\n* [Components & plugins](#components--plugins)\n  * [List of components](#list-of-components)\n  * [List of plugins](#list-of-plugins)\n* [Using plugins](#using-plugins)\n* [Creating plugins](#creating-plugins)\n\n## Components & plugins\n\nThere are three extension points when using `@mdx-js/mdx` or one of its\nintegrations:\n\n* Options passed to the compiler (see [¶ API in `@mdx-js/mdx`][api])\n* Plugins that hook into several stages of compilation (see [remark\n  plugins][remark-plugins], [rehype plugins][rehype-plugins], and\n  [recma plugins][recma-plugins])\n* Components passed, defined, or imported at runtime (see [§ Using MDX][use])\n\nMost of the time, these components and plugins are not coupled to MDX.\nFor example, if you’re using React, then you can use\n[``][react-confetti] with MDX.\nOr, you can use the plugin [`remark-gfm`][remark-gfm] to turn on GFM features in\nMDX.\nSometimes, we need specific components or specific plugins to work with MDX.\nWe’re compiling those here on this page.\n\n### List of components\n\n* [`PaulieScanlon/mdx-embed`](https://github.com/PaulieScanlon/mdx-embed)\n  — React components for embedding 3rd party content, integrates w/\n  MDX provider\n* [`system-ui/theme-ui`](https://github.com/system-ui/theme-ui)\n  — React components for building consistent apps, integrates w/ MDX provider\n\n{/*\n  * Please use alpha sorting on **project** name!\n  * You can use this template:\n  *\n  * ```markdown\n  * * [`user/project`](https://github.com/user/project)\n  *   — somewhat short description of the project\n  * ```\n  */}\n\n\n  **Note**: have another component that *specifically* works with MDX?\n  Please send a PR to add it here!\n\n\n### List of plugins\n\nSee also the [list of remark plugins][remark-plugins],\n[list of rehype plugins][rehype-plugins], and\n[list of recma plugins][recma-plugins].\n\n* [`remcohaszing/recma-export-filepath`](https://github.com/remcohaszing/recma-export-filepath)\n  — export the filepath\n* [`ipikuka/recma-mdx-change-props`](https://github.com/ipikuka/recma-mdx-change-props)\n  — changes the param as `_props` in the `_createMdxContent` function\n* [`domdomegg/recma-mdx-displayname`](https://github.com/domdomegg/recma-mdx-displayname)\n  — add a `displayName` to `MDXContent` components, to enable switching\n  on them in production\n* [`ipikuka/recma-mdx-escape-missing-components`](https://github.com/ipikuka/recma-mdx-escape-missing-components)\n  — set a default value of `() => null` for missing components instead of\n  throwing an error\n* [`remcohaszing/recma-mdx-is-mdx-component`](https://github.com/remcohaszing/recma-mdx-is-mdx-component)\n  — add an `isMdxComponent` field on MDX components\n* [`remcohaszing/recma-nextjs-static-props`](https://github.com/remcohaszing/recma-nextjs-static-props)\n  — generate [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching/get-static-props)\n  exposing top level identifiers in Next.js\n* [`remcohaszing/recma-module-to-function`](https://github.com/remcohaszing/recma-module-to-function)\n  — convert a module into a function body\n* [`remcohaszing/rehype-mdx-code-props`](https://github.com/remcohaszing/rehype-mdx-code-props)\n  — interpret the code `meta` field as JSX props\n* [`remcohaszing/rehype-mdx-import-media`](https://github.com/remcohaszing/rehype-mdx-import-media)\n  — change media sources to JavaScript imports\n* [`remcohaszing/rehype-mdx-title`](https://github.com/remcohaszing/rehype-mdx-title)\n  — expose the page title as a string\n* [`boning-w/rehype-mdx-toc`](https://github.com/boning-w/rehype-mdx-toc)\n  — export the table of contents data into MDX module\n* [`re-xyr/remark-directive-mdx`](https://github.com/re-xyr/remark-directive-mdx)\n  — transform Markdown directives (`:directive[]`) to JSX elements\n* [`pangelani/remark-mdx-chartjs`](https://github.com/pangelani/remark-mdx-chartjs)\n  — replace fenced code blocks with charts using [`react-chartjs-2`](https://react-chartjs-2.js.org/).\n* [`remcohaszing/remark-mdx-frontmatter`](https://github.com/remcohaszing/remark-mdx-frontmatter)\n  — change frontmatter (YAML) metadata to exports\n* [`goodproblems/remark-mdx-math-enhanced`](https://github.com/goodproblems/remark-mdx-math-enhanced)\n  — enhance math with JavaScript inside it\n\n{/*\n  * Please use alpha sorting on **project** name!\n  * You can use this template:\n  *\n  * ```markdown\n  * * [`user/project`](https://github.com/user/project)\n  *   — somewhat short description of the project\n  * ```\n  */}\n\n\n  **Note**: have another unified plugin that *specifically* works with MDX?\n  Please send a PR to add it here!\n\n\n## Using plugins\n\nWhere to pass plugins is encoded in their name:\nremark plugins go in `remarkPlugins`,\nrehype plugins go in `rehypePlugins`,\nand recma plugins go in `recmaPlugins` of\n[`ProcessorOptions`][processor-options].\nThose fields expect lists of plugins and/or of `[plugin, options]`:\n\n```tsx twoslash\nimport {compile} from '@mdx-js/mdx'\nimport rehypeKatex from 'rehype-katex' // Render math with KaTeX.\nimport remarkFrontmatter from 'remark-frontmatter' // YAML and such.\nimport remarkGfm from 'remark-gfm' // Tables, footnotes, strikethrough, task lists, literal URLs.\nimport remarkMath from 'remark-math' // Support math like `$so$`.\n\nconst file = '# hi'\n\n// One plugin:\nawait compile(file, {remarkPlugins: [remarkGfm]})\n\n// A plugin with options:\nawait compile(file, {remarkPlugins: [[remarkFrontmatter, 'toml']]})\n\n// Two plugins:\nawait compile(file, {remarkPlugins: [remarkGfm, remarkFrontmatter]})\n\n// Two plugins, first w/ options:\nawait compile(file, {remarkPlugins: [[remarkGfm, {singleTilde: false}], remarkFrontmatter]})\n\n// remark and rehype plugins:\nawait compile(file, {rehypePlugins: [rehypeKatex], remarkPlugins: [remarkMath]})\n\n// remark and rehype plugins, last w/ options:\nawait compile(file, {\n  // A plugin with options:\n  rehypePlugins: [[rehypeKatex, {strict: true, throwOnError: true}]],\n  remarkPlugins: [remarkMath]\n})\n```\n\n## Creating plugins\n\nCreating a plugin for MDX is mostly the same as creating a plugin for remark,\nrehype, or recma.\nThere are several guides and recipes on that in [§ Learn on\n`unifiedjs.com`][learn].\n\nFor the MDX specific parts of plugins, it’s recommended to read\n[¶ Architecture][architecture] to learn how `@mdx-js/mdx` works.\nFor info on the node types that represent MDX specific features, see\n[¶ Syntax tree in `remark-mdx`][syntax-tree] and use our interactive\n[§ Playground][playground].\n\n[api]: /packages/mdx/#api\n\n[architecture]: /packages/mdx/#architecture\n\n[learn]: https://unifiedjs.com/learn/\n\n[playground]: /playground/\n\n[processor-options]: /packages/mdx/#processoroptions\n\n[react-confetti]: https://github.com/alampros/react-confetti\n\n[recma-plugins]: https://github.com/mdx-js/recma/blob/main/doc/plugins.md#list-of-plugins\n\n[rehype-plugins]: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins\n\n[remark-gfm]: https://github.com/remarkjs/remark-gfm\n\n[remark-plugins]: https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins\n\n[start]: /docs/getting-started/\n\n[syntax-tree]: /packages/remark-mdx/#syntax-tree\n\n[use]: /docs/using-mdx/\n"
  },
  {
    "path": "docs/docs/getting-started.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2021-10-05')\n}\nexport const navSortSelf = 2\n\n# Getting started\n\nThis article explains how to integrate MDX into your project.\nIt shows how to use MDX with your bundler and JSX runtime of choice. {/* more */}\nTo understand how the MDX format works,\nwe recommend that you start with [§ What is MDX][what].\nSee [§ Using MDX][use] when you’re all set up and ready to use MDX.\n\n## Contents\n\n* [Prerequisites](#prerequisites)\n* [Quick start](#quick-start)\n  * [Bundler](#bundler)\n  * [JSX](#jsx)\n  * [Editor](#editor)\n  * [Types](#types)\n  * [Security](#security)\n* [Integrations](#integrations)\n  * [Bundlers](#bundlers)\n  * [Build systems](#build-systems)\n  * [Linters](#linters)\n  * [Compilers](#compilers)\n  * [Site generators](#site-generators)\n  * [JSX runtimes](#jsx-runtimes)\n  * [JavaScript engines](#javascript-engines)\n* [Further reading](#further-reading)\n\n## Prerequisites\n\nMDX relies on JSX,\nso it’s required that your project supports JSX as well.\nAny JSX runtime (React, Preact, Vue, etc.) will do.\nNote that we do compile JSX to JavaScript for you so you don’t have to set that\nup.\n\nAll `@mdx-js/*` packages are written in modern JavaScript.\nA [Node.js][node-js] version of 16 or later is needed to use them.\nOur packages are also [ESM only][github-gist-esm].\n\n\n  **Note**: Using Rust instead of Node.js?\n  Try [`mdxjs-rs`][mdxjs-rs]!\n\n\n## Quick start\n\n### Bundler\n\nMDX is a language that’s compiled to JavaScript.\n(We also compile regular markdown to JavaScript.)\nThe easiest way to get started is to use an integration for your bundler if you\nhave one:\n\n* if you use **esbuild** (or Bun),\n  install and configure [`@mdx-js/esbuild`][mdx-esbuild]\n* if you use **Rollup** (or Vite),\n  install and configure [`@mdx-js/rollup`][mdx-rollup]\n* if you use **webpack** (or Next.js),\n  install and configure [`@mdx-js/loader`][mdx-loader]\n\nYou can also use MDX without bundlers:\n\n* you can import MDX files in **Node.js** with\n  [`@mdx-js/node-loader`][mdx-node-loader]\n* you can use our core compiler [`@mdx-js/mdx`][mdx-mdx] to compile MDX files\n* you can use our core compiler [`@mdx-js/mdx`][mdx-mdx] to\n  [evaluate][api-evaluate] (compile *and run*) MDX files\n\nFor more info on these tools,\nsee their dedicated sections:\n[¶ Next.js][site-generator-next],\n[¶ Node.js][js-engine-node],\n[¶ Rollup][bundler-rollup],\n[¶ Vite][build-system-vite],\n[¶ esbuild][bundler-esbuild], and\n[¶ webpack][bundler-webpack].\n\n### JSX\n\nNow you’ve set up an integration or `@mdx-js/mdx` itself,\nit’s time to configure your JSX runtime.\n\n* if you use **React**,\n  that’s the default;\n  optionally install and configure [`@mdx-js/react`][mdx-react]\n* if you use **Preact**,\n  set [`jsxImportSource` in `ProcessorOptions`][api-processor-options] to\n  `'preact'`;\n  optionally install and configure [`@mdx-js/preact`][mdx-preact]\n* if you use **Svelte**,\n  install [`svelte-jsx`][svelte-jsx],\n  and set [`jsxImportSource` in `ProcessorOptions`][api-processor-options] to\n  `'svelte-jsx'`\n* if you use **Vue**,\n  set [`jsxImportSource` in `ProcessorOptions`][api-processor-options] to\n  `'vue'`;\n  optionally install and configure [`@mdx-js/vue`][mdx-vue]\n* if you use **Solid**,\n  set [`jsxImportSource` in `ProcessorOptions`][api-processor-options] to\n  `'solid-js/h'`\n* if you use **Emotion**,\n  set [`jsxImportSource` in `ProcessorOptions`][api-processor-options] to\n  `'@emotion/react'`\n* if you use **Theme UI**,\n  install and configure [`@mdx-js/react`][mdx-react],\n  then wrap your MDX content in a ``\n\nOther JSX runtimes are supported by setting\n[`jsxImportSource` in `ProcessorOptions`][api-processor-options].\n\nFor more info on these tools,\nsee their dedicated sections:\n[¶ Emotion][jsx-runtime-emotion],\n[¶ Preact][jsx-runtime-preact],\n[¶ React][jsx-runtime-react],\n[¶ Solid][jsx-runtime-solid],\n[¶ Svelte][jsx-runtime-svelte],\n[¶ Theme UI][jsx-runtime-theme-ui], and\n[¶ Vue][jsx-runtime-vue].\n\n### Editor\n\nYou can enhance the experience of using MDX by adding support of it to your\neditor:\n\n* if you use **VS Code**,\n  try [`mdx-js/mdx-analyzer`][mdx-analyzer]\n* if you use **Vim**,\n  try [`jxnblk/vim-mdx-js`][vim-mdx-js]\n* if you use **Sublime Text**,\n  try [`jonsuh/mdx-sublime`][mdx-sublime]\n* if you use **JetBrains IntelliJ/WebStorm**,\n  try [`JetBrains/mdx-intellij-plugin`][mdx-intellij-plugin]\n\nThe syntax highlighting that powers our VS Code extension and that is used\nto highlight code blocks on GitHub is maintained at\n[`wooorm/markdown-tm-language`][markdown-tm-language].\n\n### Types\n\n
    \n  Expand example of typed imports\n\n  First install the package:\n\n  ```sh\n  npm install @types/mdx\n  ```\n\n  …TypeScript should automatically pick it up:\n\n  ```js twoslash path=\"example.js\"\n  // @filename: types.d.ts\n  import type {} from 'mdx'\n  // @filename: example.js\n  // ---cut---\n  import Post from './post.mdx' // `Post` is now typed.\n  ```\n
    \n\nOur packages are typed with [TypeScript][].\nFor types to work,\nthe `JSX` namespace must be typed.\nThis is done by installing and using the types of your framework,\nsuch as [`@types/react`][definitely-typed-react],\nthen augmenting the `mdx/types.js` module.\n\n```ts twoslash path=\"example.ts\"\nimport * as React from 'react'\n\ndeclare module 'mdx/types.js' {\n  export import JSX = React.JSX\n}\n```\n\nTo enable types for imported `.mdx`, `.md`, etc.,\ninstall and use [`@types/mdx`][definitely-typed-mdx].\nThis package also exports several useful types,\nsuch as `MDXComponents` which represents the `components` prop.\nYou can import them like so:\n\n```ts twoslash path=\"example.ts\"\nimport type {MDXComponents} from 'mdx/types.js'\n```\n\n### Security\n\nMDX is a programming language.\nIf you trust your authors,\nthat’s fine.\nIf you don’t,\nit’s unsafe.\n\nDo not let random people from the internet write MDX.\nIf you do,\nyou might want to look into using `\n  \n  ```\n\n\n## Embeds at run time\n\nYou can use the React-specific [MDX Embed][mdx-embed] to embed things in MDX.\nHere is an example MDX file that uses a specific embed without `@mdx-js/react`:\n\n```mdx path=\"example.mdx\"\nimport {CodePen} from 'mdx-embed'\n\nHere’s a codepen, and some other blog post text.\n\n\n```\n\n
    \n  Expand equivalent JSX\n\n  ```jsx path=\"output.jsx\"\n  <>\n    
    Here’s a codepen, and some other blog post text.
    \n    \n  \n  ```\n
    \n\nIf you don’t want to use explicit imports in MDX files:\n\n```mdx path=\"example.mdx\"\nHere’s a codepen, and some other blog post text.\n\n\n```\n\nThen you can either pass all components:\n\n```jsx path=\"example.jsx\"\nimport * as embeds from 'mdx-embed'\nimport Example from './example.mdx' // Assumes an integration is used to compile MDX -> JS.\n\nconsole.log()\n```\n\nOr, if you’ve installed and configured [`@mdx-js/react`][mdx-react], you can\nalso use `MDXEmbedProvider`:\n\n```jsx path=\"example.jsx\"\nimport {MDXEmbedProvider} from 'mdx-embed'\nimport Example from './example.mdx' // Assumes an integration is used to compile MDX -> JS.\n\nconsole.log(\n  \n    \n  \n)\n```\n\n[commonmark]: https://spec.commonmark.org/current/\n\n[mdx-embed]: https://mdx-embed.netlify.app/\n\n[mdx-react]: /packages/react/\n\n[remark-embedder]: https://github.com/remark-embedder/core\n"
  },
  {
    "path": "docs/guides/frontmatter.mdx",
    "content": "export const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2021-10-06')\n}\nexport const navSortSelf = 2\n\n# Frontmatter\n\nThis guide explores how to support YAML frontmatter in MDX. {/* more */}\nMDX supports standard markdown syntax ([CommonMark][]).\nThat means frontmatter is not supported by default.\n\nMDX comes with a powerful and dynamic alternative to frontmatter, namely ESM\n(`import`/`export`).\nThese exports:\n\n```mdx path=\"example.mdx\"\nexport const name = 'World'\nexport const title = 'Hi, ' + name + '!'\n\n# {title}\n```\n\nCan be used like so:\n\n```js twoslash path=\"example.js\"\n// @filename: types.d.ts\ndeclare module '*.mdx' {\n  export {MDXContent as default} from 'mdx/types'\n  export const name: string\n  export const title: string\n}\n// @filename: example.js\n/// \n// ---cut---\nimport * as Post from './example.mdx' // Assumes an integration is used to compile MDX -> JS.\n\nconsole.log(Post.title) // Prints 'Hi, World!'\n```\n\nYou might prefer frontmatter though, as it lets you define data that can be\nextracted from the file system *before* compiling.\nSay our MDX with frontmatter looked like this:\n\n```mdx path=\"example.mdx\"\n---\ntitle: Hi, World!\n---\n\n# Hi, World!\n```\n\nThen without compiling or evaluating the metadata can be accessed like so:\n\n```js twoslash path=\"example.js\"\n/// \n// ---cut---\nimport {read} from 'to-vfile'\nimport {matter} from 'vfile-matter'\n\nconst file = await read('example.mdx')\nmatter(file)\n\nconsole.log(file.data.matter)\n```\n\nOur compiler, `@mdx-js/mdx`, doesn’t understand YAML frontmatter by default but\nit can be enabled by using a remark plugin,\n[`remark-frontmatter`][remark-frontmatter]:\n\n```js twoslash path=\"example.js\"\n// @filename: example.js\n/// \n// ---cut---\nimport fs from 'node:fs/promises'\nimport {compile} from '@mdx-js/mdx'\nimport remarkFrontmatter from 'remark-frontmatter'\n\nconst file = await compile(await fs.readFile('example.mdx'), {\n  remarkPlugins: [remarkFrontmatter]\n})\n\nconsole.log(file)\n```\n\nNow it “works”.\nThe frontmatter is not rendered as if it was markdown.\nBut the data embedded in the frontmatter isn’t available from *inside* the MDX.\nWhat if we wanted that too?\nLike so:\n\n```mdx path=\"example.mdx\"\n---\ntitle: Hi, World!\n---\n\n# {title}\n```\n\nThat’s exactly what the remark plugin\n[`remark-mdx-frontmatter`][remark-mdx-frontmatter] does.\n\nThat plugin, like all remark plugins, can be passed as\n[`remarkPlugins` in `ProcessorOptions`][processor-options].\nMore info on plugins is available in [§ Extending MDX][extend]\n\n[commonmark]: https://spec.commonmark.org/current/\n\n[extend]: /docs/extending-mdx/\n\n[processor-options]: /packages/mdx/#processoroptions\n\n[remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter\n\n[remark-mdx-frontmatter]: https://github.com/remcohaszing/remark-mdx-frontmatter\n"
  },
  {
    "path": "docs/guides/gfm.mdx",
    "content": "export const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2021-10-06')\n}\nexport const navSortSelf = 1\n\n# GitHub flavored markdown (GFM)\n\nThis guide explores how to support GFM features such as autolink literals,\nfootnotes, strikethrough, tables, and task lists. {/* more */}\nMDX supports standard markdown syntax ([CommonMark][]).\nThat means [GitHub flavored markdown (GFM)][gfm] extensions are not supported by\ndefault.\nThey can be enabled by using a remark plugin: [`remark-gfm`][remark-gfm].\nThat plugin, like all remark plugins, can be passed in [`remarkPlugins` in\n`ProcessorOptions`][processor-options].\nMore info on plugins is available in [§ Extending MDX][extend]\n\nSay we have an MDX file like this:\n\n```mdx path=\"example.mdx\"\n# GFM\n\n## Autolink literals\n\nwww.example.com, https://example.com, and contact@example.com.\n\n## Footnote\n\nA note[^1]\n\n[^1]: Big note.\n\n## Strikethrough\n\n~one~ or ~~two~~ tildes.\n\n## Table\n\n| a | b  |  c |  d  |\n| - | :- | -: | :-: |\n\n## Tasklist\n\n* [ ] to do\n* [x] done\n```\n\nThe above MDX with GFM can be transformed with the following module:\n\n```js twoslash path=\"example.js\"\n// @filename: example.js\n/// \n// ---cut---\nimport fs from 'node:fs/promises'\nimport {compile} from '@mdx-js/mdx'\nimport remarkGfm from 'remark-gfm'\n\nconsole.log(\n  String(\n    await compile(await fs.readFile('example.mdx'), {remarkPlugins: [remarkGfm]})\n  )\n)\n```\n\n
    \n  Expand equivalent JSX\n\n  ```jsx path=\"output.jsx\"\n  <>\n    
    GFM
    \n    
    Autolink literals
    \n    
    \n      www.example.com,{' '}\n      https://example.com, and{' '}\n      contact@example.com.\n    
    \n    
    Footnote
    \n    
    \n      A note\n      \n        \n          1\n        \n      \n    
    \n    
    Strikethrough
    \n    
    \n      one or two tildes.\n    
    \n    
    Table
    \n    \n      \n        \n          \n          \n          \n          \n        \n      \n    
    abcd
    \n    
    Tasklist
    \n    
      \n      
    • \n         to do\n      
      • \n      
    • \n        \n        done\n      
      • \n    
    \n    
    \n      
    \n        Footnotes\n      
    \n      
      \n        
    1. \n          
      \n            Big note.{' '}\n            \n              ↩\n            \n          
      \n        
      2. \n      
    \n    
    \n  \n  ```\n
    \n\n[commonmark]: https://spec.commonmark.org/current/\n\n[extend]: /docs/extending-mdx/\n\n[gfm]: https://github.github.com/gfm/\n\n[processor-options]: /packages/mdx/#processoroptions\n\n[remark-gfm]: https://github.com/remarkjs/remark-gfm\n"
  },
  {
    "path": "docs/guides/index.mdx",
    "content": "{\n  /**\n   * @import {Item} from '../_component/sort.js'\n   */\n\n  /**\n   * @typedef Props\n   * @property {Item} navigationTree\n   */\n}\n\nimport assert from 'node:assert/strict'\nimport {NavigationGroup} from '../_component/nav.jsx'\n\nexport const info = {\n  author: [{name: 'MDX Contributors'}],\n  modified: new Date('2024-07-04'),\n  published: new Date('2021-11-01')\n}\nexport const navSortSelf = 2\n\n# Guides\n\nThese guides explain how to accomplish several common use cases and patterns\naround MDX.\n\n{\n  (function () {\n    const navigationTree = props.navigationTree\n    const category = navigationTree.children.find(function (item) {\n      return item.name === '/guides/'\n    })\n    assert(category)\n\n    return (\n      \n    )\n  })()\n}\n"
  },
  {
    "path": "docs/guides/injecting-components.mdx",
    "content": "export const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2024-07-04'),\n  published: new Date('2023-10-24')\n}\nexport const navSortSelf = 7\n\n# Injecting components\n\nThis guide shows how to inject arbitrary components into MDX when it\nruns. {/* more */}\nIt shows how the underlying features used by our providers (`@mdx-js/react`,\n`@mdx-js/preact`) and the [`mdx-components.tsx`][next-mdx-components] file\nsupported by Next.js work,\nand how you can take advantage of that functionality yourself.\n\nIn many cases you do not need this,\nas you can pass components to MDX:\n\n```mdx path=\"example.mdx\"\n# Hello **\n```\n\nYou can pass `Planet` and say a component used instead of the `h1`:\n\n```jsx twoslash path=\"example.jsx\"\n// @filename: types.d.ts\nimport type {} from 'mdx'\n// @filename: example.jsx\n/// \n/* @jsxImportSource react */\n// ---cut---\nimport Example from './example.mdx' // Assumes an integration is used to compile MDX -> JS.\n\nconsole.log(\n  \n      }\n    }}\n  />\n)\n```\n\nWhen you find yourself passing that `components` prop around a lot,\nyou might want to look at an alternative.\nYou might reach for our context based providers (`@mdx-js/react`,\n`@mdx-js/preact`),\nbut context has performance downsides and context doesn’t always work (such as\nin RSC).\n\nBut first,\nhow does component passing work?\nThat can be illustrated by looking at the code generated by MDX for the above\n`example.mdx`.\nHere is a diff that shows what the example normally compiles to and what\nchanges when `providerImportSource: 'xxx'` is passed:\n\n```diff\n@@ -1,7 +1,13 @@\n import {jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'\n+import {useMDXComponents as _provideComponents} from 'xxx'\n\n function _createMdxContent(props) {\n-  const _components = {em: 'em', h1: 'h1', ...props.components}\n+  const _components = {\n+    em: 'em',\n+    h1: 'h1',\n+    ..._provideComponents(),\n+    ...props.components\n+  }\n   const {Planet} = _components\n   if (!Planet) _missingMdxReference('Planet', true)\n   return _jsxs(_components.h1, {\n@@ -10,7 +16,7 @@ function _createMdxContent(props) {\n }\n\n export default function MDXContent(props = {}) {\n-  const {wrapper: MDXLayout} = props.components || {}\n+  const {wrapper: MDXLayout} = {..._provideComponents(), ...props.components}\n   return MDXLayout\n     ? _jsx(MDXLayout, {...props, children: _jsx(_createMdxContent, {...props})})\n     : _createMdxContent(props)\n```\n\nObserve that components have defaults (such as that `h1` will use `'h1'`) and\nthat components are taken from `props.components`.\nWhat changes is an added call to `_provideComponents`,\nwhich refers to an `useMDXComponents` export from the module we specified\n(`xxx`).\n\nWe can use this interface to inject components from a file.\nIn that file,\nwe need a `useMDXComponents` function that returns our components.\n\n```jsx twoslash path=\"mdx-components.js\"\n// @filename: mdx-components.jsx\n/* @jsxImportSource react */\n// ---cut---\n/**\n * @import {MDXComponents} from 'mdx/types.js'\n */\n\n/** @returns {MDXComponents} */\nexport function useMDXComponents() {\n  return {\n    Planet() {\n      return 'Pluto'\n    },\n    h1(properties) {\n      return 
    \n    }\n  }\n}\n```\n\nAnd now passing a file path or URL to that file as `providerImportSource`,\nsuch as with `import.meta.resolve('./mdx-components.js')`:\n\n```diff\n@@ -1,5 +1,5 @@\n import {jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime'\n-import {useMDXComponents as _provideComponents} from 'xxx'\n+import {useMDXComponents as _provideComponents} from 'file:///Users/tilde/…/mdx-components.js'\n```\n\nNow our locally defined components will be used in all MDX files!\n\n[next-mdx-components]: https://nextjs.org/docs/pages/building-your-application/configuring/mdx\n"
  },
  {
    "path": "docs/guides/math.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2021-10-06')\n}\nexport const navSortSelf = 3\n\n# Math\n\nThis guide explores how to support math (LaTeX) in MDX. {/* more */}\nMDX supports standard markdown syntax ([CommonMark][]).\nThat means math is not supported by default.\nMath can be enabled by using a remark plugin: [`remark-math`][remark-math],\ncombined with a rehype plugin: either\n[`rehype-katex`][rehype-katex] (KaTeX) or [`rehype-mathjax`][rehype-mathjax]\n(MathJax).\nLike other remark and rehype plugins, they can be passed in [`remarkPlugins`\nand `rehypePlugins`, respectively, in `ProcessorOptions`][processor-options].\nMore info on plugins is available in [§ Extending MDX][extend]\n\nSay we have an MDX file like this:\n\n```mdx path=\"example.mdx\"\n# $$\\sqrt{a^2 + b^2}$$\n```\n\nThe above MDX with math can be transformed with the following module:\n\n```js twoslash path=\"example.js\"\n// @filename: example.js\n/// \n// ---cut---\nimport fs from 'node:fs/promises'\nimport {compile} from '@mdx-js/mdx'\nimport rehypeKatex from 'rehype-katex'\nimport remarkMath from 'remark-math'\n\nconsole.log(\n  String(\n    await compile(await fs.readFile('example.mdx'), {\n      rehypePlugins: [rehypeKatex],\n      remarkPlugins: [remarkMath]\n    })\n  )\n)\n```\n\n
    \n  Expand equivalent JSX\n\n  ```jsx path=\"output.jsx\"\n  <>\n    
    \n      \n        \n          …\n        \n        \n          …\n        \n      \n    
    \n  \n  ```\n
    \n\n\n  **Important**: if you chose `rehype-katex`, you should also use `katex.css`\n  somewhere on the page to style math properly.\n  At the time of writing, the last version is:\n\n  ```html\n  \n  \n  ```\n\n  To get the latest link to the stylesheet, go to [`katex docs`][katex-browser].\n\n  {/* to do: once in a while, get the latest. */}\n\n\n\n  **Note:** see also\n  [`remark-mdx-math-enhanced`](https://github.com/goodproblems/remark-mdx-math-enhanced),\n  which you can use to support JavaScript expressions inside of math (such as to\n  access properties or to make calculations)\n\n\n[commonmark]: https://spec.commonmark.org/current/\n\n[extend]: /docs/extending-mdx/\n\n[katex-browser]: https://katex.org/docs/browser#loading-as-global\n\n[processor-options]: /packages/mdx/#processoroptions\n\n[rehype-katex]: https://github.com/remarkjs/remark-math/tree/main/packages/rehype-katex\n\n[rehype-mathjax]: https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax\n\n[remark-math]: https://github.com/remarkjs/remark-math/tree/main/packages/remark-math\n"
  },
  {
    "path": "docs/guides/mdx-on-demand.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2021-11-13')\n}\nexport const navSortSelf = 6\n\n# MDX on demand\n\nThis guide shows how to use `@mdx-js/mdx` to compile MDX on the server and run\nthe result on clients. {/* more */}\nSome frameworks, such as Next.js and Remix, make it easy to split work between\nservers and clients.\nUsing that it’s possible to for example do most of the work on demand on the\nserver instead of at build time, then pass the resulting data to clients, where\nthey finally use it.\n\nThis is similar to what people sometimes use [`mdx-bundler`][mdx-bundler] or\n[`next-mdx-remote`][next-mdx-remote] for, but MDX also supports it.\n\n## Quick example\n\nOn the server:\n\n```js twoslash path=\"server.js\"\nimport {compile} from '@mdx-js/mdx'\n\nconst code = String(await compile('# hi', {\n  outputFormat: 'function-body',\n  /* …otherOptions */\n}))\n// To do: send `code` to the client somehow.\n```\n\nOn the client:\n\n```js twoslash path=\"client.js\"\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```\n\n`Content` is now an `MDXContent` component that you can use like normal in your\nframework (see [§ Using MDX][use]).\n\nMore information is available in the API docs of `@mdx-js/mdx` for\n[`compile`][compile] and [`run`][run].\nFor other use cases, you can also use [`evaluate`][eval], which both compiles\nand runs in one.\n\n\n  **Note**: MDX is not a bundler (esbuild, webpack, and Rollup are bundlers):\n  you can’t import other code from the server within the string of MDX and get a\n  nicely minified bundle out or so.\n\n\n## Next.js example\n\nSome frameworks let you write the server and client code in one file, such as\nNext.\n\n```js twoslash path=\"pages/hello.js\"\n/**\n * @import {MDXModule} from 'mdx/types.js'\n * @import {Dispatch, ReactElement, SetStateAction} from 'react'\n */\n\nimport {compile, run} from '@mdx-js/mdx'\nimport {Fragment, useEffect, useState} from 'react'\nimport * as runtime from 'react/jsx-runtime'\n\n/**\n * @param {{code: string}} props\n * @returns {ReactElement}\n */\nexport default function Page({code}) {\n  /** @type {[MDXModule | undefined, Dispatch>]} */\n  const [mdxModule, setMdxModule] = useState()\n  const Content = mdxModule ? mdxModule.default : Fragment\n\n  useEffect(\n    function () {\n      ;(async function () {\n        setMdxModule(await run(code, {...runtime, baseUrl: import.meta.url}))\n      })()\n    },\n    [code]\n  )\n\n  return \n}\n\nexport async function getStaticProps() {\n  const code = String(\n    await compile('# hi', {\n      outputFormat: 'function-body'\n      /* …otherOptions */\n    })\n  )\n  return {props: {code}}\n}\n```\n\n[compile]: /packages/mdx/#compilefile-options\n\n[eval]: /packages/mdx/#evaluatefile-options\n\n[mdx-bundler]: https://github.com/kentcdodds/mdx-bundler\n\n[next-mdx-remote]: https://github.com/hashicorp/next-mdx-remote\n\n[run]: /packages/mdx/#runcode-options\n\n[use]: /docs/using-mdx/\n"
  },
  {
    "path": "docs/guides/syntax-highlighting.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2021-10-06')\n}\nexport const navSortSelf = 4\n\n# Syntax highlighting\n\nThis guide explores how to apply syntax highlighting to code\nblocks. {/* more */}\nMDX supports standard markdown syntax ([CommonMark][]).\nIt does not apply syntax highlighting to code blocks by default.\n\nThere are two ways to accomplish syntax highlighting: at compile time or at\nruntime.\nDoing it at compile time means the effort is spent upfront so that readers will\nhave a fast experience as no extra code is sent to them (syntax highlighting\nneeds a *lot* of code to work).\nDoing it at runtime gives more flexibility by moving the work to the client.\nThis can result in a slow experience for readers though.\nIt also depends on what framework you use (as in it’s specific to React, Preact,\nVue, etc.)\n\n## Syntax highlighting at compile time\n\nUse for example [`rehype-starry-night`][rehype-starry-night] (`starry-night`),\n[`rehype-highlight`][rehype-highlight] (`lowlight`, `highlight.js`),\nor [`@mapbox/rehype-prism`][rehype-prism] (`refractor`, `prism`)\nby doing something like this:\n\n```js twoslash path=\"example.js\"\n/// \n// ---cut---\nimport {compile} from '@mdx-js/mdx'\nimport rehypeStarryNight from 'rehype-starry-night'\n\nconst code = `~~~js\nconsole.log(1)\n~~~`\n\nconsole.log(\n  String(await compile(code, {rehypePlugins: [rehypeStarryNight]}))\n)\n```\n\n
    \n  Expand equivalent JSX\n\n  ```jsx path=\"output.jsx\"\n  <>\n    
    \n      \n        console.log(1)\n      \n    
    \n  \n  ```\n
    \n\n\n  **Important**: you must likely also include CSS somewhere on the page.\n  See the documentation of the plugin you’re using for more information.\n\n\n## Syntax highlighting at run time\n\nUse for example\n[`react-syntax-highlighter`][react-syntax-highlighter],\nby doing something like this:\n\n{/* Note: `react-syntax-highlighter` doesn’t seem actively maintained so no twoslash to check this example. */}\n\n```jsx path=\"example.jsx\"\nimport SyntaxHighlighter from 'react-syntax-highlighter'\nimport Post from './example.mdx' // Assumes an integration is used to compile MDX -> JS.\n\nconsole.log()\n\nfunction code({className, ...properties}) {\n  const match = /language-(\\w+)/.exec(className || '')\n  return match\n    ? \n    : \n}\n```\n\n
    \n  Expand equivalent JSX\n\n  ```jsx path=\"output.jsx\"\n  <>\n    
    \n      \n        \n          console.\n          log\n          (\n          1\n          )\n        \n      
    \n    
    \n  \n  ```\n\n\n## Syntax highlighting with the `meta` field\n\nMarkdown supports a meta string for code:\n\n````mdx path=\"example.mdx\"\n```js filename=\"index.js\"\nconsole.log(1)\n```\n````\n\nThe `meta` part is everything after the language (in this case, `js`).\nThis is a *hidden* part of markdown: it’s normally ignored.\nBut as the above example shows, it’s a useful place to put some extra fields.\n\n`@mdx-js/mdx` doesn’t know whether you’re handling code as a component or what\nthe format of that meta string is, so it defaults to how markdown handles it:\n`meta` is ignored.\n\nBut what if you want to access `meta` at runtime?\nThat’s exactly what the rehype plugin\n[`rehype-mdx-code-props`][rehype-mdx-code-props] does.\nIt lets you type JSX attributes in the `meta` part which you can access by\nwith a component for `pre`.\n\nThat plugin, like all rehype plugins, can be passed as\n[`rehypePlugins` in `ProcessorOptions`][processor-options].\nMore info on plugins is available in [§ Extending MDX][extend]\n\n[commonmark]: https://spec.commonmark.org/current/\n\n[extend]: /docs/extending-mdx/\n\n[processor-options]: /packages/mdx/#processoroptions\n\n[react-syntax-highlighter]: https://github.com/react-syntax-highlighter/react-syntax-highlighter\n\n[rehype-highlight]: https://github.com/rehypejs/rehype-highlight\n\n[rehype-mdx-code-props]: https://github.com/remcohaszing/rehype-mdx-code-props\n\n[rehype-prism]: https://github.com/mapbox/rehype-prism\n\n[rehype-starry-night]: https://github.com/rehypejs/rehype-starry-night\n"
  },
  {
    "path": "docs/index.mdx",
    "content": "import {Chart} from './_component/snowfall.jsx'\n\nexport {Home as default} from './_component/home.jsx'\nexport const info = {\n  author: [\n    {github: 'johno', name: 'John Otander'},\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2017-12-23'),\n  schemaOrg: {\n    \"@context\": \"https://schema.org\",\n    \"@type\": \"SoftwareApplication\",\n    \"additionalType\": \"ComputerLanguage\",\n    \"applicationCategory\": \"DeveloperApplication\",\n    \"description\": \"an authorable format for writing JSX in markdown documents\",\n    \"name\": \"MDX\",\n    \"offers\": {\n      \"@type\": \"Offer\",\n      \"price\": \"0.00\",\n      \"priceCurrency\": \"USD\"\n    },\n    \"operatingSystem\": \"Windows, MacOS, Linux\",\n    \"sameAs\": [\n      \"https://www.wikidata.org/wiki/Q95971592\",\n      \"https://www.wikidata.org/wiki/Q27966906\",\n      \"https://www.wikidata.org/wiki/Q95961071\",\n      \"https://en.wikipedia.org/wiki/MDX_(markup_language)\",\n      \"https://github.com/mdx-js/mdx\"\n    ],\n    \"url\": \"https://mdxjs.com\"\n  }\n}\nexport const year = 2023\n\n{/* lint disable heading-style */}\n\nMarkdown for the\\\n**component era**\n=================\n\nMDX lets you use JSX in your markdown content.\nYou can import components, such as interactive charts or alerts, and embed them\nwithin your content.\nThis makes writing long-form content with components a blast. {/* more */}\n🚀\n[Continue reading »][what]\n\n
    \n  ## New: MDX 3!\n\n  A small major this time, nothing big, which is also nice sometimes!\n  This mainly drops support for old Node (use 16 or later), adds modern ES2024\n  support in MDX, supports `await` in MDX (if your framework does too), and\n  removes several deprecated options.\n\n  [Continue reading »][v3]\n
    \n\n## What does MDX do?\n\n
    \n  
    \n    You write markdown with embedded components through JSX:\n\n    ```mdx path=\"example.mdx\"\n    import {Chart} from './snowfall.js'\n    export const year = 2023\n\n    # Last year’s snowfall\n\n    In {year}, the snowfall was above average.\n    It was followed by a warm spring which caused\n    flood conditions in many of the nearby rivers.\n\n    \n    ```\n  
    \n\n  
    \n    It gets compiled to JavaScript that you can use in any framework that\n    supports JSX:\n\n    {/* lint disable no-multiple-toplevel-headings */}\n\n    
    \n      # Last year’s snowfall\n\n      In {year}, the snowfall was above average.\n      It was followed by a warm spring which caused flood conditions in many of\n      the nearby rivers.\n\n      \n    
    \n\n    {/* lint enable no-multiple-toplevel-headings */}\n  
    \n
    \n\nWe made an interactive playground where you can try MDX out and see what it\nturns into.\n[Play »][playground]\n\n## Get started\n\nThere are integrations for most bundlers, frameworks, and editors.\nWhether you build with Docusaurus, Next.js, or Vite.\nYou prefer Rollup, esbuild, or webpack.\nYou’re using React, Preact, or Vue.\n[Get started »][getting-started]\n\n## MDX in short\n\n
    \n  * ❤️ **Powerful**: MDX blends markdown and JSX syntax to fit perfectly in\n    JSX-based projects\n  * 💻 **Everything is a component**: Use existing components in your\n    MDX and import other MDX files as components\n  * 🔧 **Customizable**: Decide which component is rendered for each markdown\n    construct (`{h1: MyHeading}`)\n  * 📚 **Markdown-based**: The simplicity and elegance of markdown remains,\n    you use JSX only when you want to\n  * 🔥 **Blazingly blazing fast**: MDX has no runtime, all compilation occurs\n    during the build stage\n
    \n\n> lol mdx is so good\n>\n> — **@dan\\_abramov**\n\n[getting-started]: /docs/getting-started/\n\n[playground]: /playground/\n\n[v3]: /blog/v3/\n\n[what]: /docs/what-is-mdx/\n"
  },
  {
    "path": "docs/migrating/v1.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'johno', name: 'John Otander'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2019-04-04')\n}\nexport const navExclude = true\n\n\n  **Note**: This is an old migration guide.\n  See [§ Migrating from v1 to v2](/migrating/v2/).\n  The below is kept as is for historical purposes.\n\n\n# Migrating from v0 to v1\n\nUnfortunately, we’ve had to introduce a few breaking changes, so we’ve written a\nmigration guide.\nIn order to ensure as seamless of an upgrade as possible we plan on supporting\nv0 for the next 12 months so there’s not a huge rush to update (though we’d\nlove for you to ASAP) 📆.\n\n## ⚠️ Breaking changes\n\n* [🚨 `@mdx-js/tag` is replaced by `@mdx-js/react` and an `mdx`\n  pragma](#pragma) 🚨\n* [MDXProvider now merges component contexts when nested](#mdxprovider)\n* [React support now requires `>= 16.8` in `@mdx-js/react`](#react)\n\n## Pragma\n\nFor v1 you need to remove `@mdx-js/tag` and replace it with `@mdx-js/react`:\n\n```sh\nyarn remove @mdx-js/tag\nyarn add @mdx-js/react\n```\n\n### What’s different?\n\nThe MDXTag implementation has been removed with a custom pragma implementation\ninspired by\n[Emotion](https://emotion.sh/docs/css-prop#jsx-pragma).\nThis ensures that transpiled JSX is more readable and that JSX blocks use the\nsame component as its markdown counterpart.\nIt also allows MDXProvider to provide global component scope like a `Youtube`\ncomponent.\n\nThe pragma implementation will also cause JSX HTML elements to be rendered with\nthe component mapping passed to MDXProvider.\nSo, the following will result in two identically rendered `h1`s:\n\n```mdx\n# Hello, world!\n\n
    Hello, world!
    \n```\n\n[See the blog post for further reading](/blog/custom-pragma/)\n\n## MDXProvider\n\nThis shouldn’t affect most usecases, however if you’re nesting component\ncontexts and rely on them not being merged you will have to use the functional\nform which allows you to customize the merge.\nBy ignoring outer context components and returning a new component mapping, you\nwill restore the old behavior:\n\n```tsx\n\n   newComponents}>\n    {children}\n  \n\n```\n\n## React\n\nBefore upgrading to `@mdx-js/mdx@1`, update your website/application to\n`react@16.8 react-dom@16.8` and ensure it works as expected.\nThen upgrade to v1.\n"
  },
  {
    "path": "docs/migrating/v2.mdx",
    "content": "import {Note} from '../_component/note.jsx'\n\nexport const info = {\n  author: [\n    {github: 'wooorm', name: 'Titus Wormer'}\n  ],\n  modified: new Date('2025-01-27'),\n  published: new Date('2022-02-01')\n}\nexport const navExclude = true\n\n\n  **Note**: This is an old migration guide.\n  See [§ Migrating from v2 to v3](/migrating/v3/).\n  The below is kept as is for historical purposes.\n\n\n# Migrating from v1 to v2\n\n## Contents\n\n* [ESM](#esm)\n* [Update `@mdx-js/*` packages](#update-mdx-js-packages)\n  * [`@mdx-js/loader`](#mdx-jsloader)\n  * [`@mdx-js/react`, `@mdx-js/preact`, `@mdx-js/vue`](#mdx-jsreact-mdx-jspreact-mdx-jsvue)\n  * [`@mdx-js/mdx`](#mdx-jsmdx)\n  * [`@mdx-js/runtime`](#mdx-jsruntime)\n  * [`remark-mdx`](#remark-mdx)\n  * [`@mdx-js/vue-loader`](#mdx-jsvue-loader)\n  * [`@mdx-js/parcel-plugin-mdx`](#mdx-jsparcel-plugin-mdx)\n  * [Other packages](#other-packages)\n* [Update MDX files](#update-mdx-files)\n  * [JSX](#jsx)\n  * [Expressions](#expressions)\n  * [ESM](#esm-1)\n  * [Markdown](#markdown)\n  * [GFM](#gfm)\n* [Update MDX content](#update-mdx-content)\n\n## ESM\n\nWhen upgrading to version 2, you might run into import problems.\nOur packages are now ESM only.\nYou have to load them with `import foo from 'foo'` instead of\n`const foo = require('foo')`.\nPlease see [¶ ESM in § Troubleshooting MDX][trouble-esm].\n\n## Update `@mdx-js/*` packages\n\nYou need to make changes when upgrading some `mdx-js/*` packages.\nIn this section we will discuss the needed changes for each package.\nIf you’re experiencing problems, please see [§ Troubleshooting MDX][trouble]\nfor common errors and how to solve them.\n\n### `@mdx-js/loader`\n\nTo update our webpack loader `@mdx-js/loader`, please first update to recent\nversions of webpack and React.\nThen make sure ESM is supported.\n[ESM is explained above][esm].\nIf you’re having trouble using ESM in your webpack config, here’s an example\nthat works with our previous `@mdx-js/loader` (`1.6.22`):\n\n
    \n  Expand example of a `webpack.config.js` in ESM\n\n  ```tsx path=\"webpack.config.js\"\n  import {fileURLToPath} from 'node:url'\n  import webpack from 'webpack'\n\n  const config = {\n    context: fileURLToPath(new URL('src/', import.meta.url)),\n    entry: ['./index.js'],\n    mode: 'none',\n    module: {\n      rules: [\n        {\n          test: /\\.mdx?$/,\n          use: [\n            {\n              loader: 'babel-loader',\n              options: {presets: ['@babel/preset-env', '@babel/preset-react']}\n            },\n            {\n              loader: '@mdx-js/loader',\n              /** @type {import('@mdx-js/loader').Options} */\n              options: {}\n            }\n          ]\n        }\n      ]\n    },\n    output: {\n      filename: 'bundle.js',\n      path: fileURLToPath(new URL('dest/', import.meta.url))\n    }\n  };\n\n  export default config\n  ```\n
    \n\nThen install MDX version 2:\n\n```sh\nnpm install @mdx-js/loader @mdx-js/react remark-gfm\n```\n\nYou can update your code as follows:\n\n
    \n  
    \n    Before:\n\n    ```tsx path=\"webpack.config.js\"\n    // …\n    {\n      test: /\\.mdx?$/,\n      use: [\n        {\n          loader: 'babel-loader',\n          options: {\n            presets: [\n              '@babel/preset-env',\n              '@babel/preset-react'\n            ]\n          }\n        },\n        {\n          loader: '@mdx-js/loader',\n          /** @type {import('@mdx-js/loader').Options} */\n          options: {}\n        }\n      ]\n    }\n    // …\n    ```\n  
    \n\n  
    \n    After:\n\n    ```tsx path=\"webpack.config.js\"\n    import remarkGfm from 'remark-gfm'\n\n    // …\n    {\n      test: /\\.mdx?$/,\n      use: [\n        {\n          loader: 'babel-loader',\n          options: {\n            presets: [\n              '@babel/preset-env'\n            ]\n          }\n        },\n        {\n          loader: '@mdx-js/loader',\n          /** @type {import('@mdx-js/loader').Options} */\n          options: {\n            providerImportSource: '@mdx-js/react',\n            remarkPlugins: [remarkGfm]\n          }\n        }\n      ]\n    }\n    // …\n    ```\n  
    \n
    \n\nThe above changes get MDX 2 close to how MDX 1 worked.\nYou can make it simpler:\n\n* [`babel-loader`][babel-loader] is optional.\n  It compiles modern JavaScript to JavaScript your users support.\n  If you don’t need that you can remove it before `@mdx-js/loader`\n* [`remark-gfm`][remark-gfm] is optional.\n  It adds support for autolink literals, footnotes, strikethrough, tables, and\n  task lists.\n  If you don’t want them, you can uninstall it, remove the import, and remove\n  it from `options.remarkPlugins`.\n  More info in [our guide on GFM][guide-gfm]\n* [`@mdx-js/react`][mdx-react] is optional.\n  It adds support for context based components passing.\n  If you don’t need that, you can uninstall it and remove\n  `options.providerImportSource`.\n  More info in [¶ MDX provider in § Using MDX][mdx-provider]\n\n`@mdx-js/loader` now supports Preact and other JSX runtimes through\nconfiguration.\nUsing Preact as an example:\n\n```tsx path=\"webpack.config.js\"\n// …\n{\n  loader: '@mdx-js/loader',\n  /** @type {import('@mdx-js/loader').Options} */\n  options: {\n    jsxImportSource: 'preact',\n    // Optional: either remove the following line or install `@mdx-js/preact`.\n    providerImportSource: '@mdx-js/preact'\n  }\n}\n// …\n```\n\nFor more information, please see [§ API in `@mdx-js/loader`][loader-api].\n\n###### Changes\n\nThe options accepted by the loader changed:\n\n* `renderer` is replaced by `jsxImportSource`, `providerImportSource`, and\n  others options.\n  More info in [§ API in `@mdx-js/mdx`][mdx-api]\n* Other options were undocumented but passed to `@mdx-js/mdx`.\n  See `@mdx-js/mdx` below if needed\n\nFor more information, please see [§ API in `@mdx-js/loader`][loader-api].\n\n### `@mdx-js/react`, `@mdx-js/preact`, `@mdx-js/vue`\n\nTo update our framework integrations, please first update to recent versions of\nReact, Preact, or Vue 3.\nThen make sure ESM is supported.\n[ESM is explained above][esm].\nThen install version 2:\n\n```sh\nnpm install @mdx-js/react # Change `react` to `preact` or `vue` if needed\n```\n\nNote that these packages now only add support for context based components\npassing.\nIf you don’t need that, you can uninstall them.\nMore info in [¶ MDX provider in § Using MDX][mdx-provider].\n\n###### Changes\n\nThe interface of changed slightly:\n\n* The named export `mdx`, which was a `createElement` function, is removed.\n  You can use your framework’s functions instead: `React.createElement`,\n  `h` from `preact`, etc.\n\n### `@mdx-js/mdx`\n\nTo update our core compiler `@mdx-js/mdx`, first make sure ESM is supported.\n[ESM is explained above][esm].\nThen install version 2:\n\n```sh\nnpm install @mdx-js/mdx @mdx-js/react remark-gfm\n```\n\nYou can update your code as follows:\n\n
    \n  
    \n    Before:\n\n    ```tsx path=\"old.js\"\n    import mdx from '@mdx-js/mdx'\n\n    const result = await mdx('# hi')\n\n    console.log(result)\n    ```\n  
    \n\n  
    \n    After:\n\n    ```tsx path=\"new.js\"\n    import {compile} from '@mdx-js/mdx'\n    import remarkGfm from 'remark-gfm'\n\n    const result = await compile('# hi', {\n      providerImportSource: '@mdx-js/react',\n      remarkPlugins: [remarkGfm]\n    })\n\n    console.log(String(result))\n    ```\n  
    \n
    \n\nThe above changes get MDX 2 close to how MDX 1 worked.\nYou can make it simpler:\n\n* [`remark-gfm`][remark-gfm] is optional.\n  It adds support for autolink literals, footnotes, strikethrough, tables, and\n  task lists.\n  If you don’t want them, you can uninstall it, remove the import, and remove\n  it from `options.remarkPlugins`.\n  More info in [our guide on GFM][guide-gfm]\n* [`@mdx-js/react`][mdx-react] is optional.\n  It adds support for context based components passing.\n  If you don’t need that, you can uninstall it and remove\n  `options.providerImportSource`.\n  More info in [¶ MDX provider in § Using MDX][mdx-provider]\n\n`@mdx-js/mdx` now supports Preact and other JSX runtimes through configuration.\nUsing Preact as an example:\n\n```tsx path=\"new-preact.js\"\nimport {compile} from '@mdx-js/mdx'\n\nconst result = await compile('# hi', {jsxImportSource: 'preact'})\n```\n\nFor more information, please see [§ API in `@mdx-js/mdx`][mdx-api]\n\n###### Changes\n\nThe interface of `@mdx-js/mdx` changed:\n\n* The default export is replaced by the named export [`compile`][mdx-compile]\n* The named export `sync` is replaced by [`compileSync`][mdx-compilesync]\n* The named export `createCompiler` is replaced by\n  [`createProcessor`][mdx-createprocessor]\n* The named export `createMdxAstCompiler` is removed, use `remark` with\n  `remark-mdx` instead\n* The return value of `compile`, `compileSync` are now [VFile][]s instead of\n  strings\n* There are new exports [`evaluate`][mdx-evaluate],\n  [`evaluateSync`][mdx-evaluatesync] to eval (compile and run) MDX\n\nOptions in version 1 were undocumented.\nIf you used them:\n\n* `filepath` is replaced by accepting a VFile or compatible object as the\n  first argument `file`\n* `compilers` is replaced by `recmaPlugins`\n* `hastPlugins` is replaced by `rehypePlugins`\n* `mdPlugins` is replaced by `options.remarkPlugins`\n* `skipExport` is removed, [`evaluate`][mdx-evaluate] can do this\n  automatically\n* `wrapExport` is removed, use a custom recma plugin instead\n* There are many new options to support different JSX runtimes, non-React JSX,\n  compile JSX away, source maps, normal markdown, and otherwise change how MDX\n  is compiled\n\nFor more information, please see [§ API in `@mdx-js/mdx`][mdx-api].\n\n### `@mdx-js/runtime`\n\nWe’ve deprecated `@mdx-js/runtime`.\nOur core compiler `@mdx-js/mdx` can now do the same and more.\nTo update, first make sure ESM is supported.\n[ESM is explained above][esm].\nPlease also make sure you are using a recent version of React.\nThen uninstall `@mdx-js/runtime` and install `@mdx-js/mdx` and `@mdx-js/react`:\n\n```sh\nnpm uninstall @mdx-js/runtime\nnpm install @mdx-js/mdx @mdx-js/react\n```\n\nYou can update your code as follows:\n\n
    \n  
    \n    Before:\n\n    ```tsx path=\"old.js\"\n    import MDX from '@mdx-js/runtime'\n\n    const components = {/* … */}\n    const value = '# hi'\n\n    export default function () {\n      return \n        {value}\n      \n    }\n    ```\n  
    \n\n  
    \n    After:\n\n    ```tsx path=\"new.js\"\n    import * as runtime from 'react/jsx-runtime'\n    import * as provider from '@mdx-js/react'\n    import {evaluate} from '@mdx-js/mdx'\n\n    const components = {/* … */}\n    const value = '# hi'\n    const {default: Content} = await evaluate(value, {...provider, ...runtime})\n\n    export default function () {\n      return \n    }\n    ```\n  
    \n
    \n\nThe above changes get MDX 2 close to how MDX 1 worked.\nYou can make it simpler:\n\n* [`@mdx-js/react`][mdx-react] is optional.\n  It adds support for context based components passing.\n  If you don’t need that, you can uninstall it and remove\n  `options.providerImportSource`.\n  More info in [¶ MDX provider in § Using MDX][mdx-provider]\n\n`@mdx-js/mdx` now supports Preact and other JSX runtimes through configuration.\nUsing Emotion as an example:\n\n```tsx path=\"new-emotion.js\"\n// …\nimport * as runtime from '@emotion/react/jsx-runtime'\n// …\n```\n\nFor more information, please see [`evaluate` in `@mdx-js/mdx`][mdx-evaluate].\n\n###### Changes\n\n* The package `@mdx-js/runtime` is replaced by [`evaluate`][mdx-evaluate]\n  from `@mdx-js/mdx`\n* `evaluate` supports any JSX runtime and providers are optional\n* `evaluate` yields an `MDXContent` component just like how importing\n  and MDX file works\n* `evaluate` supports imports and exports inside evaluated MDX\n\nFor more information, please see [`evaluate` in `@mdx-js/mdx`][mdx-evaluate].\n\n### `remark-mdx`\n\nTo update our remark plugin `remark-mdx`, first make sure ESM is supported.\n[ESM is explained above][esm].\nThen install version 2:\n\n```sh\nnpm install remark-mdx\n```\n\nFor more information, please see [§ Use in `remark-mdx`][remark-mdx-use].\n\n### `@mdx-js/vue-loader`\n\nWe’ve deprecated `@mdx-js/vue-loader`.\nOur main loader `@mdx-js/loader` can now do the same and more.\nTo update, first remove `@mdx-js/vue-loader` and upgrade to Vue 3.\nThen, see [¶ Vue in § Getting started](/docs/getting-started/#vue) on how to use\nVue with MDX.\n\n### `@mdx-js/parcel-plugin-mdx`\n\nWe’ve deprecated `@mdx-js/parcel-plugin-mdx`.\nParcel 2 has their own plugin.\nTo update, first remove `@mdx-js/parcel-plugin-mdx` and upgrade to Parcel 2.\nThen, see [¶ Parcel in § Getting started](/docs/getting-started/#parcel) on how\nto use Parcel with MDX.\n\n### Other packages\n\nWe removed several packages doing internal work for us.\nThese packages are:\n\n* `@mdx-js/util`\n  — no longer needed internal helpers\n* `@mdx-js/test-util`\n  — no longer needed test helpers, `evaluate` can do them\n* `gatsby-theme-mdx`\n  — no longer needed website template\n* `remark-mdx-remove-imports`, `babel-plugin-extract-import-names`\n  — no longer needed transforms, our compiler handles imports\n* `remark-mdx-remove-exports`, `babel-plugin-remove-export-keywords`\n  — no longer needed transforms, our compiler handles exports\n* `babel-plugin-html-attributes-to-jsx`\n  — no longer needed transform, something similar is done by\n  [`hast-util-to-estree`](https://github.com/syntax-tree/hast-util-to-estree)\n* `babel-plugin-apply-mdx-type-props`\n  — no longer needed transform due to the new architecture\n* `create-mdx`\n  — no longer needed, we recommend to start your project with whatever other\n  integrations you prefer and *then* add MDX to it\n\n## Update MDX files\n\nNow you’ve updated our packages, you can update your MDX files.\nIn version 2, we improved the syntax of the MDX format.\nWhen upgrading, you’ll likely get errors.\nRead those error messages carefully, as they typically explain what\nhappened where and how to fix it.\nSee [§ Troubleshooting MDX][trouble] for common errors and how to solve them.\n\n### JSX\n\nLet’s kick off with a couple of things that are now possible with JSX in MDX.\nYou don’t need blank lines between JSX and markdown anymore:\n\n```mdx chrome=no\n
    \n# This is a heading now\n
    \n```\n\nYou can now indent your JSX and markdown:\n\n````mdx chrome=no\n
    \n  
    \n    # This is a heading now, not code or plain text\n  
    \n  
    \n    ```js\n    // if you do want code blocks, use fenced code\n    ```\n  
    \n
    \n````\n\nYou can use markdown “inlines” but not “blocks” inside JSX if the text and tags\nare on the same line:\n\n```mdx chrome=no\n
    # this is not a heading but *this* is emphasis
    \n```\n\nText and tags on one line don’t produce blocks so they don’t produce `
    `s\neither.\nOn separate lines, they do:\n\n```mdx chrome=no\n
    \n  This is a `p`.\n
    \n```\n\nWe differentiate using this rule (same line or not).\nNot based on semantics of elements in HTML.\nSo you *can* build incorrect HTML (which you shouldn’t):\n\n```mdx chrome=no\n
    \n  Don’t do this: it’s a `p` in an `h1`\n
    \n\n
    Do this: an `h1` with `code`
    \n```\n\nIt’s not possible to wrap “blocks” if text and tags are on the same line but the\ncorresponding tags are on different lines:\n\n```mdx chrome=no\nWelcome! \n\nThis is home of...\n\n# The Falcons!\n```\n\nThat’s because to parse markdown, we first have to divide it into “blocks”.\nSo in this case two paragraphs and a heading.\nLeaving an opening `a` tag in the first paragraph and a stray closing `a` tag in\nthe heading.\n\nWe also fixed several cases where JSX was not parsed or handled correctly or\neven crashed.\nMore on JSX in MDX is in [¶ JSX in § What is MDX?][what-jsx]\n\n### Expressions\n\nYou can now use expressions in MDX to include JavaScript.\nYou can also use them as an escape hatch if you ever *just* want strings or JSX\nrather than markdown:\n\n```mdx chrome=no\n{\n  
    \n    This just JSX, these *asterisks* have no meaning.\n  
    \n}\n\nThis is just {'`text`'}, not code.\n```\n\nMore on expressions in MDX is in\n[¶ Expressions in § What is MDX?][what-expressions]\n\n### ESM\n\nYou can more easily embed components in MDX because blank lines are allowed:\n\n{/* Note: `language` because theme in VS Code is broken. */}\n\n```mdx chrome=no\nexport function Button(props) {\n  const style = {color: 'red'}\n\n  return