storybookjs · yannbf · Jan 3, 2024 · Dec 21, 2023 · Dec 22, 2023 · Dec 28, 2023
diff --git a/MIGRATION.md b/MIGRATION.md
@@ -2,6 +2,10 @@
 
 - [From version 7.x to 8.0.0](#from-version-7x-to-800)
   - [Implicit actions can not be used during rendering (for example in the play function)](#implicit-actions-can-not-be-used-during-rendering-for-example-in-the-play-function)
+  - [MDX related changes](#mdx-related-changes)
+    - [MDX is upgraded to v3](#mdx-is-upgraded-to-v3)
+    - [Dropping support for \*.stories.mdx (CSF in MDX) format](#dropping-support-for-storiesmdx-csf-in-mdx-format)
+    - [Dropping support for id, name and story in Story block](#dropping-support-for-id-name-and-story-in-story-block)
   - [Core changes](#core-changes)
     - [Dropping support for Node.js 16](#dropping-support-for-nodejs-16)
     - [Autotitle breaking fixes](#autotitle-breaking-fixes)
@@ -380,6 +384,24 @@ To summarize:
 - This allows users and (test) integrators to run or build storybook without docgen, boosting the user performance and allows tools to give quicker feedback.
 - This will make sure that we can one day lazy load docgen, without changing how stories are rendered.
 
+### MDX related changes
+
+#### MDX is upgraded to v3
+
+Storybook now uses MDX3 under the hood. This change contains many improvements and a few small breaking changes that possibly won't affect you. However we recommend checking the [migration notes from MDX here](https://mdxjs.com/blog/v3/).
+
+#### Dropping support for *.stories.mdx (CSF in MDX) format
+
+In Storybook 7, we deprecated the ability of using MDX both for documentation and for defining stories in the same .stories.mdx file. It is now removed, and Storybook won't support .stories.mdx files anymore. We provide migration scripts to help you onto the new format.
+
+Alongside with this change, the `jsxOptions` configuration was removed as it is not used anymore.
+
+[More info here](https://storybook.js.org/docs/writing-docs/mdx#automigration).
+
+#### Dropping support for id, name and story in Story block
+
+Referencing stories by `id`, `name` or `story` in the Story block is not possible anymore. [More info here](#story-block).
+
 ### Core changes
 
 #### Dropping support for Node.js 16

diff --git a/code/addons/controls/README.md b/code/addons/controls/README.md
@@ -176,38 +176,4 @@ Like [story parameters](https://storybook.js.org/docs/react/writing-stories/para
 
 ### How do controls work with MDX?
 
-MDX compiles to component story format (CSF) under the hood, so there's a direct mapping for every example above using the `args` and `argTypes` props.
-
-Consider this example in CSF:
-
-```js
-import { Button } from './Button';
-export default {
-  title: 'Button',
-  component: Button,
-  argTypes: {
-    background: { control: 'color' },
-  },
-};
-
-const Template = (args) => <Button {...args} />;
-export const Basic = Template.bind({});
-Basic.args = { label: 'hello', background: '#ff0' };
-```
-
-Here's the MDX equivalent:
-
-```jsx
-import { Meta, Story } from '@storybook/addon-docs';
-import { Button } from './Button';
-
-<Meta title="Button" component={Button} argTypes={{ background: { control: 'color' } }} />
-
-export const Template = (args) => <Button {...args} />
-
-<Story name="Basic" args={{ label: 'hello', background: '#ff0' }}>
-  {Template.bind({})}
-</Story>
-```
-
-For more info, see a full [Controls example in MDX for Vue](https://raw.githubusercontent.com/storybookjs/storybook/next/code/examples/vue-kitchen-sink/src/stories/addon-controls.stories.mdx).
+When importing stories from your CSF file into MDX, controls will work the same way. See [the documentation](https://storybook.js.org/docs/writing-docs/mdx#basic-example) for examples.
diff --git a/code/addons/docs/README.md b/code/addons/docs/README.md
@@ -110,20 +110,6 @@ export default {
 };
 ```
 
-If using in conjunction with the [storyshots add-on](https://github.com/storybookjs/storybook/blob/next/code/addons/storyshots-core/README.md), you will need to
-configure Jest to transform MDX stories into something Storyshots can understand:
-
-Add the following to your Jest configuration:
-
-```json
-{
-  "transform": {
-    "^.+\\.[tj]sx?$": "babel-jest",
-    "^.+\\.mdx$": "@storybook/addon-docs/jest-transform-mdx"
-  }
-}
-```
-
 ### Be sure to check framework specific installation needs
 
 - [React](https://github.com/storybookjs/storybook/tree/next/code/addons/docs/react) (covered here)
@@ -143,7 +129,6 @@ export default {
     {
       name: '@storybook/addon-docs',
       options: {
-        jsxOptions: {},
         csfPluginOptions: null,
         mdxPluginOptions: {},
       },
@@ -152,8 +137,6 @@ export default {
 };
 ```
 
-`jsxOptions` are options that will be passed to `@babel/preset-react` for `.md` and `.mdx` files.
-
 `csfPluginOptions` is an object for configuring `@storybook/csf-plugin`. When set to `null` it tells docs not to run the `csf-plugin` at all, which can be used as an optimization, or if you're already using `csf-plugin` in your `main.js`.
 
 > With the release of version 7.0, it is no longer possible to import `.md` files directly into Storybook using the `transcludeMarkdown` [option](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#importing-plain-markdown-files-with-transcludemarkdown-has-changed). Instead, we recommend using the [`Markdown`](https://storybook.js.org/docs/react/api/doc-block-markdown) Doc Block for importing Markdown files into your Storybook documentation.

diff --git a/code/addons/docs/jest-transform-mdx.js b/code/addons/docs/jest-transform-mdx.js
diff --git a/code/addons/docs/package.json b/code/addons/docs/package.json
@@ -65,13 +65,13 @@
       "require": "./dist/shims/mdx-react-shim.js",
       "import": "./dist/shims/mdx-react-shim.mjs"
     },
+    "./mdx-loader": "./dist/mdx-loader.js",
     "./svelte/HOC.svelte": "./svelte/HOC.svelte",
     "./ember": "./ember/index.js",
     "./ember/index.js": "./ember/index.js",
     "./angular": "./angular/index.js",
     "./angular/index.js": "./angular/index.js",
     "./web-components/index.js": "./web-components/index.js",
-    "./jest-transform-mdx": "./jest-transform-mdx.js",
     "./package.json": "./package.json"
   },
   "main": "dist/index.js",
@@ -98,15 +98,14 @@
     "prep": "node --loader ../../../scripts/node_modules/esbuild-register/loader.js -r ../../../scripts/node_modules/esbuild-register/register.js ../../../scripts/prepare/bundle.ts"
   },
   "dependencies": {
-    "@jest/transform": "^29.3.1",
-    "@mdx-js/react": "^2.1.5",
+    "@babel/core": "^7.12.3",
+    "@mdx-js/react": "^3.0.0",
     "@storybook/blocks": "workspace:*",
     "@storybook/client-logger": "workspace:*",
     "@storybook/components": "workspace:*",
     "@storybook/csf-plugin": "workspace:*",
     "@storybook/csf-tools": "workspace:*",
     "@storybook/global": "^5.0.0",
-    "@storybook/mdx2-csf": "^1.0.0",
     "@storybook/node-logger": "workspace:*",
     "@storybook/preview-api": "workspace:*",
     "@storybook/react-dom-shim": "workspace:*",
@@ -120,6 +119,7 @@
     "ts-dedent": "^2.0.0"
   },
   "devDependencies": {
+    "@mdx-js/mdx": "^3.0.0",
     "@rollup/pluginutils": "^5.0.2",
     "typescript": "^5.3.2",
     "vite": "^4.0.4"
@@ -133,10 +133,8 @@
       "./src/preset.ts",
       "./src/preview.ts",
       "./src/blocks.ts",
-      "./src/shims/mdx-react-shim.ts"
-    ],
-    "externals": [
-      "@storybook/mdx1-csf"
+      "./src/shims/mdx-react-shim.ts",
+      "./src/mdx-loader.ts"
     ]
   },
   "gitHead": "e6a7fd8a655c69780bc20b9749c2699e44beae17",