diff --git a/docs/_asset/editor.jsx b/docs/_asset/editor.jsx index 78179b13c..1d97e1adc 100644 --- a/docs/_asset/editor.jsx +++ b/docs/_asset/editor.jsx @@ -93,12 +93,12 @@ const grammars = [ /** @type {Awaited>} */ let starryNight -const body = document.querySelector('.body') +const editor = document.querySelector('#js-editor') -if (body && window.location.pathname === '/playground/') { +if (window.location.pathname === '/playground/' && editor) { const root = document.createElement('div') root.classList.add('playground') - body.after(root) + editor.after(root) init(root) } @@ -204,7 +204,10 @@ function Playground() { if (show === 'result') { /** @type {MDXModule} */ - const mod = await run(String(file), runtime) + const mod = await run(String(file), { + ...runtime, + baseUrl: window.location.href + }) return ( diff --git a/docs/_asset/index.css b/docs/_asset/index.css index 1074d63b1..63b9b5182 100644 --- a/docs/_asset/index.css +++ b/docs/_asset/index.css @@ -331,7 +331,6 @@ hr { table { border-collapse: collapse; border-spacing: 0; - display: block; overflow: auto; width: 100%; font-variant-numeric: lining-nums; @@ -539,6 +538,16 @@ button.success { ); } +.full-bleed { + width: 100vw; + position: relative; + left: 50%; + right: 50%; + margin-left: -50vw; + margin-right: -50vw; + padding-inline: calc(1em + 1ex); +} + /* Note that the `backdrop-filter` itself is applied in light mode. */ @supports (backdrop-filter: blur(1ex)) { .navigation::before { @@ -1224,7 +1233,6 @@ details[open] { grid-template-columns: 49% 49%; min-height: 40rem; gap: calc(1em + 1ex); - margin-inline: calc(1em + 1ex); } .playground-area, diff --git a/docs/_config.js b/docs/_config.js index 94d52e43f..4503ec17f 100644 --- a/docs/_config.js +++ b/docs/_config.js @@ -38,13 +38,11 @@ export const redirect = { '/contributing/index.html': '/community/contribute/', '/editor-plugins/index.html': '/docs/getting-started/#editor', '/editors/index.html': '/docs/getting-started/#editor', - '/getting-started/create-react-app/index.html': - '/docs/getting-started/#create-react-app-cra', + '/getting-started/create-react-app/index.html': '/docs/getting-started/#vite', '/getting-started/gatsby/index.html': '/docs/getting-started/#gatsby', '/getting-started/next/index.html': '/docs/getting-started/#nextjs', '/getting-started/parcel/index.html': '/docs/getting-started/#parcel', - '/getting-started/react-static/index.html': - '/docs/getting-started/#react-static', + '/getting-started/react-static/index.html': '/docs/getting-started/#vite', '/getting-started/table-of-components/index.html': '/table-of-components/', '/getting-started/typescript/index.html': '/docs/getting-started/#types', '/getting-started/webpack/index.html': '/docs/getting-started/#webpack', diff --git a/docs/blog/v1.mdx b/docs/blog/v1.mdx index 8e003a5e3..011df6f42 100644 --- a/docs/blog/v1.mdx +++ b/docs/blog/v1.mdx @@ -77,12 +77,12 @@ for implementing this feature. **Good libraries need great docs**, so we’ve been working on adding content and improving the overall documentation website experience. -* [Search (thanks Algolia)](https://mobile.twitter.com/4lpine/status/1114270174096412672) -* [Guides](/guides/) -* [Automatic deployment via ZEIT](https://zeit.co) -* [Custom Gatsby theme](https://gatsbyjs.org) -* Reorganization of docs for intuitiveness -* Full page rewrites to improve clarity +* [Search (thanks Algolia)](https://mobile.twitter.com/4lpine/status/1114270174096412672) +* [Guides](/guides/) +* [Automatic deployment via ZEIT](https://zeit.co) +* [Custom Gatsby theme](https://gatsbyjs.org) +* Reorganization of docs for intuitiveness +* Full page rewrites to improve clarity Special thanks to [@jxnblk](https://github.com/jxnblks) and [@wooorm](https://github.com/wooorm) for their help improving the docs and @@ -97,12 +97,12 @@ The community has evolved and we’ve come up with newer, better ideas over the last year. We have made sure the impact is small and have written a full migration guide. -* 🚨`@mdx-js/tag` is replaced by `@mdx-js/react` and an `@mdx` pragma - — [migration guide](/migrating/v1#pragma) -* MDXProvider now merges component contexts when nested - — [migration guide](/migrating/v1#mdxprovider) -* React support now requires `>= 16.8` in `@mdx-js/react` - — [migration guide](/migrating/v1#react) +* 🚨`@mdx-js/tag` is replaced by `@mdx-js/react` and an `@mdx` pragma + — [migration guide](/migrating/v1#pragma) +* MDXProvider now merges component contexts when nested + — [migration guide](/migrating/v1#mdxprovider) +* React support now requires `>= 16.8` in `@mdx-js/react` + — [migration guide](/migrating/v1#react) [Read the full v1 migration guide](/migrating/v1) @@ -123,11 +123,11 @@ We’ve also seen projects/products/application we never even imagined. ### Numbers -* **Downloads**: 125,000/week, 2.4M total -* **Stars**: 6,200 -* **Contributors**: 50 -* **Pull requests**: 281 -* **Commits**: 670 +* **Downloads**: 125,000/week, 2.4M total +* **Stars**: 6,200 +* **Contributors**: 50 +* **Pull requests**: 281 +* **Commits**: 670 The contributor growth is one of the most important aspects here as we have numerous community members that are familiar with MDX internals. @@ -138,15 +138,15 @@ against an ever growing team of contributors. ### Ecosystem -* [Prettier](https://prettier.io) -* [Docz](https://docz.site) -* [MDX Deck](https://github.com/jxnblk/mdx-deck) -* [Next.js](https://nextjs.org) -* [Gatsby](https://gatsbyjs.org) -* [AST Explorer](https://astexplorer.net) -* [Vue support (alpha)](/docs/getting-started/#vue) -* [Demoboard](https://frontarm.com/demoboard/) -* [Editors](/docs/getting-started/#editor) +* [Prettier](https://prettier.io) +* [Docz](https://docz.site) +* [MDX Deck](https://github.com/jxnblk/mdx-deck) +* [Next.js](https://nextjs.org) +* [Gatsby](https://gatsbyjs.org) +* [AST Explorer](https://astexplorer.net) +* [Vue support (alpha)](/docs/getting-started/#vue) +* [Demoboard](https://frontarm.com/demoboard/) +* [Editors](/docs/getting-started/#editor) ## 🛣 Roadmap @@ -154,14 +154,14 @@ With v1 released we have a roadmap in place that we’ll continue working toward over the next 6 months or so in addition to bug fixes and parsing issues we might encounter. -* MDXs: [#454](https://github.com/mdx-js/mdx/issues/454) -* Interleaving: [#195](https://github.com/mdx-js/mdx/issues/195) -* Global shortcodes: [#508](https://github.com/mdx-js/mdx/pull/508) -* Stable Vue support: [#238](https://github.com/mdx-js/mdx/issues/238) -* Blocks: MDX WYSIWYG: [blocks/blocks](https://github.com/blocks/blocks) -* MDX playground inspired by AST Explorer: [#220](https://github.com/mdx-js/mdx/issues/220) -* New splash page: [#444](https://github.com/mdx-js/mdx/issues/444) -* Showcase page: [#414](https://github.com/mdx-js/mdx/issues/414) +* MDXs: [#454](https://github.com/mdx-js/mdx/issues/454) +* Interleaving: [#195](https://github.com/mdx-js/mdx/issues/195) +* Global shortcodes: [#508](https://github.com/mdx-js/mdx/pull/508) +* Stable Vue support: [#238](https://github.com/mdx-js/mdx/issues/238) +* Blocks: MDX WYSIWYG: [blocks/blocks](https://github.com/blocks/blocks) +* MDX playground inspired by AST Explorer: [#220](https://github.com/mdx-js/mdx/issues/220) +* New splash page: [#444](https://github.com/mdx-js/mdx/issues/444) +* Showcase page: [#414](https://github.com/mdx-js/mdx/issues/414) ### Vue support @@ -196,11 +196,11 @@ dealing with many sources of content. unified projects are used all over the web, and it would never be possible without financial support from our fine sponsors. -* [ZEIT](https://zeit.co) 🥇 -* [Gatsby](https://gatsbyjs.org) 🥇 -* [Holloway](https://www.holloway.com) 🥉 -* [Backers](https://opencollective.com/unified#budget) 🏆 -* [You?](https://opencollective.com/unified)👤 +* [ZEIT](https://zeit.co) 🥇 +* [Gatsby](https://gatsbyjs.org) 🥇 +* [Holloway](https://www.holloway.com) 🥉 +* [Backers](https://opencollective.com/unified#budget) 🏆 +* [You?](https://opencollective.com/unified)👤 ## 🙏 Thanks diff --git a/docs/blog/v2.mdx b/docs/blog/v2.mdx index d5c573884..b6ecde4cc 100644 --- a/docs/blog/v2.mdx +++ b/docs/blog/v2.mdx @@ -21,17 +21,17 @@ Here are the highlights: {/* more */}
- * 📝 **Improved syntax** makes it easier to use markdown in JSX - * 🧑‍💻 **JavaScript expressions** turn `{2 * Math.PI}` into {2 * Math.PI} - * 🔌 New **esbuild**, **Rollup**, and **Node.js** integrations - * ⚛️ **Any JSX runtime**: React, Preact, Vue, Emotion, you name it, they’re - all supported - * 🌳 **Improved AST** exposes more info in greater detail - * 🏃‍♀️ Compiles at least **25% faster** - * 🚴 Generated code runs twice as fast (**100% faster**) - * 🚄 Bundle size of `@mdx-js/mdx` is more than three times as small - (**250% smaller**) - * 🧵 …and much, so much more + * 📝 **Improved syntax** makes it easier to use markdown in JSX + * 🧑‍💻 **JavaScript expressions** turn `{2 * Math.PI}` into {2 * Math.PI} + * 🔌 New **esbuild**, **Rollup**, and **Node.js** integrations + * ⚛️ **Any JSX runtime**: React, Preact, Vue, Emotion, you name it, they’re + all supported + * 🌳 **Improved AST** exposes more info in greater detail + * 🏃‍♀️ Compiles at least **25% faster** + * 🚴 Generated code runs twice as fast (**100% faster**) + * 🚄 Bundle size of `@mdx-js/mdx` is more than three times as small + (**250% smaller**) + * 🧵 …and much, so much more
It’s been 4 years since this project was announced. @@ -41,13 +41,13 @@ Let’s dive in! ## Contents -* [Improvements to the MDX format](#improvements-to-the-mdx-format) -* [Rollup, esbuild, and other integrations](#rollup-esbuild-and-other-integrations) -* [Architectural improvements](#architectural-improvements) -* [TypeScript](#typescript) -* [Docs & site](#docs--site) -* [Breaking changes](#breaking-changes) -* [Thanks](#thanks) +* [Improvements to the MDX format](#improvements-to-the-mdx-format) +* [Rollup, esbuild, and other integrations](#rollup-esbuild-and-other-integrations) +* [Architectural improvements](#architectural-improvements) +* [TypeScript](#typescript) +* [Docs & site](#docs--site) +* [Breaking changes](#breaking-changes) +* [Thanks](#thanks) ## Improvements to the MDX format diff --git a/docs/community/about.mdx b/docs/community/about.mdx index fc4b24351..1dfb044b4 100644 --- a/docs/community/about.mdx +++ b/docs/community/about.mdx @@ -29,28 +29,28 @@ MDX solves this. There are many languages objectively better than markdown, however, markdown is great because: -* It looks like what it means and is relatively easy to read -* Although images are [confusing][], most stuff is relatively simple to write -* It’s loose and ambiguous: it may not work but you won’t get an error (great - for someone posting a comment to a forum if they forgot an asterisk) +* It looks like what it means and is relatively easy to read +* Although images are [confusing][], most stuff is relatively simple to write +* It’s loose and ambiguous: it may not work but you won’t get an error (great + for someone posting a comment to a forum if they forgot an asterisk) Markdown *does* have a way to extend it, HTML, but that has drawbacks: -* HTML in markdown is naïve, how it’s parsed sometimes doesn’t make sense -* HTML is unsafe by default, so it’s sometimes (partially) unsupported -* HTML and markdown don’t mix well, resulting in confusing rules such as - blank lines or `markdown="1"` attributes -* HTML is coupled with browsers, markdown is useful for other things too +* HTML in markdown is naïve, how it’s parsed sometimes doesn’t make sense +* HTML is unsafe by default, so it’s sometimes (partially) unsupported +* HTML and markdown don’t mix well, resulting in confusing rules such as + blank lines or `markdown="1"` attributes +* HTML is coupled with browsers, markdown is useful for other things too The frontend world has an alternative to HTML: JSX. JSX is great, amongst other things, because: -* It has a relatively familiar syntax (like XML) -* It’s agnostic to semantics and intended for compilers (can have any - domain-specific meaning) -* It’s strict and unambiguous (great if an author forgot a slash somewhere, as - they’ll get an error early, instead of a book going to print with broken - stuff in it) +* It has a relatively familiar syntax (like XML) +* It’s agnostic to semantics and intended for compilers (can have any + domain-specific meaning) +* It’s strict and unambiguous (great if an author forgot a slash somewhere, as + they’ll get an error early, instead of a book going to print with broken + stuff in it) ## Who governs MDX? @@ -104,17 +104,17 @@ The following projects inspired `@mdx-js/*` originally: {/* Note: please keep the original project names intact: */} -* [`jamesknelson/mdxc`](https://github.com/frontarm/mdx-util) -* [`ticky/markdown-component-loader`](https://github.com/ticky/markdown-component-loader) -* [`threepointone/markdown-in-js`](https://github.com/threepointone/markdown-in-js) -* [`fazouane-marouane/remark-jsx`](https://github.com/remarkjs/remark-jsx) -* [`mapbox/remark-react`](https://github.com/remarkjs/remark-react) -* [`rx-ts/eslint-mdx`](https://github.com/mdx-js/eslint-mdx) +* [`jamesknelson/mdxc`](https://github.com/frontarm/mdx-util) +* [`ticky/markdown-component-loader`](https://github.com/ticky/markdown-component-loader) +* [`threepointone/markdown-in-js`](https://github.com/threepointone/markdown-in-js) +* [`fazouane-marouane/remark-jsx`](https://github.com/remarkjs/remark-jsx) +* [`mapbox/remark-react`](https://github.com/remarkjs/remark-react) +* [`rx-ts/eslint-mdx`](https://github.com/mdx-js/eslint-mdx) The following articles inspired `@mdx-js/*` originally: -* [IA Markdown Content Blocks](https://github.com/iainc/Markdown-Content-Blocks) -* [Idyll: Markup language for interactive documents](https://idyll-lang.org) +* [IA Markdown Content Blocks](https://github.com/iainc/Markdown-Content-Blocks) +* [Idyll: Markup language for interactive documents](https://idyll-lang.org) [what]: /docs/what-is-mdx/ diff --git a/docs/community/contribute.mdx b/docs/community/contribute.mdx index 7dfeac6c0..e6a05166e 100644 --- a/docs/community/contribute.mdx +++ b/docs/community/contribute.mdx @@ -4,7 +4,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2022-01-25'), + modified: new Date('2023-10-23'), published: new Date('2018-11-04') } export const navSortSelf = 2 @@ -35,13 +35,7 @@ As a user you’re perfect for helping us improve our docs. Typo corrections, error fixes, better explanations, new examples, etcetera. All MDX docs live in `docs/`. -You can run the docs locally by following those steps: - -* Use Node.js 14 -* Install latest npm (not the one coming with Node.js 14): `npm install -g npm` -* Install repository packages: `npm install` -* Build the docs site: `npm run docs` -* Test the static docs site: `npx serve public` +You can run the docs locally, see [¶ Site][site] below. ### Improve issues @@ -57,30 +51,30 @@ bug or suggest a new feature before creating a pull request. ## Submitting an issue -* The issue tracker is for issues. - Use discussions for support -* Search the issue tracker (including closed issues) before opening a new - issue -* Ensure you’re using the latest version of our packages -* Use a clear and descriptive title -* Include as much information as possible: steps to reproduce the issue, - error message, version, operating system, etcetera -* The more time you put into an issue, the better we will be able to help you -* The best issue report is a [failing test][unit-test] proving it +* The issue tracker is for issues. + Use discussions for support +* Search the issue tracker (including closed issues) before opening a new + issue +* Ensure you’re using the latest version of our packages +* Use a clear and descriptive title +* Include as much information as possible: steps to reproduce the issue, + error message, version, operating system, etcetera +* The more time you put into an issue, the better we will be able to help you +* The best issue report is a [failing test][unit-test] proving it ## Submitting a pull request -* See [¶ Project][project] below for info on how the project is structured, - how to test, and how to build the site -* Non-trivial changes are often best discussed in an issue first, to prevent - you from doing unnecessary work -* For ambitious tasks, you should try to get your work in front of the - community for feedback as soon as possible -* New features should be accompanied by tests and documentation -* Don’t include unrelated changes -* Test before submitting code by running `npm test` -* Write a convincing description of why we should land your pull request: - it’s your job to convince us +* See [¶ Project][project] below for info on how the project is structured, + how to test, and how to build the site +* Non-trivial changes are often best discussed in an issue first, to prevent + you from doing unnecessary work +* For ambitious tasks, you should try to get your work in front of the + community for feedback as soon as possible +* New features should be accompanied by tests and documentation +* Don’t include unrelated changes +* Test before submitting code by running `npm test` +* Write a convincing description of why we should land your pull request: + it’s your job to convince us ## Project @@ -100,42 +94,35 @@ This ensures everything is okay, from code style to unit tests to types. To build the site, first do `npm install`, then do `npm run docs`. This produces the website in `public/`. - - **Important**: the site uses several experimental packages. - They require Node.js 14, and don’t work in earlier or later - versions. - To build the site, please use Node.js 14 (with `nvm`: `nvm use 14`). - - ### Release To release a new version, do: -1. update `version`s of packages with a patch, minor, or major (make sure to - update dependency ranges on monorepo packages when needed): - ```sh - npm version minor --workspaces --no-git-tag-version - ``` -2. commit and tag using the version (without `v`) as the message: - ```sh - git commit --all --message 1.2.3 && git tag 1.2.3 && git push && git push --tags - ``` -3. release to the npm registry: - ```sh - npm publish --workspaces - ``` -4. add a changelog entry for the release on GitHub: - ```sh - open https://github.com/mdx-js/mdx/releases - ``` +1. update `version`s of packages with a patch, minor, or major (make sure to + update dependency ranges on monorepo packages when needed): + ```sh + npm version minor --workspaces --no-git-tag-version + ``` +2. commit and tag using the version (without `v`) as the message: + ```sh + git commit --all --message 1.2.3 && git tag 1.2.3 && git push && git push --tags + ``` +3. release to the npm registry: + ```sh + npm publish --workspaces + ``` +4. add a changelog entry for the release on GitHub: + ```sh + open https://github.com/mdx-js/mdx/releases + ``` ## Resources -* [Good first issues in the MDX repository](https://github.com/mdx-js/mdx/labels/good%20first%20issue%20👋) -* [How to contribute to open source](https://opensource.guide/how-to-contribute/) -* [Making your first contribution](https://medium.com/@vadimdemedes/making-your-first-contribution-de6576ddb190) -* [Using pull requests](https://help.github.com/articles/about-pull-requests/) -* [GitHub help](https://help.github.com) +* [Good first issues in the MDX repository](https://github.com/mdx-js/mdx/labels/good%20first%20issue%20👋) +* [How to contribute to open source](https://opensource.guide/how-to-contribute/) +* [Making your first contribution](https://medium.com/@vadimdemedes/making-your-first-contribution-de6576ddb190) +* [Using pull requests](https://help.github.com/articles/about-pull-requests/) +* [GitHub help](https://help.github.com) [coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md @@ -146,3 +133,5 @@ To release a new version, do: [sponsor]: /community/sponsor/ [project]: #project + +[site]: #site diff --git a/docs/community/projects.mdx b/docs/community/projects.mdx index 028d0e9af..dd8707971 100644 --- a/docs/community/projects.mdx +++ b/docs/community/projects.mdx @@ -22,31 +22,31 @@ This page lists community projects using MDX. ## Apps -* [demoboard][]: The simplest editor alive +* [demoboard][]: The simplest editor alive ## Libraries -* [ok-mdx][]: Browser-based MDX editor -* [docz][]: Documentation framework -* [mdx-deck][]: MDX-based presentation decks -* [mdx-docs][]: Next-based documentation framework -* [mdx-paper][]: MDX-based research articles -* [spectacle-boilerplate-mdx][]: Boilerplate that facilitates using MDX with - Spectacle -* [Charge][]: An opinionated, zero-config static site generator -* [MDNEXT][]: An ecosystem of tools to get your NextJS + MDX projects blasting - off +* [ok-mdx][]: Browser-based MDX editor +* [docz][]: Documentation framework +* [mdx-deck][]: MDX-based presentation decks +* [mdx-docs][]: Next-based documentation framework +* [mdx-paper][]: MDX-based research articles +* [spectacle-boilerplate-mdx][]: Boilerplate that facilitates using MDX with + Spectacle +* [Charge][]: An opinionated, zero-config static site generator +* [MDNEXT][]: An ecosystem of tools to get your NextJS + MDX projects blasting + off ## Sites -* This website! -* [Prisma][] -* [Max Stoiber’s Blog][mxstbr] +* This website! +* [Prisma][] +* [Max Stoiber’s Blog][mxstbr] ## Other related links -* [awesome-mdx][] -* [MDX: content for kings and princesses][mdx-fairy-tale] +* [awesome-mdx][] +* [MDX: content for kings and princesses][mdx-fairy-tale] [demoboard]: https://frontarm.com/demoboard diff --git a/docs/community/sponsor.mdx b/docs/community/sponsor.mdx index e9f53b2c2..d9d19214c 100644 --- a/docs/community/sponsor.mdx +++ b/docs/community/sponsor.mdx @@ -2,7 +2,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2022-02-01'), + modified: new Date('2023-05-17'), published: new Date('2021-10-06'), } export const navSortSelf = 3 @@ -24,30 +24,30 @@ as [micromark][]. { - - - - - - - - - - + + +
+ Vercel

 + Motif

 + HashiCorp

 + GitBook

 + Gatsby
+ Netlify

{/* OC has a sharper image */} @@ -80,7 +80,7 @@ as [micromark][].
+
You?

diff --git a/docs/community/support.mdx b/docs/community/support.mdx index 0e6099f45..add450063 100644 --- a/docs/community/support.mdx +++ b/docs/community/support.mdx @@ -32,19 +32,19 @@ Spend time framing questions and add links and resources. Spending the extra time up front can help save everyone time in the long run. Here are some tips: -* Read through [§ Getting started][getting-started] -* [Talk to a duck!][rubberduck] -* Don’t fall for the [XY problem][xy] -* Search to find out if a similar question has been asked -* Try to define what you need help with: - * Is there something in particular you want to do? - * What problem are you encountering and what steps have you taken to try - and fix it? - * Is there a concept you don’t understand? -* Provide sample code, such as a [CodeSandbox][cs] or video, if possible -* Screenshots can help, but if there’s important text such as code or error - messages in them, please also provide those as text -* The more time you put into asking your question, the better we can help you +* Read through [§ Getting started][getting-started] +* [Talk to a duck!][rubberduck] +* Don’t fall for the [XY problem][xy] +* Search to find out if a similar question has been asked +* Try to define what you need help with: + * Is there something in particular you want to do? + * What problem are you encountering and what steps have you taken to try + and fix it? + * Is there a concept you don’t understand? +* Provide sample code, such as a [CodeSandbox][cs] or video, if possible +* Screenshots can help, but if there’s important text such as code or error + messages in them, please also provide those as text +* The more time you put into asking your question, the better we can help you [coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md diff --git a/docs/docs/extending-mdx.mdx b/docs/docs/extending-mdx.mdx index 5fd072516..14a53e6fb 100644 --- a/docs/docs/extending-mdx.mdx +++ b/docs/docs/extending-mdx.mdx @@ -18,22 +18,22 @@ See [§ Getting started][start] for how to integrate MDX into your project. ## Contents -* [Components & plugins](#components--plugins) - * [List of components](#list-of-components) - * [List of plugins](#list-of-plugins) -* [Using plugins](#using-plugins) -* [Creating plugins](#creating-plugins) +* [Components & plugins](#components--plugins) + * [List of components](#list-of-components) + * [List of plugins](#list-of-plugins) +* [Using plugins](#using-plugins) +* [Creating plugins](#creating-plugins) ## Components & plugins There are three extension points when using `@mdx-js/mdx` or one of its integrations: -* Options passed to the compiler (see [¶ API in `@mdx-js/mdx`][api]) -* Plugins that hook into several stages of compilation (see [remark - plugins][remark-plugins], [rehype plugins][rehype-plugins], and the new - recma plugins) -* Components passed, defined, or imported at runtime (see [§ Using MDX][use]) +* Options passed to the compiler (see [¶ API in `@mdx-js/mdx`][api]) +* Plugins that hook into several stages of compilation (see [remark + plugins][remark-plugins], [rehype plugins][rehype-plugins], and the new + recma plugins) +* Components passed, defined, or imported at runtime (see [§ Using MDX][use]) Most of the time, these components and plugins are not coupled to MDX. For example, if you’re using React, then you can use @@ -45,11 +45,11 @@ We’re compiling those here on this page. ### List of components -* [`PaulieScanlon/mdx-embed`](https://github.com/PaulieScanlon/mdx-embed) - — React components for embedding 3rd party content, integrates w/ - MDX provider -* [`system-ui/theme-ui`](https://github.com/system-ui/theme-ui) - — React components for building consistent apps, integrates w/ MDX provider +* [`PaulieScanlon/mdx-embed`](https://github.com/PaulieScanlon/mdx-embed) + — React components for embedding 3rd party content, integrates w/ + MDX provider +* [`system-ui/theme-ui`](https://github.com/system-ui/theme-ui) + — React components for building consistent apps, integrates w/ MDX provider {/* please use alpha sorting on **project** name! @@ -69,24 +69,24 @@ You can use this template: See also the [list of remark plugins][remark-plugins] and [list of rehype plugins][rehype-plugins]. -* [`domdomegg/recma-mdx-displayname`](https://github.com/domdomegg/recma-mdx-displayname) - — add a `displayName` to `MDXContent` components, to enable switching - on them in production -* [`remcohaszing/recma-nextjs-static-props`](https://github.com/remcohaszing/recma-nextjs-static-props) - — generate [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching/get-static-props) - exposing top level identifiers in Next.js -* [`remcohaszing/rehype-mdx-title`](https://github.com/remcohaszing/rehype-mdx-title) - — expose the page title as a string -* [`remcohaszing/remark-mdx-code-meta`](https://github.com/remcohaszing/remark-mdx-code-meta) - — interpret the code `meta` field as JSX props -* [`remcohaszing/remark-mdx-images`](https://github.com/remcohaszing/remark-mdx-images) - — change image sources to JavaScript imports -* [`remcohaszing/remark-mdx-frontmatter`](https://github.com/remcohaszing/remark-mdx-frontmatter) - — change frontmatter (YAML) metadata to exports -* [`goodproblems/remark-mdx-math-enhanced`](https://github.com/goodproblems/remark-mdx-math-enhanced) - — enhance math with JavaScript inside it -* [`pangelani/remark-mdx-chartjs`](https://github.com/pangelani/remark-mdx-chartjs) - — replace fenced code blocks with charts using [`react-chartjs-2`](https://react-chartjs-2.js.org/). +* [`domdomegg/recma-mdx-displayname`](https://github.com/domdomegg/recma-mdx-displayname) + — add a `displayName` to `MDXContent` components, to enable switching + on them in production +* [`remcohaszing/recma-nextjs-static-props`](https://github.com/remcohaszing/recma-nextjs-static-props) + — generate [`getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching/get-static-props) + exposing top level identifiers in Next.js +* [`remcohaszing/rehype-mdx-title`](https://github.com/remcohaszing/rehype-mdx-title) + — expose the page title as a string +* [`pangelani/remark-mdx-chartjs`](https://github.com/pangelani/remark-mdx-chartjs) + — replace fenced code blocks with charts using [`react-chartjs-2`](https://react-chartjs-2.js.org/). +* [`remcohaszing/remark-mdx-code-meta`](https://github.com/remcohaszing/remark-mdx-code-meta) + — interpret the code `meta` field as JSX props +* [`remcohaszing/remark-mdx-frontmatter`](https://github.com/remcohaszing/remark-mdx-frontmatter) + — change frontmatter (YAML) metadata to exports +* [`remcohaszing/remark-mdx-images`](https://github.com/remcohaszing/remark-mdx-images) + — change image sources to JavaScript imports +* [`goodproblems/remark-mdx-math-enhanced`](https://github.com/goodproblems/remark-mdx-math-enhanced) + — enhance math with JavaScript inside it {/* please use alpha sorting on **project** name! diff --git a/docs/docs/getting-started.mdx b/docs/docs/getting-started.mdx index 6a5fdee27..732879b9d 100644 --- a/docs/docs/getting-started.mdx +++ b/docs/docs/getting-started.mdx @@ -4,7 +4,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2022-12-14'), + modified: new Date('2023-10-24'), published: new Date('2021-10-05') } export const navSortSelf = 2 @@ -13,40 +13,45 @@ export const navSortSelf = 2 This article explains how to integrate MDX into your project. It shows how to use MDX with your bundler and JSX runtime of choice. {/* more */} -To understand how the MDX format works, we recommend that you start with -[§ What is MDX][what]. +To understand how the MDX format works, +we recommend that you start with [§ What is MDX][what]. See [§ Using MDX][use] when you’re all set up and ready to use MDX. ## Contents -* [Prerequisites](#prerequisites) -* [Quick start](#quick-start) - * [Bundler](#bundler) - * [JSX](#jsx) - * [Editor](#editor) - * [Types](#types) - * [Security](#security) -* [Integrations](#integrations) - * [Bundlers](#bundlers) - * [Build systems](#build-systems) - * [Compilers](#compilers) - * [Site generators](#site-generators) - * [JSX runtimes](#jsx-runtimes) - * [JavaScript engines](#javascript-engines) -* [Further reading](#further-reading) +* [Prerequisites](#prerequisites) +* [Quick start](#quick-start) + * [Bundler](#bundler) + * [JSX](#jsx) + * [Editor](#editor) + * [Types](#types) + * [Security](#security) +* [Integrations](#integrations) + * [Bundlers](#bundlers) + * [Build systems](#build-systems) + * [Compilers](#compilers) + * [Site generators](#site-generators) + * [JSX runtimes](#jsx-runtimes) + * [JavaScript engines](#javascript-engines) +* [Further reading](#further-reading) ## Prerequisites -MDX relies on JSX, so it’s required that your project supports JSX as well. +MDX relies on JSX, +so it’s required that your project supports JSX as well. Any JSX runtime (React, Preact, Vue, etc.) will do. Note that we do compile JSX to JavaScript for you so you don’t have to set that up. All `@mdx-js/*` packages are written in modern JavaScript. -A [Node.js](https://nodejs.org) version of 12.20, 14.14, 16.0, or later is -required to use them. -Our packages are also [ESM only][esm], so they have to be `import`ed instead of -`require`d. +A [Node.js][node-js] version of 16.0 or later is needed to use them. +Our packages are also [ESM only][github-gist-esm], +so they have to be `import`ed instead of `require`d. + + + **Note**: Using Rust instead of Node.js? + Use [`mdxjs-rs`][mdxjs-rs]! + ## Quick start @@ -57,112 +62,90 @@ MDX is a language that’s compiled to JavaScript. The easiest way to get started is to use an integration for your bundler if you have one: -* If you’re using **esbuild**, - install and configure [`@mdx-js/esbuild`][mdx-esbuild] -* If you’re using **Rollup** - (or Vite or WMR, which use it), - install and configure [`@mdx-js/rollup`][mdx-rollup] -* If you’re using **webpack** - (or Create React App (CRA), Next.js, or Vue CLI, which use it), - install and configure [`@mdx-js/loader`][mdx-loader] - -You can also use MDX if you’re not using a bundler: - -* If you want to import MDX files in **Node.js**, you can - install and configure [`@mdx-js/node-loader`][mdx-node-loader] -* Otherwise, you can install and use the core compiler - [`@mdx-js/mdx`][mdx-mdx] to manually compile MDX files -* Finally, it’s also possible to evaluate (compile *and run*) MDX anywhere, - with [`evaluate` from `@mdx-js/mdx`][evaluate]. - -For more info on the aforementioned tools, please see their dedicated sections: -[¶ Create React App (CRA)][cra], [¶ esbuild][esbuild], -[¶ Next.js][next], [¶ Node.js][node], -[¶ Rollup][rollup], [¶ Vite][vite], [¶ Vue CLI][vue-cli], -[¶ WMR][wmr], [¶ webpack][webpack]. - -There are also community driven integrations. -As we’ve just hit a major milestone with v2, they might be out of date with our -v2 docs though. -See: -[¶ Docusaurus][docusaurus], -[¶ Gatsby][gatsby], -[¶ Parcel][parcel], -[¶ Razzle][razzle], -[¶ React Static][react-static], and -[¶ Snowpack][snowpack]. - -{/* - old link as used on gatsby’s website currently: - -*/} - - +* if you use **esbuild**, + install and configure [`@mdx-js/esbuild`][mdx-esbuild] +* if you use **Rollup** (or Vite), + install and configure [`@mdx-js/rollup`][mdx-rollup] +* if you use **webpack** (or Next.js), + install and configure [`@mdx-js/loader`][mdx-loader] + +You can also use MDX without bundlers: + +* you can import MDX files in **Node.js** with + [`@mdx-js/node-loader`][mdx-node-loader] +* you can use our core compiler [`@mdx-js/mdx`][mdx-mdx] to compile MDX files +* you can use our core compiler [`@mdx-js/mdx`][mdx-mdx] to + [evaluate][api-evaluate] (compile *and run*) MDX files + +For more info on these tools, +see their dedicated sections: +[¶ Next.js][site-generator-next], +[¶ Node.js][js-engine-node], +[¶ Rollup][bundler-rollup], +[¶ Vite][build-system-vite], +[¶ esbuild][bundler-esbuild], and +[¶ webpack][bundler-webpack]. ### JSX -Now you’ve set up an integration or `@mdx-js/mdx` itself, it’s time to configure -your JSX runtime. - -* If you’re using **React**, - you don’t need to do anything. - Optionally install and configure [`@mdx-js/react`][mdx-react] -* If you’re using **Preact**, - set [`jsxImportSource` in `ProcessorOptions`][processor-options] to - `'preact'`. - Optionally install and configure [`@mdx-js/preact`][mdx-preact] -* If you’re using **Svelte**, - install [`svelte-jsx`][svelte-jsx]. - Set [`jsxImportSource` in `ProcessorOptions`][processor-options] to - `'svelte-jsx'`. -* If you’re using **Vue 3**, - set [`jsx` in `ProcessorOptions`][processor-options] to `true`. - Then use Babel alongside your MDX integration (which is possible with - webpack and Rollup but not esbuild) and configure it to use - [`@vue/babel-plugin-jsx`](https://github.com/vuejs/jsx-next/tree/dev/packages/babel-plugin-jsx). - Optionally install and configure [`@mdx-js/vue`][mdx-vue] -* If you’re using **Emotion**, - set [`jsxImportSource` in `ProcessorOptions`][processor-options] to - `'@emotion/react'` -* If you’re using **Theme UI**, - install and configure [`@mdx-js/react`][mdx-react]. - Then wrap your MDX content in a `` -* If you’re using **Solid**, - set [`jsxImportSource` in `ProcessorOptions`][processor-options] to - `'solid-js/h'` +Now you’ve set up an integration or `@mdx-js/mdx` itself, +it’s time to configure your JSX runtime. + +* if you use **React**, + you don’t need to do anything; + optionally install and configure [`@mdx-js/react`][mdx-react] +* if you use **Preact**, + set [`jsxImportSource` in `ProcessorOptions`][api-processor-options] to + `'preact'`; + optionally install and configure [`@mdx-js/preact`][mdx-preact] +* if you use **Svelte**, + install [`svelte-jsx`][svelte-jsx], + and set [`jsxImportSource` in `ProcessorOptions`][api-processor-options] to + `'svelte-jsx'` +* if you use **Vue**, + set [`jsxImportSource` in `ProcessorOptions`][api-processor-options] to + `'vue'`; + optionally install and configure [`@mdx-js/vue`][mdx-vue] +* if you use **Solid**, + set [`jsxImportSource` in `ProcessorOptions`][api-processor-options] to + `'solid-js/h'` +* if you use **Emotion**, + set [`jsxImportSource` in `ProcessorOptions`][api-processor-options] to + `'@emotion/react'` +* if you use **Theme UI**, + install and configure [`@mdx-js/react`][mdx-react], + then wrap your MDX content in a `` Other JSX runtimes are supported by setting -[`jsxImportSource` in `ProcessorOptions`][processor-options]. -See also the different options there on how to use the classic JSX runtime -and how to define a `pragma` and `pragmaFrag` for it. - -For more info on the aforementioned tools, please see their dedicated sections: -[¶ Emotion][emotion], -[¶ Preact][preact], -[¶ React][react], -[¶ Solid][solid], -[¶ Svelte][svelte], -[¶ Theme UI][themeui], or -[¶ Vue][vue]. +[`jsxImportSource` in `ProcessorOptions`][api-processor-options]. + +For more info on these tools, +see their dedicated sections: +[¶ Emotion][jsx-runtime-emotion], +[¶ Preact][jsx-runtime-preact], +[¶ React][jsx-runtime-react], +[¶ Solid][jsx-runtime-solid], +[¶ Svelte][jsx-runtime-svelte], +[¶ Theme UI][jsx-runtime-theme-ui], and +[¶ Vue][jsx-runtime-vue]. ### Editor -Once everything is set up in your project, you can enhance the experience by -adding support for MDX in your editor: +You can enhance the experience of using MDX by adding support of it to your +editor: -* With **VS Code**, - try [`mdx-js/vscode-mdx`](https://github.com/mdx-js/vscode-mdx) - and/or [`xyc/vscode-mdx-preview`](https://github.com/xyc/vscode-mdx-preview) -* With **Vim**, - try [`jxnblk/vim-mdx-js`](https://github.com/jxnblk/vim-mdx-js) -* With **Sublime Text**, - try [`jonsuh/mdx-sublime`](https://github.com/jonsuh/mdx-sublime) -* With **JetBrains IntelliJ/WebStorm**, - try [`JetBrains/mdx-intellij-plugin`](https://github.com/JetBrains/intellij-plugins/tree/master/mdx) +* if you use **VS Code**, + try [`mdx-js/vscode-mdx`][vscode-mdx] +* if you use **Vim**, + try [`jxnblk/vim-mdx-js`][vim-mdx-js] +* if you use **Sublime Text**, + try [`jonsuh/mdx-sublime`][mdx-sublime] +* if you use **JetBrains IntelliJ/WebStorm**, + try [`JetBrains/mdx-intellij-plugin`][mdx-intellij-plugin] - - **Note**: we’re looking for help with emacs and others! - +The syntax highlighting that powers our VS Code extension and that is used +to highlight code blocks on GitHub is maintained at +[`wooorm/markdown-tm-language`][markdown-tm-language]. ### Types @@ -182,19 +165,17 @@ adding support for MDX in your editor: ``` -All our APIs are fully typed with -[TypeScript](https://www.typescriptlang.org). - -To enable types for imported `.mdx`, `.md`, etcetera files, you should make sure -the TypeScript `JSX` namespace is typed. -This is done by installing and using the types of your framework, such as -[`@types/react`](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/react). -Then you can install and use -[`@types/mdx`](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/mdx), -which adds types to import statements of supported files. +Our packages are typed with [TypeScript][]. +For types to work, +the `JSX` namespace must be typed. +This is done by installing and using the types of your framework, +such as [`@types/react`][definitely-typed-react]. -You can also import several types about the API of MDX files from `@types/mdx`. -For example: +To enable types for imported `.mdx`, `.md`, etc., +install and use [`@types/mdx`][definitely-typed-mdx]. +This package also exports several useful types, +such as `MDXComponents` which represents the `components` prop. +You can import them like so: ```tsx path="example.ts" import type {MDXComponents} from 'mdx/types.js' @@ -202,16 +183,22 @@ import type {MDXComponents} from 'mdx/types.js' ### Security -Please note that MDX is a programming language. -If you trust your authors, that’s fine. -But be extremely careful with user content and don’t let random people from the -internet write MDX. -If you do, you might want to look into using ` ``` diff --git a/docs/guides/frontmatter.mdx b/docs/guides/frontmatter.mdx index 178661a1f..825489c45 100644 --- a/docs/guides/frontmatter.mdx +++ b/docs/guides/frontmatter.mdx @@ -2,7 +2,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2022-12-14'), + modified: new Date('2023-10-23'), published: new Date('2021-10-06') } export const navSortSelf = 2 @@ -17,7 +17,7 @@ MDX comes with a powerful and dynamic alternative to frontmatter, namely ESM (`import`/`export`). These exports: -```mdx path="post.mdx" +```mdx path="example.mdx" export const name = 'World' export const title = 'Hi, ' + name + '!' @@ -27,7 +27,7 @@ export const title = 'Hi, ' + name + '!' Can be used like so: ```tsx path="example.js" -import * as Post from './post.mdx' // Assumes an integration is used to compile MDX -> JS. +import * as Post from './example.mdx' // Assumes an integration is used to compile MDX -> JS. console.log(Post.title) // Prints 'Hi, World!' ``` @@ -36,7 +36,7 @@ You might prefer frontmatter though, as it lets you define data that can be extracted from the file system *before* compiling. Say our MDX with frontmatter looked like this: -```mdx path="post.mdx" +```mdx path="example.mdx" --- title: Hi, World! --- @@ -47,11 +47,13 @@ title: Hi, World! Then without compiling or evaluating the metadata can be accessed like so: ```tsx path="example.js" -import fs from 'node:fs/promises' -import yaml from 'js-yaml' +import {read} from 'to-vfile' +import {matter} from 'vfile-matter' + +const file = await read('example.mdx') +matter(file) -console.log(yaml.loadAll(await fs.readFile('post.mdx'))[0]) -// Prints `{title: 'Hi, World!'}` +console.log(file.data.matter) ``` Our compiler, `@mdx-js/mdx`, doesn’t understand YAML frontmatter by default but @@ -60,23 +62,23 @@ it can be enabled by using a remark plugin, ```tsx path="example.js" import fs from 'node:fs/promises' -import remarkFrontmatter from 'remark-frontmatter' import {compile} from '@mdx-js/mdx' +import remarkFrontmatter from 'remark-frontmatter' + +const file = await compile(await fs.readFile('example.mdx'), { + remarkPlugins: [remarkFrontmatter] +}) -console.log( - await compile(await fs.readFile('post.mdx'), { - remarkPlugins: [remarkFrontmatter] - }) -) +console.log(file) ``` Now it “works”. -The frontmatter is ignored. +The frontmatter is not rendered as if it was markdown. But the data embedded in the frontmatter isn’t available from *inside* the MDX. What if we wanted that too? Like so: -```mdx path="post.mdx" +```mdx path="example.mdx" --- title: Hi, World! --- @@ -87,7 +89,7 @@ title: Hi, World! That’s exactly what the remark plugin [`remark-mdx-frontmatter`][remark-mdx-frontmatter] does. -remark plugins can be passed as +That plugin, like all remark plugins, can be passed as [`remarkPlugins` in `ProcessorOptions`][processor-options]. More info on plugins is available in [§ Extending MDX][extend] diff --git a/docs/guides/gfm.mdx b/docs/guides/gfm.mdx index 40d6e4bdc..d30a91782 100644 --- a/docs/guides/gfm.mdx +++ b/docs/guides/gfm.mdx @@ -2,7 +2,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2022-12-14'), + modified: new Date('2023-10-23'), published: new Date('2021-10-06') } export const navSortSelf = 1 @@ -15,7 +15,7 @@ MDX supports standard markdown syntax ([CommonMark][]). That means [GitHub flavored markdown (GFM)][gfm] extensions are not supported by default. They can be enabled by using a remark plugin: [`remark-gfm`][remark-gfm]. -Such plugins can be passed in [`remarkPlugins` in +That plugin, like all remark plugins, can be passed in [`remarkPlugins` in `ProcessorOptions`][processor-options]. More info on plugins is available in [§ Extending MDX][extend] @@ -71,12 +71,24 @@ console.log(

GFM

Autolink literals

- www.example.com, - https://example.com, and + www.example.com,{' '} + https://example.com, and{' '} contact@example.com.

Footnote

-

A note1

+

+ A note + + + 1 + + +

Strikethrough

one or two tildes. @@ -86,9 +98,9 @@ console.log(

abcdbcd
@@ -98,19 +110,29 @@ console.log( to do
  • - done + + done
    • -
    -

    Footnotes

    -
      -
    1. -

      - Big note. - ↩ -

      -
      2. -
    +
    +

    + Footnotes +

    +
      +
    1. +

      + Big note.{' '} + + ↩ + +

      +
      2. +
    ``` diff --git a/docs/guides/index.mdx b/docs/guides/index.mdx index 45609fac4..e4ee97ede 100644 --- a/docs/guides/index.mdx +++ b/docs/guides/index.mdx @@ -3,7 +3,7 @@ import {NavGroup} from '../_component/nav.jsx' export const info = { author: [{name: 'MDX Contributors'}], - modified: new Date('2021-11-01'), + modified: new Date('2023-10-23'), published: new Date('2021-11-01') } export const navSortSelf = 2 @@ -12,6 +12,7 @@ export const navSortSelf = 2 These guides explain how to accomplish several common use cases and patterns around MDX. + { (function () { /** diff --git a/docs/guides/math.mdx b/docs/guides/math.mdx index 1d6678ba7..bc3b05502 100644 --- a/docs/guides/math.mdx +++ b/docs/guides/math.mdx @@ -4,7 +4,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2023-10-09'), + modified: new Date('2023-10-23'), published: new Date('2021-10-06') } export const navSortSelf = 3 @@ -18,8 +18,8 @@ Math can be enabled by using a remark plugin: [`remark-math`][remark-math], combined with a rehype plugin: either [`rehype-katex`][rehype-katex] (KaTeX) or [`rehype-mathjax`][rehype-mathjax] (MathJax). -Plugins can be passed in -[`rehypePlugins` and `remarkPlugins` in `ProcessorOptions`][processor-options]. +Like other remark and rehype plugins, they can be passed in [`remarkPlugins` +and `rehypePlugins`, respectively, in `ProcessorOptions`][processor-options]. More info on plugins is available in [§ Extending MDX][extend] Say we have an MDX file like this: @@ -52,12 +52,12 @@ console.log( ```tsx path="output.jsx" <>

    - - - - … - - + + + … + +

    @@ -75,6 +75,8 @@ console.log( ``` To get the latest link to the stylesheet, go to [`katex docs`][katex docs]. + + {/* to do: once in a while, get the latest. */} diff --git a/docs/guides/mdx-on-demand.mdx b/docs/guides/mdx-on-demand.mdx index f4522c88d..c435c5599 100644 --- a/docs/guides/mdx-on-demand.mdx +++ b/docs/guides/mdx-on-demand.mdx @@ -4,7 +4,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2021-11-14'), + modified: new Date('2023-10-23'), published: new Date('2021-11-13') } export const navSortSelf = 6 @@ -19,8 +19,8 @@ Using that it’s possible to for example do most of the work on demand on the server instead of at build time, then pass the resulting data to clients, where they finally use it. -This is similar to what [`mdx-bundler`][mdx-bundler] and -[`next-mdx-remote`][next-mdx-remote] also do, but they add more features. +This is similar to what people sometimes use [`mdx-bundler`][mdx-bundler] or +[`next-mdx-remote`][next-mdx-remote] for, but MDX also supports it. ## Quick example @@ -40,12 +40,11 @@ On the client: ```tsx path="client.js" import {run} from '@mdx-js/mdx' -import * as runtime from 'react/jsx-runtime' // Production. -// import * as runtime from 'react/jsx-dev-runtime' // Development. +import * as runtime from 'react/jsx-runtime' const code = '' // To do: get `code` from server somehow. -const {default: Content} = await run(code, runtime) +const {default: Content} = await run(code, {...runtime, baseUrl: import.meta.url}) ``` `Content` is now an `MDXContent` component that you can use like normal in your @@ -68,10 +67,9 @@ Some frameworks let you write the server and client code in one file, such as Next. ```tsx path="pages/hello.js" -import {Fragment, useEffect, useState} from 'react' -import * as runtime from 'react/jsx-runtime' // Production. -// import * as runtime from 'react/jsx-dev-runtime' // Development. import {compile, run} from '@mdx-js/mdx' +import {Fragment, useEffect, useState} from 'react' +import * as runtime from 'react/jsx-runtime' export default function Page({code}) { const [mdxModule, setMdxModule] = useState() @@ -79,7 +77,7 @@ export default function Page({code}) { useEffect(function () { ;(async function () { - setMdxModule(await run(code, runtime)) + setMdxModule(await run(code, {...runtime, baseUrl: import.meta.url})) })() }, [code]) diff --git a/docs/guides/syntax-highlighting.mdx b/docs/guides/syntax-highlighting.mdx index 7aee74467..70caeaac9 100644 --- a/docs/guides/syntax-highlighting.mdx +++ b/docs/guides/syntax-highlighting.mdx @@ -4,7 +4,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2022-08-27'), + modified: new Date('2023-10-23'), published: new Date('2021-10-06') } export const navSortSelf = 4 @@ -33,8 +33,8 @@ Use either [`rehype-highlight`][rehype-highlight] (Prism) by doing something like this: ```tsx path="example.js" -import rehypeHighlight from 'rehype-highlight' import {compile} from '@mdx-js/mdx' +import rehypeHighlight from 'rehype-highlight' const code = `~~~js console.log(1) @@ -52,7 +52,8 @@ console.log( <> 
           
-        console.log(
+        console.
+        log(
         1)
    @@ -66,15 +67,19 @@ console.log( For example, to get GitHub Dark from cdnjs: ```html - + ``` + {/* to do: once in a while, get the latest: */} + If you chose `@mapbox/rehype-prism`, include something like this instead to get Prism Dark: ```html - + ``` + + {/* to do: once in a while, get the latest: */}     ## Syntax highlighting at run time diff --git a/docs/index.mdx b/docs/index.mdx index 566ec0ffc..c8612998a 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -3,19 +3,24 @@ import {Chart} from './_component/snowfall.jsx' export {Home as default} from './_component/home.jsx' export const info = { author: [ - {github: 'johno', name: 'John Otander', twitter: '4lpine'} + {github: 'johno', name: 'John Otander', twitter: '4lpine'}, + {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2022-02-01'), + modified: new Date('2023-10-24'), published: new Date('2017-12-23'), schemaOrg: { "@context": "https://schema.org", "@type": "SoftwareApplication", "additionalType": "ComputerLanguage", - "name": "MDX", - "description": "an authorable format for writing JSX in markdown documents", "applicationCategory": "DeveloperApplication", + "description": "an authorable format for writing JSX in markdown documents", + "name": "MDX", + "offers": { + "@type": "Offer", + "price": "0.00", + "priceCurrency": "USD" + }, "operatingSystem": "Windows, MacOS, Linux", - "url": "https://mdxjs.com", "sameAs": [ "https://www.wikidata.org/wiki/Q95971592", "https://www.wikidata.org/wiki/Q27966906", @@ -23,14 +28,10 @@ export const info = { "https://en.wikipedia.org/wiki/MDX_(markup_language)", "https://github.com/mdx-js/mdx" ], - "offers": { - "@type": "Offer", - "price": "0.00", - "priceCurrency": "USD" - } + "url": "https://mdxjs.com" } } -export const year = 2018 +export const year = 2023 {/* lint disable heading-style */} @@ -38,7 +39,7 @@ Markdown for the\ **component era** ================= -MDX allows you to use JSX in your markdown content. +MDX lets you use JSX in your markdown content. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast. {/* more */} @@ -53,17 +54,17 @@ This makes writing long-form content with components a blast. {/* more */} Here are the highlights:
    - * 📝 **Improved syntax** makes it easier to use markdown in JSX - * 🧑‍💻 **JavaScript expressions** turn `{2 * Math.PI}` into {2 * Math.PI} - * 🔌 New **esbuild**, **Rollup**, and **Node.js** integrations - * ⚛️ **Any JSX runtime**: React, Preact, Vue, Emotion, you name it, they’re - all supported - * 🌳 **Improved AST** exposes more info in greater detail - * 🏃‍♀️ Compiles at least **25% faster** - * 🚴 Generated code runs twice as fast (**100% faster**) - * 🚄 Bundle size of `@mdx-js/mdx` is more than three times as small - (**250% smaller**) - * 🧵 …and much, so much more + * 📝 **Improved syntax** makes it easier to use markdown in JSX + * 🧑‍💻 **JavaScript expressions** turn `{2 * Math.PI}` into {2 * Math.PI} + * 🔌 New **esbuild**, **Rollup**, and **Node.js** integrations + * ⚛️ **Any JSX runtime**: React, Preact, Vue, Emotion, you name it, they’re + all supported + * 🌳 **Improved AST** exposes more info in greater detail + * 🏃‍♀️ Compiles at least **25% faster** + * 🚴 Generated code runs twice as fast (**100% faster**) + * 🚄 Bundle size of `@mdx-js/mdx` is more than three times as small + (**250% smaller**) + * 🧵 …and much, so much more
    [Continue reading »][v2] @@ -77,7 +78,7 @@ This makes writing long-form content with components a blast. {/* more */} ```mdx path="example.mdx" import {Chart} from './snowfall.js' - export const year = 2018 + export const year = 2023 # Last year’s snowfall @@ -116,24 +117,24 @@ turns into. ## Get started There are integrations for most bundlers, frameworks, and editors. -Whether you build with Next.js, Docusaurus, or Gatsby. -You prefer esbuild, Rollup, or webpack. +Whether you build with Docusaurus, Next.js, or Vite. +You prefer Rollup, esbuild, or webpack. You’re using React, Preact, or Vue. [Get started »][getting-started] ## MDX in short
    - * ❤️ **Powerful**: MDX blends markdown and JSX syntax to fit perfectly in - JSX-based projects - * 💻 **Everything is a component**: Use existing components in your - MDX and import other MDX files as components - * 🔧 **Customizable**: Decide which component is rendered for each markdown - construct (`{h1: MyHeading}`) - * 📚 **Markdown-based**: The simplicity and elegance of markdown remains, - you use JSX only when you want to - * 🔥 **Blazingly blazing fast**: MDX has no runtime, all compilation occurs - during the build stage + * ❤️ **Powerful**: MDX blends markdown and JSX syntax to fit perfectly in + JSX-based projects + * 💻 **Everything is a component**: Use existing components in your + MDX and import other MDX files as components + * 🔧 **Customizable**: Decide which component is rendered for each markdown + construct (`{h1: MyHeading}`) + * 📚 **Markdown-based**: The simplicity and elegance of markdown remains, + you use JSX only when you want to + * 🔥 **Blazingly blazing fast**: MDX has no runtime, all compilation occurs + during the build stage
    {/* To do: quotes. */} @@ -143,6 +144,8 @@ You’re using React, Preact, or Vue. > > — [**@chrisbiscardi**][quote] +{/* [v3]: /blog/v3/ */} + [quote]: https://twitter.com/chrisbiscardi/status/1022304288326864896 [what]: /docs/what-is-mdx/ diff --git a/docs/migrating/v1.mdx b/docs/migrating/v1.mdx index c63bf3c5b..6bebeeade 100644 --- a/docs/migrating/v1.mdx +++ b/docs/migrating/v1.mdx @@ -25,9 +25,9 @@ love for you to ASAP) 📆. ## ⚠️ Breaking changes -* [🚨`@mdx-js/tag` is replaced by `@mdx-js/react` and an `mdx` pragma](#pragma) 🚨 -* [MDXProvider now merges component contexts when nested](#mdxprovider) -* [React support now requires `>= 16.8` in `@mdx-js/react`](#react) +* [🚨`@mdx-js/tag` is replaced by `@mdx-js/react` and an `mdx` pragma](#pragma) 🚨 +* [MDXProvider now merges component contexts when nested](#mdxprovider) +* [React support now requires `>= 16.8` in `@mdx-js/react`](#react) ## Pragma diff --git a/docs/migrating/v2.mdx b/docs/migrating/v2.mdx index 3300f7e34..bb9ffb0d2 100644 --- a/docs/migrating/v2.mdx +++ b/docs/migrating/v2.mdx @@ -11,23 +11,23 @@ export const navExclude = true ## Contents -* [ESM](#esm) -* [Update `@mdx-js/*` packages](#update-mdx-js-packages) - * [`@mdx-js/loader`](#mdx-jsloader) - * [`@mdx-js/react`, `@mdx-js/preact`, `@mdx-js/vue`](#mdx-jsreact-mdx-jspreact-mdx-jsvue) - * [`@mdx-js/mdx`](#mdx-jsmdx) - * [`@mdx-js/runtime`](#mdx-jsruntime) - * [`remark-mdx`](#remark-mdx) - * [`@mdx-js/vue-loader`](#mdx-jsvue-loader) - * [`@mdx-js/parcel-plugin-mdx`](#mdx-jsparcel-plugin-mdx) - * [Other packages](#other-packages) -* [Update MDX files](#update-mdx-files) - * [JSX](#jsx) - * [Expressions](#expressions) - * [ESM](#esm-1) - * [Markdown](#markdown) - * [GFM](#gfm) -* [Update MDX content](#update-mdx-content) +* [ESM](#esm) +* [Update `@mdx-js/*` packages](#update-mdx-js-packages) + * [`@mdx-js/loader`](#mdx-jsloader) + * [`@mdx-js/react`, `@mdx-js/preact`, `@mdx-js/vue`](#mdx-jsreact-mdx-jspreact-mdx-jsvue) + * [`@mdx-js/mdx`](#mdx-jsmdx) + * [`@mdx-js/runtime`](#mdx-jsruntime) + * [`remark-mdx`](#remark-mdx) + * [`@mdx-js/vue-loader`](#mdx-jsvue-loader) + * [`@mdx-js/parcel-plugin-mdx`](#mdx-jsparcel-plugin-mdx) + * [Other packages](#other-packages) +* [Update MDX files](#update-mdx-files) + * [JSX](#jsx) + * [Expressions](#expressions) + * [ESM](#esm-1) + * [Markdown](#markdown) + * [GFM](#gfm) +* [Update MDX content](#update-mdx-content) ## ESM @@ -165,20 +165,20 @@ You can update your code as follows: The above changes get MDX 2 close to how MDX 1 worked. You can make it simpler: -* [`babel-loader`][babel-loader] is optional. - It compiles modern JavaScript to JavaScript your users support. - If you don’t need that you can remove it before `@mdx-js/loader` -* [`remark-gfm`][remark-gfm] is optional. - It adds support for autolink literals, footnotes, strikethrough, tables, and - task lists. - If you don’t want them, you can uninstall it, remove the import, and remove - it from `options.remarkPlugins`. - More info in [our guide on GFM][guide-gfm] -* [`@mdx-js/react`][mdx-react] is optional. - It adds support for context based components passing. - If you don’t need that, you can uninstall it and remove - `options.providerImportSource`. - More info in [¶ MDX provider in § Using MDX][mdx-provider] +* [`babel-loader`][babel-loader] is optional. + It compiles modern JavaScript to JavaScript your users support. + If you don’t need that you can remove it before `@mdx-js/loader` +* [`remark-gfm`][remark-gfm] is optional. + It adds support for autolink literals, footnotes, strikethrough, tables, and + task lists. + If you don’t want them, you can uninstall it, remove the import, and remove + it from `options.remarkPlugins`. + More info in [our guide on GFM][guide-gfm] +* [`@mdx-js/react`][mdx-react] is optional. + It adds support for context based components passing. + If you don’t need that, you can uninstall it and remove + `options.providerImportSource`. + More info in [¶ MDX provider in § Using MDX][mdx-provider] `@mdx-js/loader` now supports Preact and other JSX runtimes through configuration. @@ -204,11 +204,11 @@ For more information, please see [§ API in `@mdx-js/loader`][loader-api]. The options accepted by the loader changed: -* `renderer` is replaced by `jsxImportSource`, `providerImportSource`, and - others options. - More info in [§ API in `@mdx-js/mdx`][mdx-api] -* Other options were undocumented but passed to `@mdx-js/mdx`. - See `@mdx-js/mdx` below if needed +* `renderer` is replaced by `jsxImportSource`, `providerImportSource`, and + others options. + More info in [§ API in `@mdx-js/mdx`][mdx-api] +* Other options were undocumented but passed to `@mdx-js/mdx`. + See `@mdx-js/mdx` below if needed For more information, please see [§ API in `@mdx-js/loader`][loader-api]. @@ -233,9 +233,9 @@ More info in [¶ MDX provider in § Using MDX][mdx-provider]. The interface of changed slightly: -* The named export `mdx`, which was a `createElement` function, is removed. - You can use your framework’s functions instead: `React.createElement`, - `h` from `preact`, etc. +* The named export `mdx`, which was a `createElement` function, is removed. + You can use your framework’s functions instead: `React.createElement`, + `h` from `preact`, etc. ### `@mdx-js/mdx` @@ -282,17 +282,17 @@ You can update your code as follows: The above changes get MDX 2 close to how MDX 1 worked. You can make it simpler: -* [`remark-gfm`][remark-gfm] is optional. - It adds support for autolink literals, footnotes, strikethrough, tables, and - task lists. - If you don’t want them, you can uninstall it, remove the import, and remove - it from `options.remarkPlugins`. - More info in [our guide on GFM][guide-gfm] -* [`@mdx-js/react`][mdx-react] is optional. - It adds support for context based components passing. - If you don’t need that, you can uninstall it and remove - `options.providerImportSource`. - More info in [¶ MDX provider in § Using MDX][mdx-provider] +* [`remark-gfm`][remark-gfm] is optional. + It adds support for autolink literals, footnotes, strikethrough, tables, and + task lists. + If you don’t want them, you can uninstall it, remove the import, and remove + it from `options.remarkPlugins`. + More info in [our guide on GFM][guide-gfm] +* [`@mdx-js/react`][mdx-react] is optional. + It adds support for context based components passing. + If you don’t need that, you can uninstall it and remove + `options.providerImportSource`. + More info in [¶ MDX provider in § Using MDX][mdx-provider] `@mdx-js/mdx` now supports Preact and other JSX runtimes through configuration. Using Preact as an example: @@ -309,31 +309,31 @@ For more information, please see [§ API in `@mdx-js/mdx`][mdx-api] The interface of `@mdx-js/mdx` changed: -* The default export is replaced by the named export [`compile`][mdx-compile] -* The named export `sync` is replaced by [`compileSync`][mdx-compilesync] -* The named export `createCompiler` is replaced by - [`createProcessor`][mdx-createprocessor] -* The named export `createMdxAstCompiler` is removed, use `remark` with - `remark-mdx` instead -* The return value of `compile`, `compileSync` are now [VFile][]s instead of - strings -* There are new exports [`evaluate`][mdx-evaluate], - [`evaluateSync`][mdx-evaluatesync] to eval (compile and run) MDX +* The default export is replaced by the named export [`compile`][mdx-compile] +* The named export `sync` is replaced by [`compileSync`][mdx-compilesync] +* The named export `createCompiler` is replaced by + [`createProcessor`][mdx-createprocessor] +* The named export `createMdxAstCompiler` is removed, use `remark` with + `remark-mdx` instead +* The return value of `compile`, `compileSync` are now [VFile][]s instead of + strings +* There are new exports [`evaluate`][mdx-evaluate], + [`evaluateSync`][mdx-evaluatesync] to eval (compile and run) MDX Options in version 1 were undocumented. If you used them: -* `filepath` is replaced by accepting a VFile or compatible object as the - first argument `file` -* `compilers` is replaced by `recmaPlugins` -* `hastPlugins` is replaced by `rehypePlugins` -* `mdPlugins` is replaced by `options.remarkPlugins` -* `skipExport` is removed, [`evaluate`][mdx-evaluate] can do this - automatically -* `wrapExport` is removed, use a custom recma plugin instead -* There are many new options to support different JSX runtimes, non-React JSX, - compile JSX away, source maps, normal markdown, and otherwise change how MDX - is compiled +* `filepath` is replaced by accepting a VFile or compatible object as the + first argument `file` +* `compilers` is replaced by `recmaPlugins` +* `hastPlugins` is replaced by `rehypePlugins` +* `mdPlugins` is replaced by `options.remarkPlugins` +* `skipExport` is removed, [`evaluate`][mdx-evaluate] can do this + automatically +* `wrapExport` is removed, use a custom recma plugin instead +* There are many new options to support different JSX runtimes, non-React JSX, + compile JSX away, source maps, normal markdown, and otherwise change how MDX + is compiled For more information, please see [§ API in `@mdx-js/mdx`][mdx-api]. @@ -393,11 +393,11 @@ You can update your code as follows: The above changes get MDX 2 close to how MDX 1 worked. You can make it simpler: -* [`@mdx-js/react`][mdx-react] is optional. - It adds support for context based components passing. - If you don’t need that, you can uninstall it and remove - `options.providerImportSource`. - More info in [¶ MDX provider in § Using MDX][mdx-provider] +* [`@mdx-js/react`][mdx-react] is optional. + It adds support for context based components passing. + If you don’t need that, you can uninstall it and remove + `options.providerImportSource`. + More info in [¶ MDX provider in § Using MDX][mdx-provider] `@mdx-js/mdx` now supports Preact and other JSX runtimes through configuration. Using Emotion as an example: @@ -412,12 +412,12 @@ For more information, please see [`evaluate` in `@mdx-js/mdx`][mdx-evaluate]. ###### Changes -* The package `@mdx-js/runtime` is replaced by [`evaluate`][mdx-evaluate] - from `@mdx-js/mdx` -* `evaluate` supports any JSX runtime and providers are optional -* `evaluate` yields an `MDXContent` component just like how importing - and MDX file works -* `evaluate` supports imports and exports inside evaluated MDX +* The package `@mdx-js/runtime` is replaced by [`evaluate`][mdx-evaluate] + from `@mdx-js/mdx` +* `evaluate` supports any JSX runtime and providers are optional +* `evaluate` yields an `MDXContent` component just like how importing + and MDX file works +* `evaluate` supports imports and exports inside evaluated MDX For more information, please see [`evaluate` in `@mdx-js/mdx`][mdx-evaluate]. @@ -454,24 +454,24 @@ to use Parcel with MDX. We removed several packages doing internal work for us. These packages are: -* `@mdx-js/util` - — no longer needed internal helpers -* `@mdx-js/test-util` - — no longer needed test helpers, `evaluate` can do them -* `gatsby-theme-mdx` - — no longer needed website template -* `remark-mdx-remove-imports`, `babel-plugin-extract-import-names` - — no longer needed transforms, our compiler handles imports -* `remark-mdx-remove-exports`, `babel-plugin-remove-export-keywords` - — no longer needed transforms, our compiler handles exports -* `babel-plugin-html-attributes-to-jsx` - — no longer needed transform, something similar is done by - [`hast-util-to-estree`](https://github.com/syntax-tree/hast-util-to-estree) -* `babel-plugin-apply-mdx-type-props` - — no longer needed transform due to the new architecture -* `create-mdx` - — no longer needed, we recommend to start your project with whatever other - integrations you prefer and *then* add MDX to it +* `@mdx-js/util` + — no longer needed internal helpers +* `@mdx-js/test-util` + — no longer needed test helpers, `evaluate` can do them +* `gatsby-theme-mdx` + — no longer needed website template +* `remark-mdx-remove-imports`, `babel-plugin-extract-import-names` + — no longer needed transforms, our compiler handles imports +* `remark-mdx-remove-exports`, `babel-plugin-remove-export-keywords` + — no longer needed transforms, our compiler handles exports +* `babel-plugin-html-attributes-to-jsx` + — no longer needed transform, something similar is done by + [`hast-util-to-estree`](https://github.com/syntax-tree/hast-util-to-estree) +* `babel-plugin-apply-mdx-type-props` + — no longer needed transform due to the new architecture +* `create-mdx` + — no longer needed, we recommend to start your project with whatever other + integrations you prefer and *then* add MDX to it ## Update MDX files @@ -613,30 +613,30 @@ How to do so is described in [our guide on GFM][guide-gfm]. The interface of the generated JavaScript from MDX changed: -* Missing components now throw an error rather than render their children - and emit a warning to the console, which is closer to how frameworks like - React handle missing undefined JSX components -* `parent.child` combos such as `ol.li`, to pass components, were removed, we - recommend to style your `ol`s, `ul`s, and `li`s separately -* The special component name `inlineCode` was removed, we recommend to use - `pre` for the block version of code, and `code` for both the block and - inline versions -* `MDXContent.isMDXContent` was removed, we recommend treating `MDXContent` - like any other component -* Locally defined or imported components precede over passed components -* We now “sandbox” components, for lack of a better name. - It means that when you pass a component for `h1`, it does get used for - `# hi` but not for `

    hi

    ` -* You can now pass and use objects of components: if you pass - `components={{theme}}`, where `theme` is an object with a `Box` component, - it can be used with: `stuff` -* the values exports from an MDX file are no longer passed to layouts, you - can achieve the same with: - ```tsx - import * as everything from './example.mdx' - const {default: Content, ...exported} = everything - - ``` +* Missing components now throw an error rather than render their children + and emit a warning to the console, which is closer to how frameworks like + React handle missing undefined JSX components +* `parent.child` combos such as `ol.li`, to pass components, were removed, we + recommend to style your `ol`s, `ul`s, and `li`s separately +* The special component name `inlineCode` was removed, we recommend to use + `pre` for the block version of code, and `code` for both the block and + inline versions +* `MDXContent.isMDXContent` was removed, we recommend treating `MDXContent` + like any other component +* Locally defined or imported components precede over passed components +* We now “sandbox” components, for lack of a better name. + It means that when you pass a component for `h1`, it does get used for + `# hi` but not for `

    hi

    ` +* You can now pass and use objects of components: if you pass + `components={{theme}}`, where `theme` is an object with a `Box` component, + it can be used with: `stuff` +* the values exports from an MDX file are no longer passed to layouts, you + can achieve the same with: + ```tsx + import * as everything from './example.mdx' + const {default: Content, ...exported} = everything + + ``` We also fixed several cases where defined, imported, or passed components weren’t handled correctly or even crashed. diff --git a/docs/packages/register.md b/docs/packages/register.md deleted file mode 120000 index f5d933204..000000000 --- a/docs/packages/register.md +++ /dev/null @@ -1 +0,0 @@ -../../packages/register/readme.md \ No newline at end of file diff --git a/docs/playground.mdx b/docs/playground.mdx index 7b1aeeeeb..27eef8a0b 100644 --- a/docs/playground.mdx +++ b/docs/playground.mdx @@ -18,4 +18,8 @@ This can be helpful for debugging or exploring. To read about how the MDX format works, we recommend that you start with [§ What is MDX][what]. +
    +
    +
    + [what]: /docs/what-is-mdx/ diff --git a/docs/table-of-components.mdx b/docs/table-of-components.mdx index d8dae0120..7ee31d418 100644 --- a/docs/table-of-components.mdx +++ b/docs/table-of-components.mdx @@ -27,390 +27,392 @@ import {FancyLink} from './components/fancy-link.js' More information on how to use markdown can be found in [CommonMark][]. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameMarkdown syntaxEquivalent JSX
    `a` - ```mdx chrome=no - [MDX](https://mdxjs.com "title") - ``` - - ```tsx chrome=no - <> -

    MDX

    - - ``` -
    `blockquote` - ```mdx chrome=no - > A greater than… - ``` - - ```tsx chrome=no - <> -
    -

    A greater than…

    -
    - - ``` -
    `br` - ```mdx chrome=no - A backslash\ - before a line break… - ``` - - ```tsx chrome=no - <> -

    - A backslash
    - before a line break… -

    - - ``` -
    `code` - ````mdx chrome=no - Some `backticks` for inline. - - ```tsx - backtick.fences('for blocks') - ``` - ```` - - ```tsx chrome=no - <> -

    - Some backticks for inline. -

    - 
    backtick.fences('for blocks')
-
    - - ``` -
    `em` - ```mdx chrome=no - Some *asterisks* for emphasis. - ``` - - ```tsx chrome=no - <> -

    Some asterisks for emphasis.

    - - ``` -
    `h1` - ```mdx chrome=no - # One number sign… - ``` - - ```tsx chrome=no - <> -

    One number sign…

    - - ``` -
    `h2` - ```mdx chrome=no - ## Two number signs… - ``` - - ```tsx chrome=no - <> -

    Two number signs…

    - - ``` -
    `h3` - ```mdx chrome=no - ### Three number signs… - ``` - - ```tsx chrome=no - <> -

    Three number signs…

    - - ``` -
    `h4` - ```mdx chrome=no - #### Four number signs… - ``` - - ```tsx chrome=no - <> -

    Four number signs…

    - - ``` -
    `h5` - ```mdx chrome=no - ##### Five number signs… - ``` - - ```tsx chrome=no - <> -
    Five number signs…
    - - ``` -
    `h6` - ```mdx chrome=no - ###### Six number signs… - ``` - - ```tsx chrome=no - <> -
    Six number signs…
    - - ``` -
    `hr` - ```mdx chrome=no - Three asterisks for a thematic break: - - *** - ``` - - ```tsx chrome=no - <> -

    Three asterisks for a thematic break:

    -
    - - ``` -
    `img` - ```mdx chrome=no - ![Alt text](/logo.png "title") - ``` - - ```tsx chrome=no - <> -

    Alt text

    - - ``` -
    `li` - ```mdx chrome=no - * asterisks for unordered items - - 1. decimals and a dot for ordered items - ``` - - ```tsx chrome=no - <> -
      -
    • asterisks for unordered items
      • -
    -
      -
    1. decimals and a dot for ordered items
      2. -
    - - ``` -
    `ol` - ```mdx chrome=no - 1. decimals and a dot for ordered - ``` - - ```tsx chrome=no - <> -
      -
    1. decimals and a dot for ordered
      2. -
    - - ``` -
    `p` - ```mdx chrome=no - Just some text… - ``` - - ```tsx chrome=no - <> -

    Just some text…

    - - ``` -
    `pre` - ````mdx chrome=no - ```tsx - backtick.fences('for blocks') - ``` - ```` - - ```tsx chrome=no - <> - 
    backtick.fences('for blocks')
-
    - - ``` -
    `strong` - ```mdx chrome=no - Two **asterisks** for strong. - ``` - - ```tsx chrome=no - <> -

    Two asterisks for strong.

    - - ``` -
    `ul` - ```mdx chrome=no - * asterisks for unordered - ``` - - ```tsx chrome=no - <> -
      -
    • asterisks for unordered
      • -
    - - ``` -
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameMarkdown syntaxEquivalent JSX
    `a` + ```mdx chrome=no + [MDX](https://mdxjs.com "title") + ``` + + ```tsx chrome=no + <> +

    MDX

    + + ``` +
    `blockquote` + ```mdx chrome=no + > A greater than… + ``` + + ```tsx chrome=no + <> +
    +

    A greater than…

    +
    + + ``` +
    `br` + ```mdx chrome=no + A backslash\ + before a line break… + ``` + + ```tsx chrome=no + <> +

    + A backslash
    + before a line break… +

    + + ``` +
    `code` + ````mdx chrome=no + Some `backticks` for inline. + + ```tsx + backtick.fences('for blocks') + ``` + ```` + + ```tsx chrome=no + <> +

    + Some backticks for inline. +

    + 
    backtick.fences('for blocks')
+
    + + ``` +
    `em` + ```mdx chrome=no + Some *asterisks* for emphasis. + ``` + + ```tsx chrome=no + <> +

    Some asterisks for emphasis.

    + + ``` +
    `h1` + ```mdx chrome=no + # One number sign… + ``` + + ```tsx chrome=no + <> +

    One number sign…

    + + ``` +
    `h2` + ```mdx chrome=no + ## Two number signs… + ``` + + ```tsx chrome=no + <> +

    Two number signs…

    + + ``` +
    `h3` + ```mdx chrome=no + ### Three number signs… + ``` + + ```tsx chrome=no + <> +

    Three number signs…

    + + ``` +
    `h4` + ```mdx chrome=no + #### Four number signs… + ``` + + ```tsx chrome=no + <> +

    Four number signs…

    + + ``` +
    `h5` + ```mdx chrome=no + ##### Five number signs… + ``` + + ```tsx chrome=no + <> +
    Five number signs…
    + + ``` +
    `h6` + ```mdx chrome=no + ###### Six number signs… + ``` + + ```tsx chrome=no + <> +
    Six number signs…
    + + ``` +
    `hr` + ```mdx chrome=no + Three asterisks for a thematic break: + + *** + ``` + + ```tsx chrome=no + <> +

    Three asterisks for a thematic break:

    +
    + + ``` +
    `img` + ```mdx chrome=no + ![Alt text](/logo.png "title") + ``` + + ```tsx chrome=no + <> +

    Alt text

    + + ``` +
    `li` + ```mdx chrome=no + * asterisks for unordered items + + 1. decimals and a dot for ordered items + ``` + + ```tsx chrome=no + <> +
      +
    • asterisks for unordered items
      • +
    +
      +
    1. decimals and a dot for ordered items
      2. +
    + + ``` +
    `ol` + ```mdx chrome=no + 1. decimals and a dot for ordered + ``` + + ```tsx chrome=no + <> +
      +
    1. decimals and a dot for ordered
      2. +
    + + ``` +
    `p` + ```mdx chrome=no + Just some text… + ``` + + ```tsx chrome=no + <> +

    Just some text…

    + + ``` +
    `pre` + ````mdx chrome=no + ```tsx + backtick.fences('for blocks') + ``` + ```` + + ```tsx chrome=no + <> + 
    backtick.fences('for blocks')
+
    + + ``` +
    `strong` + ```mdx chrome=no + Two **asterisks** for strong. + ``` + + ```tsx chrome=no + <> +

    Two asterisks for strong.

    + + ``` +
    `ul` + ```mdx chrome=no + * asterisks for unordered + ``` + + ```tsx chrome=no + <> +
      +
    • asterisks for unordered
      • +
    + + ``` +
    +
    The components you can overwrite use their standard HTML names. Normally, in markdown, those names are: `a`, `blockquote`, `br`, `code`, `em`, diff --git a/package-lock.json b/package-lock.json index 7db511277..1a56382e6 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2930,9 +2930,9 @@ } }, "node_modules/caniuse-lite": { - "version": "1.0.30001551", - "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001551.tgz", - "integrity": "sha512-vtBAez47BoGMMzlbYhfXrMV1kvRF2WP/lqiMuDu1Sb4EE4LKEgjopFDSRtZfdVnslNRpOqV/woE+Xgrwj6VQlg==", + "version": "1.0.30001553", + "resolved": "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001553.tgz", + "integrity": "sha512-N0ttd6TrFfuqKNi+pMgWJTb9qrdJu4JSpgPFLe/lrD19ugC6fZgF0pUewRowDwzdDnb9V41mFcdlYgl/PyKf4A==", "funding": [ { "type": "opencollective", @@ -3983,6 +3983,17 @@ "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==", "dev": true }, + "node_modules/encoding": { + "version": "0.1.13", + "resolved": "https://registry.npmjs.org/encoding/-/encoding-0.1.13.tgz", + "integrity": "sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A==", + "dev": true, + "optional": true, + "peer": true, + "dependencies": { + "iconv-lite": "^0.6.2" + } + }, "node_modules/end-of-stream": { "version": "1.4.4", "resolved": "https://registry.npmjs.org/end-of-stream/-/end-of-stream-1.4.4.tgz", @@ -4456,21 +4467,21 @@ } }, "node_modules/eslint-import-resolver-webpack": { - "version": "0.13.7", - "resolved": "https://registry.npmjs.org/eslint-import-resolver-webpack/-/eslint-import-resolver-webpack-0.13.7.tgz", - "integrity": "sha512-2a+meyMeABBRO4K53Oj1ygkmt5lhQS79Lmx2f684Qnv6gjvD4RLOM5jfPGTXwQ0A2K03WSoKt3HRQu/uBgxF7w==", + "version": "0.13.8", + "resolved": "https://registry.npmjs.org/eslint-import-resolver-webpack/-/eslint-import-resolver-webpack-0.13.8.tgz", + "integrity": "sha512-Y7WIaXWV+Q21Rz/PJgUxiW/FTBOWmU8NTLdz+nz9mMoiz5vAev/fOaQxwD7qRzTfE3HSm1qsxZ5uRd7eX+VEtA==", "dev": true, "dependencies": { - "array.prototype.find": "^2.2.1", + "array.prototype.find": "^2.2.2", "debug": "^3.2.7", "enhanced-resolve": "^0.9.1", "find-root": "^1.1.0", - "has": "^1.0.3", + "hasown": "^2.0.0", "interpret": "^1.4.0", - "is-core-module": "^2.13.0", + "is-core-module": "^2.13.1", "is-regex": "^1.1.4", "lodash": "^4.17.21", - "resolve": "^2.0.0-next.4", + "resolve": "^2.0.0-next.5", "semver": "^5.7.2" }, "engines": { @@ -6667,6 +6678,20 @@ "node": ">=10.17.0" } }, + "node_modules/iconv-lite": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz", + "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==", + "dev": true, + "optional": true, + "peer": true, + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, "node_modules/ieee754": { "version": "1.2.1", "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz", @@ -25063,6 +25088,14 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/safer-buffer": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", + "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", + "dev": true, + "optional": true, + "peer": true + }, "node_modules/scheduler": { "version": "0.23.0", "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.0.tgz", diff --git a/package.json b/package.json index ee241751c..707268f9d 100644 --- a/package.json +++ b/package.json @@ -123,8 +123,7 @@ "docs-js-editor": "esbuild --bundle --conditions=browser,production --define:process.env.NODE_ENV=\\\"production\\\" --log-level=warning --minify --outfile=public/editor.js --target=es2020 docs/_asset/editor.jsx", "docs-post": "node website/post.js", "docs-prep": "node website/prep.js && npm run docs-js && npm run docs-css", - "#": "remark . --frail --output --quiet && remark . --ext mdx --frail --output --plugin remark-mdx --quiet", - "format": "prettier . --log-level warn --write && xo --fix", + "format": "remark . --frail --output --quiet && remark . --ext mdx --frail --output --quiet --use remark-mdx && prettier . --log-level warn --write && xo --fix", "test": "npm run build && npm run format && npm run test-coverage", "test-api": "npm run test-api --workspaces --if-present", "test-coverage": "npm run test-coverage --workspaces --if-present" @@ -152,6 +151,11 @@ "remarkConfig": { "plugins": [ "remark-preset-wooorm", + [ + "remark-preset-wooorm/node_modules/remark-gfm/index.js", + false + ], + "remark-gfm", [ "remark-lint-no-html", false @@ -159,6 +163,16 @@ [ "remark-lint-file-extension", false + ], + [ + "remark-lint-list-item-indent", + "space" + ], + [ + "remark-stringify", + { + "listItemIndent": "one" + } ] ] }, diff --git a/packages/esbuild/readme.md b/packages/esbuild/readme.md index b89eb9666..82432551d 100644 --- a/packages/esbuild/readme.md +++ b/packages/esbuild/readme.md @@ -13,16 +13,18 @@ esbuild plugin for MDX. ## Contents -* [What is this?](#what-is-this) -* [When should I use this?](#when-should-i-use-this) -* [Install](#install) -* [Use](#use) -* [API](#api) - * [`mdx(options?)`](#mdxoptions) -* [Types](#types) -* [Security](#security) -* [Contribute](#contribute) -* [License](#license) +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`mdx(options?)`](#mdxoptions) + * [`Options`](#options) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Contribute](#contribute) +* [License](#license) ## What is this? @@ -30,8 +32,8 @@ This package is an esbuild plugin to support MDX. ## When should I use this? -This integration is useful if you’re using esbuild (or another tool that uses -esbuild). +This integration is useful if you’re using [esbuild][] (or another tool that +uses esbuild). If you want to evaluate MDX code then the lower-level compiler (`@mdx-js/mdx`) can be used. @@ -61,11 +63,7 @@ await esbuild.build({ entryPoints: ['index.js'], format: 'esm', outfile: 'output.js', - plugins: [ - mdx({ - /* Options… */ - }) - ] + plugins: [mdx({/* jsxImportSource: …, otherOptions… */})] }) ``` @@ -86,8 +84,8 @@ See esbuild’s docs for more info. ###### Parameters -* `options` ([`Options`][api-options], optional) - — configuration +* `options` ([`Options`][api-options], optional) + — configuration ###### Returns diff --git a/packages/loader/lib/index.js b/packages/loader/lib/index.js index fb4656fde..6aa72b808 100644 --- a/packages/loader/lib/index.js +++ b/packages/loader/lib/index.js @@ -61,6 +61,7 @@ export function loader(value, callback) { /* c8 ignore next -- some loaders set `undefined` (see `TypeStrong/ts-loader`). */ const compiler = this._compiler || marker + // To do: next major (MDX 4?): remove. if ('renderer' in config) { callback( new Error( diff --git a/packages/loader/readme.md b/packages/loader/readme.md index 8f5c4843f..df3f20a2c 100644 --- a/packages/loader/readme.md +++ b/packages/loader/readme.md @@ -13,15 +13,20 @@ webpack loader for MDX. ## Contents -* [What is this?](#what-is-this) -* [When should I use this?](#when-should-i-use-this) -* [Install](#install) -* [Use](#use) -* [API](#api) -* [Types](#types) -* [Security](#security) -* [Contribute](#contribute) -* [License](#license) +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`mdx`](#mdx) + * [`Options`](#options) +* [Examples](#examples) + * [Combine with Babel](#combine-with-babel) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Contribute](#contribute) +* [License](#license) ## What is this? @@ -64,7 +69,7 @@ const webpackConfig = { { loader: '@mdx-js/loader', /** @type {import('@mdx-js/loader').Options} */ - options: {} + options: {/* jsxImportSource: …, otherOptions… */} } ] } diff --git a/packages/mdx/readme.md b/packages/mdx/readme.md index 88075d1a3..2524497c1 100644 --- a/packages/mdx/readme.md +++ b/packages/mdx/readme.md @@ -14,16 +14,33 @@ MDX compiler. ## Contents -* [What is this?](#what-is-this) -* [When should I use this?](#when-should-i-use-this) -* [Install](#install) -* [Use](#use) -* [API](#api) -* [Types](#types) -* [Architecture](#architecture) -* [Security](#security) -* [Contribute](#contribute) -* [License](#license) +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`compile(file, options?)`](#compilefile-options) + * [`compileSync(file, options?)`](#compilesyncfile-options) + * [`createProcessor(options?)`](#createprocessoroptions) + * [`evaluate(file, options)`](#evaluatefile-options) + * [`evaluateSync(file, options)`](#evaluatesyncfile-options) + * [`nodeTypes`](#nodetypes) + * [`run(code, options)`](#runcode-options) + * [`runSync(code, options)`](#runsynccode-options) + * [`CompileOptions`](#compileoptions) + * [`EvaluateOptions`](#evaluateoptions) + * [`Fragment`](#fragment) + * [`Jsx`](#jsx) + * [`JsxDev`](#jsxdev) + * [`ProcessorOptions`](#processoroptions) + * [`RunOptions`](#runoptions) + * [`UseMdxComponents`](#usemdxcomponents) +* [Types](#types) +* [Architecture](#architecture) +* [Compatibility](#compatibility) +* [Security](#security) +* [Contribute](#contribute) +* [License](#license) ## What is this? @@ -128,10 +145,10 @@ Compile MDX to JS. ###### Parameters -* `file` ([`Compatible` from `vfile`][vfile-compatible]) - — MDX document to parse -* `options` ([`CompileOptions`][api-compile-options], optional) - — compile configuration +* `file` ([`Compatible` from `vfile`][vfile-compatible]) + — MDX document to parse +* `options` ([`CompileOptions`][api-compile-options], optional) + — compile configuration ###### Returns @@ -181,10 +198,10 @@ When possible please use the async [`compile`][api-compile]. ###### Parameters -* `file` ([`Compatible` from `vfile`][vfile-compatible]) - — MDX document to parse -* `options` ([`CompileOptions`][api-compile-options], optional) - — compile configuration +* `file` ([`Compatible` from `vfile`][vfile-compatible]) + — MDX document to parse +* `options` ([`CompileOptions`][api-compile-options], optional) + — compile configuration ###### Returns @@ -198,8 +215,8 @@ Create a processor to compile markdown or MDX to JavaScript. ###### Parameters -* `options` ([`ProcessorOptions`][api-processor-options], optional) - — process configuration +* `options` ([`ProcessorOptions`][api-processor-options], optional) + — process configuration ###### Returns @@ -207,7 +224,7 @@ Processor ([`Processor` from `unified`][unified-processor]). ### `evaluate(file, options)` -[Compile][] and [run][] MDX. +[Compile][api-compile] and [run][api-run] MDX. When you trust your content, `evaluate` can work. When possible, use [`compile`][api-compile], write to a file, and then run with @@ -217,14 +234,15 @@ Node or use one of the [§ Integrations][integrations]. ###### Parameters -* `file` ([`Compatible` from `vfile`][vfile-compatible]) - — MDX document to parse -* `options` ([`EvaluateOptions`][api-evaluate-options], **required**) - — configuration +* `file` ([`Compatible` from `vfile`][vfile-compatible]) + — MDX document to parse +* `options` ([`EvaluateOptions`][api-evaluate-options], **required**) + — configuration ###### Returns -Promise to a module ([`Promise` from `mdx/types.js`][mdx-types-module]). +Promise to a module ([`Promise` from +`mdx/types.js`][mdx-types-module]). The result is an object with a `default` field set to the component; anything else that was exported is available too. @@ -271,10 +289,10 @@ When possible please use the async [`evaluate`][api-evaluate]. ###### Parameters -* `file` ([`Compatible` from `vfile`][vfile-compatible]) - — MDX document to parse -* `options` ([`EvaluateOptions`][api-evaluate-options], **required**) - — configuration +* `file` ([`Compatible` from `vfile`][vfile-compatible]) + — MDX document to parse +* `options` ([`EvaluateOptions`][api-evaluate-options], **required**) + — configuration ###### Returns @@ -293,14 +311,15 @@ Run code compiled with `outputFormat: 'function-body'`. ###### Parameters -* `code` ([`VFile`][vfile] or `string`) - — JavaScript function body to run -* `options` ([`RunOptions`][api-run-options], **required**) - — configuration +* `code` ([`VFile`][vfile] or `string`) + — JavaScript function body to run +* `options` ([`RunOptions`][api-run-options], **required**) + — configuration ###### Returns -Promise to a module ([`Promise` from `mdx/types.js`][mdx-types-module]); +Promise to a module ([`Promise` from +`mdx/types.js`][mdx-types-module]); the result is an object with a `default` field set to the component; anything else that was exported is available too. @@ -344,10 +363,10 @@ When possible please use the async [`run`][api-run]. ###### Parameters -* `code` ([`VFile`][vfile] or `string`) - — JavaScript function body to run -* `options` ([`RunOptions`][api-run-options], **required**) - — configuration +* `code` ([`VFile`][vfile] or `string`) + — JavaScript function body to run +* `options` ([`RunOptions`][api-run-options], **required**) + — configuration ###### Returns @@ -424,12 +443,12 @@ Create a production element (TypeScript type). ###### Parameters -* `type` (`unknown`) - — element type: `Fragment` symbol, tag name (`string`), component -* `props` (`Props`) - — element props and `children` -* `key` (`string` or `undefined`) - — key to use +* `type` (`unknown`) + — element type: `Fragment` symbol, tag name (`string`), component +* `props` (`Props`) + — element props and `children` +* `key` (`string` or `undefined`) + — key to use ###### Returns @@ -441,19 +460,19 @@ Create a development element (TypeScript type). ###### Parameters -* `type` (`unknown`) - — element type: `Fragment` symbol, tag name (`string`), component -* `props` (`Props`) - — element props and `children` -* `key` (`string` or `undefined`) - — key to use -* `isStaticChildren` (`boolean`) - — whether two or more children are passed (in an array), which is whether - `jsxs` or `jsx` would be used -* `source` (`Source`) - — info about source -* `self` (`unknown`) - — context object (`this`) +* `type` (`unknown`) + — element type: `Fragment` symbol, tag name (`string`), component +* `props` (`Props`) + — element props and `children` +* `key` (`string` or `undefined`) + — key to use +* `isStaticChildren` (`boolean`) + — whether two or more children are passed (in an array), which is whether + `jsxs` or `jsx` would be used +* `source` (`Source`) + — info about source +* `self` (`unknown`) + — context object (`this`) ### `ProcessorOptions` @@ -461,498 +480,517 @@ Configuration for `createProcessor` (TypeScript type). ###### Fields -* `SourceMapGenerator` (`SourceMapGenerator` from [`source-map`][source-map], - optional) - — add a source map (object form) as the `map` field on the resulting file +* `SourceMapGenerator` (`SourceMapGenerator` from [`source-map`][source-map], + optional) + — add a source map (object form) as the `map` field on the resulting file -
    Expand example +
    Expand example - Assuming `example.mdx` from [§ Use][use] exists, then: + Assuming `example.mdx` from [§ Use][use] exists, then: - ```tsx - import fs from 'node:fs/promises' - import {compile} from '@mdx-js/mdx' - import {SourceMapGenerator} from 'source-map' + ```tsx + import fs from 'node:fs/promises' + import {compile} from '@mdx-js/mdx' + import {SourceMapGenerator} from 'source-map' - const file = await compile( - {path: 'example.mdx', value: await fs.readFile('example.mdx')}, - {SourceMapGenerator} - ) + const file = await compile( + {path: 'example.mdx', value: await fs.readFile('example.mdx')}, + {SourceMapGenerator} + ) - console.log(file.map) - ``` + console.log(file.map) + ``` - …yields: + …yields: - ```tsx - { - file: 'example.mdx', - mappings: ';;aAAaA,QAAQ;YAAQ;;;;;;;;iBAE3B', - names: ['Thing'], - sources: ['example.mdx'], - version: 3 - } - ``` + ```tsx + { + file: 'example.mdx', + mappings: ';;aAAaA,QAAQ;YAAQ;;;;;;;;iBAE3B', + names: ['Thing'], + sources: ['example.mdx'], + version: 3 + } + ``` -
    -* `baseUrl` (`URL` or `string`, optional, example: `import.meta.url`) - — use this URL as `import.meta.url` and resolve `import` and - `export … from` relative to it - -
    Expand example - - Say we have a module `example.js`: - - ```tsx - import {compile} from '@mdx-js/mdx' - - const code = 'export {number} from "./data.js"\n\n# hi' - const baseUrl = 'https://a.full/url' // Typically `import.meta.url` - - console.log(String(await compile(code, {baseUrl}))) - ``` - - …now running `node example.js` yields: - - ```tsx - import {jsx as _jsx} from 'react/jsx-runtime' - export {number} from 'https://a.full/data.js' - function _createMdxContent(props) { /* … */ } - export default function MDXContent(props = {}) { /* … */ } - ``` - -
    -* `development` (`boolean`, default: `false`) - — whether to add extra info to error messages in generated code and use the - development automatic JSX runtime (`Fragment` and `jsxDEV` from - `/jsx-dev-runtime`); - when using the webpack loader (`@mdx-js/loader`) or the Rollup integration - (`@mdx-js/rollup`) through Vite, this is automatically inferred from how - you configure those tools - -
    Expand example - - Say we had some MDX that references a component that can be passed or - provided at runtime: - - ```mdx - **Note**: some stuff. - ``` - - And a module to evaluate that: - - ```tsx - import fs from 'node:fs/promises' - import {evaluate} from '@mdx-js/mdx' - import * as runtime from 'react/jsx-runtime' - - const path = 'example.mdx' - const value = await fs.readFile(path) - const MDXContent = (await evaluate({path, value}, runtime)).default - - console.log(MDXContent({})) - ``` - - …running that would normally (production) yield: - - ```txt - Error: Expected component `NoteIcon` to be defined: you likely forgot to import, pass, or provide it. - at _missingMdxReference (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :27:9) - at _createMdxContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :15:20) - at MDXContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :9:9) - at main (…/example.js:11:15) - ``` - - …but if we add `development: true` to our example: - - ```diff - @@ -7,6 +7,6 @@ - import fs from 'node:fs/promises' - -import * as runtime from 'react/jsx-runtime' - +import * as runtime from 'react/jsx-dev-runtime' - import {evaluate} from '@mdx-js/mdx' - - const path = 'example.mdx' - const value = await fs.readFile(path) - -const MDXContent = (await evaluate({path, value}, runtime)).default - +const MDXContent = (await evaluate({path, value}, {development: true, ...runtime})).default - - console.log(MDXContent({})) - ``` - - …and we’d run it again, we’d get: - - ```txt - Error: Expected component `NoteIcon` to be defined: you likely forgot to import, pass, or provide it. - It’s referenced in your code at `1:9-1:21` in `example.mdx` - provide it. - at _missingMdxReference (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :27:9) - at _createMdxContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :15:20) - at MDXContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :9:9) - at main (…/example.js:11:15) - ``` - -
    -* `elementAttributeNameCase` (`'html'` or `'react`, default: `'react'`) - — casing to use for attribute names; - HTML casing is for example `class`, `stroke-linecap`, `xml:lang`; - React casing is for example `className`, `strokeLinecap`, `xmlLang`; - for JSX components written in MDX, the author has to be aware of which - framework they use and write code accordingly; - for AST nodes generated by this project, this option configures it -* `format` (`'md'` or `'mdx'`, default: `'mdx'`) - — format of the file; - `'md'` means treat as markdown and `'mdx'` means treat as [MDX][mdx-syntax] - -
    Expand example - - ```tsx - compile('…') // Seen as MDX. - compile('…', {format: 'mdx'}) // Seen as MDX. - compile('…', {format: 'md'}) // Seen as markdown. - ``` - -
    -* `jsx` (`boolean`, default: `false`) - — whether to keep JSX; - the default is to compile JSX away so that the resulting file is - immediately runnable. - -
    Expand example - - If `file` is the contents of `example.mdx` from [§ Use][use], then: - - ```tsx - compile(file, {jsx: true}) - ``` - - …yields this difference: - - ```diff - /* @jsxRuntime automatic @jsxImportSource react */ - -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime' - - export function Thing() { - - return _jsx(_Fragment, {children: 'World'}) - + return <>World! - } +
    - function _createMdxContent(props) { - const _components = { - h1: 'h1', - ...props.components - } - - return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]}) - + return <_components.h1>{"Hello "} - } +* `baseUrl` (`URL` or `string`, optional, example: `import.meta.url`) + — use this URL as `import.meta.url` and resolve `import` and + `export … from` relative to it - export default function MDXContent(props = {}) { - const {wrapper: MDXLayout} = props.components || {} - return MDXLayout - - ? _jsx(MDXLayout, { - - ...props, - - children: _jsx(_createMdxContent, props) - - }) - + ? <_createMdxContent {...props} /> - : _createMdxContent(props) - } - } - ``` +
    Expand example -
    -* `jsxImportSource` (`string`, default: `'react'`) - — place to import automatic JSX runtimes from; - when in the `automatic` runtime, this is used to define an import for - `Fragment`, `jsx`, `jsxDEV`, and `jsxs` + Say we have a module `example.js`: -
    Expand example + ```tsx + import {compile} from '@mdx-js/mdx' - If `file` is the contents of `example.mdx` from [§ Use][use], then: + const code = 'export {number} from "./data.js"\n\n# hi' + const baseUrl = 'https://a.full/url' // Typically `import.meta.url` - ```tsx - compile(file, {jsxImportSource: 'preact'}) - ``` + console.log(String(await compile(code, {baseUrl}))) + ``` - …yields this difference: + …now running `node example.js` yields: - ```diff - -/* @jsxRuntime automatic @jsxImportSource react */ - -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime' - +/* @jsxRuntime automatic @jsxImportSource preact */ - +import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from 'preact/jsx-runtime' - ``` + ```tsx + import {jsx as _jsx} from 'react/jsx-runtime' + export {number} from 'https://a.full/data.js' + function _createMdxContent(props) { /* … */ } + export default function MDXContent(props = {}) { /* … */ } + ``` -
    -* `jsxRuntime` (`'automatic'` or `'classic'`, default: `'automatic'`) - — JSX runtime to use; - the automatic runtime compiles to `import _jsx from - '$importSource/jsx-runtime'\n_jsx('p')`; - the classic runtime compiles to calls such as `h('p')` +
    - > 👉 **Note**: support for the classic runtime is deprecated and will - > likely be removed in the next major version. +* `development` (`boolean`, default: `false`) + — whether to add extra info to error messages in generated code and use the + development automatic JSX runtime (`Fragment` and `jsxDEV` from + `/jsx-dev-runtime`); + when using the webpack loader (`@mdx-js/loader`) or the Rollup integration + (`@mdx-js/rollup`) through Vite, this is automatically inferred from how + you configure those tools -
    Expand example +
    Expand example - If `file` is the contents of `example.mdx` from [§ Use][use], then: + Say we had some MDX that references a component that can be passed or + provided at runtime: - ```tsx - compile(file, {jsxRuntime: 'classic'}) - ``` + ```mdx + **Note**: some stuff. + ``` - …yields this difference: + And a module to evaluate that: - ```diff - -/* @jsxRuntime automatic @jsxImportSource react */ - -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime' - +/* @jsxRuntime classic @jsx React.createElement @jsxFrag React.Fragment */ - +import React from 'react' + ```tsx + import fs from 'node:fs/promises' + import {evaluate} from '@mdx-js/mdx' + import * as runtime from 'react/jsx-runtime' - export function Thing() { - - return _jsx(_Fragment, {children: 'World'}) - + return React.createElement(React.Fragment, null, 'World!') - } - … - ``` - -
    -* `outputFormat` (`'function-body'` or `'program'`, default: `'program'`) - — output format to generate; - in most cases `'program'` should be used, it results in a whole program; - internally [`evaluate`][api-evaluate] uses `'function-body'` to compile to - code that can be passed to [`run`][api-run]; - in some cases, you might want to do what `evaluate` does in separate steps - yourself, such as when compiling on the server and running on the client. - -
    Expand example - - With a module `example.js`: - - ```tsx - import {compile} from '@mdx-js/mdx' - - const code = 'export const no = 3.14\n\n# hi {no}' - - console.log(String(await compile(code, {outputFormat: 'program'}))) // Default. - console.log(String(await compile(code, {outputFormat: 'function-body'}))) - ``` - - …yields: - - ```tsx - /* @jsxRuntime automatic @jsxImportSource react */ - import {jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime' - export const no = 3.14 - function _createMdxContent(props) { /* … */ } - export default function MDXContent(props = {}) { /* … */ } - ``` - - ```tsx - const {Fragment: _Fragment, jsx: _jsx} = arguments[0] - const no = 3.14 - function _createMdxContent(props) { /* … */ } - function MDXContent(props = {}) { /* … */ } - return {no, default: MDXContent} - ``` - - The `'program'` format will use import statements to import the runtime (and - optionally provider) and use an export statement to yield the `MDXContent` - component. - - The `'function-body'` format will get the runtime (and optionally provider) from - `arguments[0]`, rewrite export statements, and use a return statement to yield - what was exported. - -
    -* `mdExtensions` (`Array`, default: `['.md', '.markdown', '.mdown', - '.mkdn', '.mkd', '.mdwn', '.mkdown', '.ron']`) - — list of markdown extensions, with dot - affects [§ Integrations][integrations] -* `mdxExtensions` (`Array`, default: `['.mdx']`) - — list of MDX extensions, with dot; - affects [§ Integrations][integrations] -* `pragma` (`string`, default: `'React.createElement'`) - — pragma for JSX, used in the classic runtime as an identifier for function - calls: `` to `React.createElement('x')`; - when changing this, you should also define `pragmaFrag` and - `pragmaImportSource` too - - > 👉 **Note**: support for the classic runtime is deprecated and will - > likely be removed in the next major version. - -
    Expand example - - If `file` is the contents of `example.mdx` from [§ Use][use], then: - - ```tsx - compile(file, { - jsxRuntime: 'classic', - pragma: 'preact.createElement', - pragmaFrag: 'preact.Fragment', - pragmaImportSource: 'preact/compat' - }) - ``` - - …yields this difference: - - ```diff - -/* @jsxRuntime classic @jsx React.createElement @jsxFrag React.Fragment */ - -import React from 'react' - +/* @jsxRuntime classic @jsx preact.createElement @jsxFrag preact.Fragment */ - +import preact from 'preact/compat' - - export function Thing() { - - return React.createElement(React.Fragment, null, 'World!') - + return preact.createElement(preact.Fragment, null, 'World!') - } - … - ``` - -
    -* `pragmaFrag` (`string`, default: `'React.Fragment'`) - — pragma for fragment symbol, used in the classic runtime as an identifier - for unnamed calls: `<>` to `React.createElement(React.Fragment)`; - when changing this, you should also define `pragma` and `pragmaImportSource` - too - - > 👉 **Note**: support for the classic runtime is deprecated and will - > likely be removed in the next major version. -* `pragmaImportSource` (`string`, default: `'react'`) - — where to import the identifier of `pragma` from, used in the classic - runtime; - to illustrate, when `pragma` is `'a.b'` and `pragmaImportSource` is `'c'` - the following will be generated: `import a from 'c'` and things such as - `a.b('h1', {})`; - when changing this, you should also define `pragma` and `pragmaFrag` too - - > 👉 **Note**: support for the classic runtime is deprecated and will - > likely be removed in the next major version. -* `providerImportSource` (`string`, optional, example: `'@mdx-js/react'`) - — place to import a provider from; - normally it’s used for runtimes that support context (React, Preact), but - it can be used to inject components into the compiled code; - the module must export and identifier `useMDXComponents` which is called - without arguments to get an object of components (see - [`UseMdxComponents`][api-use-mdx-components]) - -
    Expand example - - If `file` is the contents of `example.mdx` from [§ Use][use], then: - - ```tsx - compile(file, {providerImportSource: '@mdx-js/react'}) - ``` - - …yields this difference: - - ```diff - /* @jsxRuntime automatic @jsxImportSource react */ - import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime' - +import {useMDXComponents as _provideComponents} from '@mdx-js/react' - - export function Thing() { - return _jsx(_Fragment, {children: 'World'}) + const path = 'example.mdx' + const value = await fs.readFile(path) + const MDXContent = (await evaluate({path, value}, runtime)).default + + console.log(MDXContent({})) + ``` + + …running that would normally (production) yield: + + ```txt + Error: Expected component `NoteIcon` to be defined: you likely forgot to import, pass, or provide it. + at _missingMdxReference (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :27:9) + at _createMdxContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :15:20) + at MDXContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :9:9) + at main (…/example.js:11:15) + ``` + + …but if we add `development: true` to our example: + + ```diff + @@ -7,6 +7,6 @@ + import fs from 'node:fs/promises' + -import * as runtime from 'react/jsx-runtime' + +import * as runtime from 'react/jsx-dev-runtime' + import {evaluate} from '@mdx-js/mdx' + + const path = 'example.mdx' + const value = await fs.readFile(path) + -const MDXContent = (await evaluate({path, value}, runtime)).default + +const MDXContent = (await evaluate({path, value}, {development: true, ...runtime})).default + + console.log(MDXContent({})) + ``` + + …and we’d run it again, we’d get: + + ```txt + Error: Expected component `NoteIcon` to be defined: you likely forgot to import, pass, or provide it. + It’s referenced in your code at `1:9-1:21` in `example.mdx` + provide it. + at _missingMdxReference (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :27:9) + at _createMdxContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :15:20) + at MDXContent (eval at run (…/@mdx-js/mdx/lib/run.js:18:10), :9:9) + at main (…/example.js:11:15) + ``` + +
    + +* `elementAttributeNameCase` (`'html'` or `'react`, default: `'react'`) + — casing to use for attribute names; + HTML casing is for example `class`, `stroke-linecap`, `xml:lang`; + React casing is for example `className`, `strokeLinecap`, `xmlLang`; + for JSX components written in MDX, the author has to be aware of which + framework they use and write code accordingly; + for AST nodes generated by this project, this option configures it + +* `format` (`'md'` or `'mdx'`, default: `'mdx'`) + — format of the file; + `'md'` means treat as markdown and `'mdx'` means treat as [MDX][mdx-syntax] + +
    Expand example + + ```tsx + compile('…') // Seen as MDX. + compile('…', {format: 'mdx'}) // Seen as MDX. + compile('…', {format: 'md'}) // Seen as markdown. + ``` + +
    + +* `jsx` (`boolean`, default: `false`) + — whether to keep JSX; + the default is to compile JSX away so that the resulting file is + immediately runnable. + +
    Expand example + + If `file` is the contents of `example.mdx` from [§ Use][use], then: + + ```tsx + compile(file, {jsx: true}) + ``` + + …yields this difference: + + ```diff + /* @jsxRuntime automatic @jsxImportSource react */ + -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime' + + export function Thing() { + - return _jsx(_Fragment, {children: 'World'}) + + return <>World! + } + + function _createMdxContent(props) { + const _components = { + h1: 'h1', + ...props.components } + - return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]}) + + return <_components.h1>{"Hello "} + } + + export default function MDXContent(props = {}) { + const {wrapper: MDXLayout} = props.components || {} + return MDXLayout + - ? _jsx(MDXLayout, { + - ...props, + - children: _jsx(_createMdxContent, props) + - }) + + ? <_createMdxContent {...props} /> + : _createMdxContent(props) + } + } + ``` + +
    + +* `jsxImportSource` (`string`, default: `'react'`) + — place to import automatic JSX runtimes from; + when in the `automatic` runtime, this is used to define an import for + `Fragment`, `jsx`, `jsxDEV`, and `jsxs` + +
    Expand example + + If `file` is the contents of `example.mdx` from [§ Use][use], then: + + ```tsx + compile(file, {jsxImportSource: 'preact'}) + ``` + + …yields this difference: + + ```diff + -/* @jsxRuntime automatic @jsxImportSource react */ + -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime' + +/* @jsxRuntime automatic @jsxImportSource preact */ + +import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from 'preact/jsx-runtime' + ``` + +
    + +* `jsxRuntime` (`'automatic'` or `'classic'`, default: `'automatic'`) + — JSX runtime to use; + the automatic runtime compiles to `import _jsx from + '$importSource/jsx-runtime'\n_jsx('p')`; + the classic runtime compiles to calls such as `h('p')` + + > 👉 **Note**: support for the classic runtime is deprecated and will + > likely be removed in the next major version. + +
    Expand example + + If `file` is the contents of `example.mdx` from [§ Use][use], then: + + ```tsx + compile(file, {jsxRuntime: 'classic'}) + ``` + + …yields this difference: + + ```diff + -/* @jsxRuntime automatic @jsxImportSource react */ + -import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime' + +/* @jsxRuntime classic @jsx React.createElement @jsxFrag React.Fragment */ + +import React from 'react' + + export function Thing() { + - return _jsx(_Fragment, {children: 'World'}) + + return React.createElement(React.Fragment, null, 'World!') + } + … + ``` + +
    + +* `outputFormat` (`'function-body'` or `'program'`, default: `'program'`) + — output format to generate; + in most cases `'program'` should be used, it results in a whole program; + internally [`evaluate`][api-evaluate] uses `'function-body'` to compile to + code that can be passed to [`run`][api-run]; + in some cases, you might want to do what `evaluate` does in separate steps + yourself, such as when compiling on the server and running on the client. + +
    Expand example + + With a module `example.js`: + + ```tsx + import {compile} from '@mdx-js/mdx' + + const code = 'export const no = 3.14\n\n# hi {no}' + + console.log(String(await compile(code, {outputFormat: 'program'}))) // Default. + console.log(String(await compile(code, {outputFormat: 'function-body'}))) + ``` + + …yields: + + ```tsx + /* @jsxRuntime automatic @jsxImportSource react */ + import {jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime' + export const no = 3.14 + function _createMdxContent(props) { /* … */ } + export default function MDXContent(props = {}) { /* … */ } + ``` + + ```tsx + const {Fragment: _Fragment, jsx: _jsx} = arguments[0] + const no = 3.14 + function _createMdxContent(props) { /* … */ } + function MDXContent(props = {}) { /* … */ } + return {no, default: MDXContent} + ``` - function _createMdxContent(props) { - const _components = { - h1: 'h1', - + ..._provideComponents(), - ...props.components - } - return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]}) + The `'program'` format will use import statements to import the runtime (and + optionally provider) and use an export statement to yield the `MDXContent` + component. + + The `'function-body'` format will get the runtime (and optionally provider) + from `arguments[0]`, rewrite export statements, and use a return statement to + yield what was exported. + +
    + +* `mdExtensions` (`Array`, default: `['.md', '.markdown', '.mdown', + '.mkdn', '.mkd', '.mdwn', '.mkdown', '.ron']`) + — list of markdown extensions, with dot + affects [§ Integrations][integrations] + +* `mdxExtensions` (`Array`, default: `['.mdx']`) + — list of MDX extensions, with dot; + affects [§ Integrations][integrations] + +* `pragma` (`string`, default: `'React.createElement'`) + — pragma for JSX, used in the classic runtime as an identifier for function + calls: `` to `React.createElement('x')`; + when changing this, you should also define `pragmaFrag` and + `pragmaImportSource` too + + > 👉 **Note**: support for the classic runtime is deprecated and will + > likely be removed in the next major version. + +
    Expand example + + If `file` is the contents of `example.mdx` from [§ Use][use], then: + + ```tsx + compile(file, { + jsxRuntime: 'classic', + pragma: 'preact.createElement', + pragmaFrag: 'preact.Fragment', + pragmaImportSource: 'preact/compat' + }) + ``` + + …yields this difference: + + ```diff + -/* @jsxRuntime classic @jsx React.createElement @jsxFrag React.Fragment */ + -import React from 'react' + +/* @jsxRuntime classic @jsx preact.createElement @jsxFrag preact.Fragment */ + +import preact from 'preact/compat' + + export function Thing() { + - return React.createElement(React.Fragment, null, 'World!') + + return preact.createElement(preact.Fragment, null, 'World!') + } + … + ``` + +
    + +* `pragmaFrag` (`string`, default: `'React.Fragment'`) + — pragma for fragment symbol, used in the classic runtime as an identifier + for unnamed calls: `<>` to `React.createElement(React.Fragment)`; + when changing this, you should also define `pragma` and `pragmaImportSource` + too + + > 👉 **Note**: support for the classic runtime is deprecated and will + > likely be removed in the next major version. + +* `pragmaImportSource` (`string`, default: `'react'`) + — where to import the identifier of `pragma` from, used in the classic + runtime; + to illustrate, when `pragma` is `'a.b'` and `pragmaImportSource` is `'c'` + the following will be generated: `import a from 'c'` and things such as + `a.b('h1', {})`; + when changing this, you should also define `pragma` and `pragmaFrag` too + + > 👉 **Note**: support for the classic runtime is deprecated and will + > likely be removed in the next major version. + +* `providerImportSource` (`string`, optional, example: `'@mdx-js/react'`) + — place to import a provider from; + normally it’s used for runtimes that support context (React, Preact), but + it can be used to inject components into the compiled code; + the module must export and identifier `useMDXComponents` which is called + without arguments to get an object of components (see + [`UseMdxComponents`][api-use-mdx-components]) + +
    Expand example + + If `file` is the contents of `example.mdx` from [§ Use][use], then: + + ```tsx + compile(file, {providerImportSource: '@mdx-js/react'}) + ``` + + …yields this difference: + + ```diff + /* @jsxRuntime automatic @jsxImportSource react */ + import {Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs} from 'react/jsx-runtime' + +import {useMDXComponents as _provideComponents} from '@mdx-js/react' + + export function Thing() { + return _jsx(_Fragment, {children: 'World'}) + } + + function _createMdxContent(props) { + const _components = { + h1: 'h1', + + ..._provideComponents(), + ...props.components } + return _jsxs(_components.h1, {children: ['Hello ', _jsx(Thing, {})]}) + } + + export default function MDXContent(props = {}) { + - const {wrapper: MDXLayout} = props.components || {} + + const {wrapper: MDXLayout} = { + + ..._provideComponents(), + + ...props.components + + } + + return MDXLayout + ? _jsx(MDXLayout, {...props, children: _jsx(_createMdxContent, {})}) + : _createMdxContent() + ``` - export default function MDXContent(props = {}) { - - const {wrapper: MDXLayout} = props.components || {} - + const {wrapper: MDXLayout} = { - + ..._provideComponents(), - + ...props.components - + } - - return MDXLayout - ? _jsx(MDXLayout, {...props, children: _jsx(_createMdxContent, {})}) - : _createMdxContent() - ``` - -
    -* `recmaPlugins` ([`PluggableList` from `unified`][unified-pluggable-list], - optional) - — list of recma plugins; - this is a new ecosystem, currently in beta, to transform [esast][] trees - (JavaScript) - -
    Expand example - - ```tsx - import recmaMdxIsMdxComponent from 'recma-mdx-is-mdx-component' - - await compile(file, {recmaPlugins: [recmaMdxIsMdxComponent]}) - ``` - -
    -* `rehypePlugins` ([`PluggableList` from `unified`][unified-pluggable-list], - optional) - — list of [rehype plugins][rehype-plugins] - -
    Expand example - - ```tsx - import rehypeKatex from 'rehype-katex' // Render math with KaTeX. - import remarkMath from 'remark-math' // Support math like `$so$`. - - await compile(file, {rehypePlugins: [rehypeKatex], remarkPlugins: [remarkMath]}) - - await compile(file, { - // A plugin with options: - rehypePlugins: [[rehypeKatex, {strict: true, throwOnError: true}]], - remarkPlugins: [remarkMath] - }) - ``` - -
    -* `remarkPlugins` ([`PluggableList` from `unified`][unified-pluggable-list], - optional) - — list of [remark plugins][remark-plugins] - -
    Expand example - - ```tsx - import remarkFrontmatter from 'remark-frontmatter' // YAML and such. - import remarkGfm from 'remark-gfm' // Tables, footnotes, strikethrough, task lists, literal URLs. - - await compile(file, {remarkPlugins: [remarkGfm]}) // One plugin. - await compile(file, {remarkPlugins: [[remarkFrontmatter, 'toml']]}) // A plugin with options. - await compile(file, {remarkPlugins: [remarkGfm, remarkFrontmatter]}) // Two plugins. - await compile(file, {remarkPlugins: [[remarkGfm, {singleTilde: false}], remarkFrontmatter]}) // Two plugins, first w/ options. - ``` - -
    -* `remarkRehypeOptions` ([`Options` from - `remark-rehype`][remark-rehype-options], optional) - — options to pass through to `remark-rehype`; - the option `allowDangerousHtml` will always be set to `true` and the MDX - nodes (see [`nodeTypes`][api-node-types]) are passed through; - In particular, you might want to pass configuration for footnotes if your - content is not in English - -
    Expand example - - ```tsx - compile({value: '…'}, {remarkRehypeOptions: {clobberPrefix: 'comment-1'}}) - ``` - -
    - -* `stylePropertyNameCase` (`'css'` or `'dom`, default: `'dom'`) - — casing to use for property names in `style` objects; - CSS casing is for example `background-color` and `-webkit-line-clamp`; - DOM casing is for example `backgroundColor` and `WebkitLineClamp`; - for JSX components written in MDX, the author has to be aware of which - framework they use and write code accordingly; - for AST nodes generated by this project, this option configures it -* `tableCellAlignToStyle` (`boolean`, default: `true`) - — turn obsolete `align` props on `td` and `th` into CSS `style` props +
    + +* `recmaPlugins` ([`PluggableList` from `unified`][unified-pluggable-list], + optional) + — list of recma plugins; + this is a new ecosystem, currently in beta, to transform [esast][] trees + (JavaScript) + +
    Expand example + + ```tsx + import recmaMdxIsMdxComponent from 'recma-mdx-is-mdx-component' + + await compile(file, {recmaPlugins: [recmaMdxIsMdxComponent]}) + ``` + +
    + +* `rehypePlugins` ([`PluggableList` from `unified`][unified-pluggable-list], + optional) + — list of [rehype plugins][rehype-plugins] + +
    Expand example + + ```tsx + import rehypeKatex from 'rehype-katex' // Render math with KaTeX. + import remarkMath from 'remark-math' // Support math like `$so$`. + + await compile(file, {rehypePlugins: [rehypeKatex], remarkPlugins: [remarkMath]}) + + await compile(file, { + // A plugin with options: + rehypePlugins: [[rehypeKatex, {strict: true, throwOnError: true}]], + remarkPlugins: [remarkMath] + }) + ``` + +
    + +* `remarkPlugins` ([`PluggableList` from `unified`][unified-pluggable-list], + optional) + — list of [remark plugins][remark-plugins] + +
    Expand example + + ```tsx + import remarkFrontmatter from 'remark-frontmatter' // YAML and such. + import remarkGfm from 'remark-gfm' // Tables, footnotes, strikethrough, task lists, literal URLs. + + await compile(file, {remarkPlugins: [remarkGfm]}) // One plugin. + await compile(file, {remarkPlugins: [[remarkFrontmatter, 'toml']]}) // A plugin with options. + await compile(file, {remarkPlugins: [remarkGfm, remarkFrontmatter]}) // Two plugins. + await compile(file, {remarkPlugins: [[remarkGfm, {singleTilde: false}], remarkFrontmatter]}) // Two plugins, first w/ options. + ``` + +
    + +* `remarkRehypeOptions` ([`Options` from + `remark-rehype`][remark-rehype-options], optional) + — options to pass through to `remark-rehype`; + the option `allowDangerousHtml` will always be set to `true` and the MDX + nodes (see [`nodeTypes`][api-node-types]) are passed through; + In particular, you might want to pass configuration for footnotes if your + content is not in English + +
    Expand example + + ```tsx + compile({value: '…'}, {remarkRehypeOptions: {clobberPrefix: 'comment-1'}}) + ``` + +
    + +* `stylePropertyNameCase` (`'css'` or `'dom`, default: `'dom'`) + — casing to use for property names in `style` objects; + CSS casing is for example `background-color` and `-webkit-line-clamp`; + DOM casing is for example `backgroundColor` and `WebkitLineClamp`; + for JSX components written in MDX, the author has to be aware of which + framework they use and write code accordingly; + for AST nodes generated by this project, this option configures it + +* `tableCellAlignToStyle` (`boolean`, default: `true`) + — turn obsolete `align` props on `td` and `th` into CSS `style` props ### `RunOptions` @@ -968,22 +1006,22 @@ matter). ###### Fields -* `Fragment` ([`Fragment`][api-fragment], **required**) - — symbol to use for fragments -* `baseUrl` (`URL` or `string`, optional, example: `import.meta.url`) - — use this URL as `import.meta.url` and resolve `import` and - `export … from` relative to it; - this option can also be given at compile time in `CompileOptions`; - you should pass this (likely at runtime), as you might get runtime errors - when using `import.meta.url` / `import` / `export … from ` otherwise -* `jsx` ([`Jsx`][api-jsx], optional) - — function to generate an element with static children in production mode -* `jsxDEV` ([`JsxDEV`][api-jsx-dev], optional) - — function to generate an element in development mode -* `jsxs` ([`Jsx`][api-jsx], optional) - — function to generate an element with dynamic children in production mode -* `useMDXComponents` ([`UseMdxComponents`][api-use-mdx-components], optional) - — function to get components from context +* `Fragment` ([`Fragment`][api-fragment], **required**) + — symbol to use for fragments +* `baseUrl` (`URL` or `string`, optional, example: `import.meta.url`) + — use this URL as `import.meta.url` and resolve `import` and + `export … from` relative to it; + this option can also be given at compile time in `CompileOptions`; + you should pass this (likely at runtime), as you might get runtime errors + when using `import.meta.url` / `import` / `export … from ` otherwise +* `jsx` ([`Jsx`][api-jsx], optional) + — function to generate an element with static children in production mode +* `jsxDEV` ([`JsxDev`][api-jsx-dev], optional) + — function to generate an element in development mode +* `jsxs` ([`Jsx`][api-jsx], optional) + — function to generate an element with dynamic children in production mode +* `useMDXComponents` ([`UseMdxComponents`][api-use-mdx-components], optional) + — function to get components from context ###### Examples @@ -1054,15 +1092,15 @@ what unified does: please read through the [`unifiedjs/unified`][unified] readme know about unified: [`core.js#L65`][core]. The processor goes through these steps: -1. parse MDX (serialized markdown with embedded JSX, ESM, and expressions) - to mdast (markdown syntax tree) -2. transform through remark (markdown ecosystem) -3. transform mdast to hast (HTML syntax tree) -4. transform through rehype (HTML ecosystem) -5. transform hast to esast (JS syntax tree) -6. do the work needed to get a component -7. transform through recma (JS ecosystem) -8. serialize esast as JavaScript +1. parse MDX (serialized markdown with embedded JSX, ESM, and expressions) + to mdast (markdown syntax tree) +2. transform through remark (markdown ecosystem) +3. transform mdast to hast (HTML syntax tree) +4. transform through rehype (HTML ecosystem) +5. transform hast to esast (JS syntax tree) +6. do the work needed to get a component +7. transform through recma (JS ecosystem) +8. serialize esast as JavaScript The *input* is MDX (serialized markdown with embedded JSX, ESM, and expressions). @@ -1167,8 +1205,6 @@ abide by its terms. [npm]: https://docs.npmjs.com/cli/install -[yarn]: https://classic.yarnpkg.com/docs/cli/add/ - [contribute]: https://mdxjs.com/community/contribute/ [support]: https://mdxjs.com/community/support/ @@ -1179,16 +1215,6 @@ abide by its terms. [vercel]: https://vercel.com -[compile]: #compilefile-options - -[compile-sync]: #compilesyncfile-options - -[eval]: #evaluatefile-options - -[run]: #runfunctionbody-options - -[create-processor]: #createprocessoroptions - [source-map]: https://github.com/mozilla/source-map [vfile]: https://github.com/vfile/vfile @@ -1197,16 +1223,12 @@ abide by its terms. [rehype-plugins]: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins -[remark-rehype]: https://github.com/remarkjs/remark-rehype - [mdx-syntax]: https://mdxjs.com/docs/what-is-mdx/#mdx-syntax [use]: #use [unified]: https://github.com/unifiedjs/unified -[processor]: https://github.com/unifiedjs/unified#processor - [core]: https://github.com/mdx-js/mdx/blob/main/packages/mdx/lib/core.js#L65 [micromark]: https://github.com/micromark/micromark diff --git a/packages/node-loader/readme.md b/packages/node-loader/readme.md index b3ac33e2f..a27c0c781 100644 --- a/packages/node-loader/readme.md +++ b/packages/node-loader/readme.md @@ -13,16 +13,19 @@ Node.js hooks (also knows as loaders) for MDX. ## Contents -* [What is this?](#what-is-this) -* [When should I use this?](#when-should-i-use-this) -* [Install](#install) -* [Use](#use) -* [API](#api) - * [`createLoader(options?)`](#createloaderoptions) -* [Types](#types) -* [Security](#security) -* [Contribute](#contribute) -* [License](#license) +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`createLoader(options?)`](#createloaderoptions) + * [`load`](#load) + * [`Options`](#options) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Contribute](#contribute) +* [License](#license) ## What is this? @@ -118,8 +121,8 @@ Create Node.js hooks to handle markdown and MDX. ###### Parameters -* `options` ([`Options`][api-options], optional) - — configuration +* `options` ([`Options`][api-options], optional) + — configuration ###### Returns @@ -197,8 +200,6 @@ abide by its terms. [npm]: https://docs.npmjs.com/cli/install -[yarn]: https://classic.yarnpkg.com/docs/cli/add/ - [contribute]: https://mdxjs.com/community/contribute/ [support]: https://mdxjs.com/community/support/ @@ -209,8 +210,6 @@ abide by its terms. [author]: https://wooorm.com -[loader]: https://nodejs.org/api/esm.html#esm_loaders - [integrations]: https://mdxjs.com/getting-started/#integrations [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c @@ -221,8 +220,6 @@ abide by its terms. [typescript]: https://www.typescriptlang.org -[node-loader-core]: https://github.com/node-loader/node-loader-core - [compile-options]: https://mdxjs.com/packages/mdx/#compileoptions [node-load]: https://nodejs.org/api/module.html#loadurl-context-nextload diff --git a/packages/preact/readme.md b/packages/preact/readme.md index 90387cdbf..60d4aa02d 100644 --- a/packages/preact/readme.md +++ b/packages/preact/readme.md @@ -14,17 +14,20 @@ Preact context for MDX. ## Contents -* [What is this?](#what-is-this) -* [When should I use this?](#when-should-i-use-this) -* [Install](#install) -* [Use](#use) -* [API](#api) - * [`MDXProvider(props?)`](#mdxproviderprops) - * [`useMDXComponents(components?)`](#usemdxcomponentscomponents) -* [Types](#types) -* [Security](#security) -* [Contribute](#contribute) -* [License](#license) +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`MDXProvider(props?)`](#mdxproviderprops) + * [`useMDXComponents(components?)`](#usemdxcomponentscomponents) + * [`MergeComponents`](#mergecomponents) + * [`Props`](#props) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Contribute](#contribute) +* [License](#license) ## What is this? @@ -111,8 +114,8 @@ Provider for MDX context. ###### Parameters -* `props` ([`Props`][api-props]) - — configuration +* `props` ([`Props`][api-props]) + — configuration ##### Returns @@ -124,9 +127,9 @@ Get current components from the MDX Context. ###### Parameters -* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components] - or [`MergeComponents`][api-merge-components], optional) - — additional components to use or a function that creates them +* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components] + or [`MergeComponents`][api-merge-components], optional) + — additional components to use or a function that creates them ###### Returns @@ -139,8 +142,8 @@ Custom merge function (TypeScript type). ###### Parameters -* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components]) - — current components from the context +* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components]) + — current components from the context ###### Returns @@ -153,14 +156,14 @@ Configuration for `MDXProvider` (TypeScript type). ###### Fields -* `children` ([`ComponentChildren` from `preact`][preact-component-children], - optional) - — children -* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components] - or [`MergeComponents`][api-merge-components], optional) - — additional components to use or a function that creates them -* `disableParentContext` (`boolean`, default: `false`) - — turn off outer component context +* `children` ([`ComponentChildren` from `preact`][preact-component-children], + optional) + — children +* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components] + or [`MergeComponents`][api-merge-components], optional) + — additional components to use or a function that creates them +* `disableParentContext` (`boolean`, default: `false`) + — turn off outer component context ## Types diff --git a/packages/react/readme.md b/packages/react/readme.md index c231ab229..ec0d3514a 100644 --- a/packages/react/readme.md +++ b/packages/react/readme.md @@ -14,17 +14,20 @@ React context for MDX. ## Contents -* [What is this?](#what-is-this) -* [When should I use this?](#when-should-i-use-this) -* [Install](#install) -* [Use](#use) -* [API](#api) - * [`MDXProvider(props?)`](#mdxproviderprops) - * [`useMDXComponents(components?)`](#usemdxcomponentscomponents) -* [Types](#types) -* [Security](#security) -* [Contribute](#contribute) -* [License](#license) +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`MDXProvider(props?)`](#mdxproviderprops) + * [`useMDXComponents(components?)`](#usemdxcomponentscomponents) + * [`MergeComponents`](#mergecomponents) + * [`Props`](#props) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Contribute](#contribute) +* [License](#license) ## What is this? @@ -37,6 +40,10 @@ This package is **not needed** for MDX to work with React. See [¶ MDX provider in § Using MDX][use-provider] for when and how to use an MDX provider. +If you use Next.js, **do not use this**. +Add an `mdx-components.tsx` (in `src/` or `/`) file instead. +See [Configuring MDX on `nextjs.org`][next-configuring-mdx] for more info. + ## Install This package is [ESM only][esm]. @@ -111,8 +118,8 @@ Provider for MDX context. ###### Parameters -* `props` ([`Props`][api-props]) - — configuration +* `props` ([`Props`][api-props]) + — configuration ##### Returns @@ -124,9 +131,9 @@ Get current components from the MDX Context. ###### Parameters -* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components] - or [`MergeComponents`][api-merge-components], optional) - — additional components to use or a function that creates them +* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components] + or [`MergeComponents`][api-merge-components], optional) + — additional components to use or a function that creates them ###### Returns @@ -139,8 +146,8 @@ Custom merge function (TypeScript type). ###### Parameters -* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components]) - — current components from the context +* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components]) + — current components from the context ###### Returns @@ -153,14 +160,14 @@ Configuration for `MDXProvider` (TypeScript type). ###### Fields -* `children` ([`ReactNode` from `react`][react-node], - optional) - — children -* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components] - or [`MergeComponents`][api-merge-components], optional) - — additional components to use or a function that creates them -* `disableParentContext` (`boolean`, default: `false`) - — turn off outer component context +* `children` ([`ReactNode` from `react`][react-node], + optional) + — children +* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components] + or [`MergeComponents`][api-merge-components], optional) + — additional components to use or a function that creates them +* `disableParentContext` (`boolean`, default: `false`) + — turn off outer component context ## Types @@ -253,6 +260,8 @@ abide by its terms. [react-node]: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/HEAD/types/react/index.d.ts#L244 +[next-configuring-mdx]: https://nextjs.org/docs/pages/building-your-application/configuring/mdx + [api-mdx-provider]: #mdxproviderprops [api-merge-components]: #mergecomponents diff --git a/packages/remark-mdx/readme.md b/packages/remark-mdx/readme.md index 72c88eabb..12666ce8b 100644 --- a/packages/remark-mdx/readme.md +++ b/packages/remark-mdx/readme.md @@ -14,18 +14,23 @@ remark plugin to support the MDX syntax (JSX, export/import, expressions). ## Contents -* [What is this?](#what-is-this) -* [When should I use this?](#when-should-i-use-this) -* [Install](#install) -* [Use](#use) -* [API](#api) - * [`unified().use(remarkMdx)`](#unifieduseremarkmdx) -* [Syntax](#syntax) -* [Syntax tree](#syntax-tree) -* [Types](#types) -* [Security](#security) -* [Contribute](#contribute) -* [License](#license) +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`unified().use(remarkMdx[, options])`](#unifieduseremarkmdx-options) + * [`Options`](#options) +* [Authoring](#authoring) +* [HTML](#html) +* [Syntax](#syntax) +* [Syntax tree](#syntax-tree) +* [Errors](#errors) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Contribute](#contribute) +* [License](#license) ## What is this? @@ -112,8 +117,8 @@ from 'y'`; and expressions: `{1 + 1}`). ###### Parameters -* `options` ([`Options`][api-options], optional) - — configuration +* `options` ([`Options`][api-options], optional) + — configuration ###### Returns @@ -125,22 +130,22 @@ Configuration (TypeScript type). ###### Fields -* `acornOptions` ([`AcornOptions`][acorn-options], default: - `{ecmaVersion: 2024, locations: true, sourceType: 'module'}`) - — configuration for acorn; all fields except `locations` can be set -* `printWidth` (`number`, default: `Infinity`) - — try and wrap syntax at this width; - when set to a finite number (say, `80`), the formatter will print - attributes on separate lines when a tag doesn’t fit on one line; - the normal behavior is to print attributes with spaces between them instead - of line endings -* `quote` (`'"'` or `"'"`, default: `'"'`) - — preferred quote to use around attribute values -* `quoteSmart` (`boolean`, default: `false`) - — use the other quote if that results in less bytes -* `tightSelfClosing` (`boolean`, default: `false`) - — do not use an extra space when closing self-closing elements: `` - instead of `` +* `acornOptions` ([`AcornOptions`][acorn-options], default: + `{ecmaVersion: 2024, locations: true, sourceType: 'module'}`) + — configuration for acorn; all fields except `locations` can be set +* `printWidth` (`number`, default: `Infinity`) + — try and wrap syntax at this width; + when set to a finite number (say, `80`), the formatter will print + attributes on separate lines when a tag doesn’t fit on one line; + the normal behavior is to print attributes with spaces between them instead + of line endings +* `quote` (`'"'` or `"'"`, default: `'"'`) + — preferred quote to use around attribute values +* `quoteSmart` (`boolean`, default: `false`) + — use the other quote if that results in less bytes +* `tightSelfClosing` (`boolean`, default: `false`) + — do not use an extra space when closing self-closing elements: `` + instead of `` @@ -148,10 +153,10 @@ Configuration (TypeScript type). For recommendations on how to author MDX, see each corresponding readme: -* [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#authoring) -* [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#authoring) -* [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#authoring) -* [CommonMark features not in MDX](https://github.com/micromark/micromark-extension-mdx-md#authoring) +* [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#authoring) +* [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#authoring) +* [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#authoring) +* [CommonMark features not in MDX](https://github.com/micromark/micromark-extension-mdx-md#authoring) ## HTML @@ -165,28 +170,28 @@ You can enable passing MDX through to hast by configuring For info on the syntax of these features, see each corresponding readme: -* [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#syntax) -* [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#syntax) -* [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#syntax) -* CommonMark features not in MDX: n/a +* [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#syntax) +* [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#syntax) +* [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#syntax) +* CommonMark features not in MDX: n/a ## Syntax tree For info on the syntax tree of these features, see each corresponding readme: -* [ESM](https://github.com/syntax-tree/mdast-util-mdxjs-esm#syntax-tree) -* [JSX](https://github.com/syntax-tree/mdast-util-mdx-jsx#syntax-tree) -* [expressions](https://github.com/syntax-tree/mdast-util-mdx-expression#syntax-tree) -* CommonMark features not in MDX: n/a +* [ESM](https://github.com/syntax-tree/mdast-util-mdxjs-esm#syntax-tree) +* [JSX](https://github.com/syntax-tree/mdast-util-mdx-jsx#syntax-tree) +* [expressions](https://github.com/syntax-tree/mdast-util-mdx-expression#syntax-tree) +* CommonMark features not in MDX: n/a ## Errors For info on what errors are thrown, see each corresponding readme: -* [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#errors) -* [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#errors) -* [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#errors) -* CommonMark features not in MDX: n/a +* [ESM](https://github.com/micromark/micromark-extension-mdxjs-esm#errors) +* [JSX](https://github.com/micromark/micromark-extension-mdx-jsx#errors) +* [expressions](https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#errors) +* CommonMark features not in MDX: n/a ## Types @@ -272,8 +277,6 @@ abide by its terms. [npm]: https://docs.npmjs.com/cli/install -[yarn]: https://classic.yarnpkg.com/docs/cli/add/ - [contribute]: https://mdxjs.com/community/contribute/ [support]: https://mdxjs.com/community/support/ @@ -284,8 +287,6 @@ abide by its terms. [author]: https://wooorm.com -[create-plugin]: https://unifiedjs.com/learn/guide/create-a-plugin/ - [integrations]: https://mdxjs.com/getting-started/#integrations [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c diff --git a/packages/rollup/readme.md b/packages/rollup/readme.md index ba624a011..e39e27d5b 100644 --- a/packages/rollup/readme.md +++ b/packages/rollup/readme.md @@ -13,15 +13,20 @@ Rollup (and Vite) plugin for MDX. ## Contents -* [What is this?](#what-is-this) -* [When should I use this?](#when-should-i-use-this) -* [Install](#install) -* [Use](#use) -* [API](#api) -* [Types](#types) -* [Security](#security) -* [Contribute](#contribute) -* [License](#license) +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`mdx(options?)`](#mdxoptions) + * [`Options`](#options) +* [Examples](#examples) + * [Combine with Babel](#combine-with-babel) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Contribute](#contribute) +* [License](#license) ## What is this? @@ -59,9 +64,7 @@ const config = { // … plugins: [ // … - mdx({ - /* Options… */ - }) + mdx({/* jsxImportSource: …, otherOptions… */}) ] } @@ -81,8 +84,8 @@ Plugin to compile MDX w/ [rollup][]. ###### Parameters -* `options` ([`Options`][api-options], optional) - — configuration +* `options` ([`Options`][api-options], optional) + — configuration ###### Returns @@ -103,10 +106,10 @@ There are also two additional options: ###### Fields -* `exclude` (`Array`, `RegExp`, or `string`, optional) - — [picomatch][] patterns to exclude -* `include` (`Array`, `RegExp`, or `string`, optional) - — [picomatch][] patterns to include +* `exclude` (`Array`, `RegExp`, or `string`, optional) + — [picomatch][] patterns to exclude +* `include` (`Array`, `RegExp`, or `string`, optional) + — [picomatch][] patterns to include ## Examples @@ -124,9 +127,7 @@ const config = { // … plugins: [ // … - mdx({ - /* Options… */ - }), + mdx({/* jsxImportSource: …, otherOptions… */}), babel({ // Also run on what used to be `.mdx` (but is now JS): extensions: ['.js', '.jsx', '.cjs', '.mjs', '.md', '.mdx'] @@ -223,8 +224,6 @@ abide by its terms. [vite]: https://mdxjs.com/getting-started/#vite -[wmr]: https://mdxjs.com/getting-started/#wmr - -[api-mdx]: #mdx +[api-mdx]: #mdxoptions [api-options]: #options diff --git a/packages/vue/readme.md b/packages/vue/readme.md index edd7c76ee..db4faad6d 100644 --- a/packages/vue/readme.md +++ b/packages/vue/readme.md @@ -14,17 +14,19 @@ Vue context for MDX. ## Contents -* [What is this?](#what-is-this) -* [When should I use this?](#when-should-i-use-this) -* [Install](#install) -* [Use](#use) -* [API](#api) - * [`MDXProvider(props?)`](#mdxproviderprops) - * [`useMDXComponents()`](#usemdxcomponents) -* [Types](#types) -* [Security](#security) -* [Contribute](#contribute) -* [License](#license) +* [What is this?](#what-is-this) +* [When should I use this?](#when-should-i-use-this) +* [Install](#install) +* [Use](#use) +* [API](#api) + * [`MDXProvider(props?)`](#mdxproviderprops) + * [`useMDXComponents(components?)`](#usemdxcomponentscomponents) + * [`Props`](#props) +* [Types](#types) +* [Compatibility](#compatibility) +* [Security](#security) +* [Contribute](#contribute) +* [License](#license) ## What is this? @@ -128,9 +130,9 @@ Configuration for `MDXProvider` (TypeScript type). ###### Fields -* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components], - optional) - — additional components to use +* `components` ([`MDXComponents` from `mdx/types.js`][mdx-types-components], + optional) + — additional components to use ## Types @@ -196,8 +198,6 @@ abide by its terms. [npm]: https://docs.npmjs.com/cli/install -[yarn]: https://classic.yarnpkg.com/docs/cli/add/ - [contribute]: https://mdxjs.com/community/contribute/ [support]: https://mdxjs.com/community/support/ diff --git a/vercel.json b/vercel.json index 9135fd52f..bf13a8075 100644 --- a/vercel.json +++ b/vercel.json @@ -75,7 +75,7 @@ "source": "/editors/" }, { - "destination": "/docs/getting-started/#create-react-app-cra", + "destination": "/docs/getting-started/#vite", "source": "/getting-started/create-react-app/" }, { @@ -91,7 +91,7 @@ "source": "/getting-started/parcel/" }, { - "destination": "/docs/getting-started/#react-static", + "destination": "/docs/getting-started/#vite", "source": "/getting-started/react-static/" }, {