diff --git a/code/addons/themes/docs/getting-started/bootstrap.md b/code/addons/themes/docs/getting-started/bootstrap.md index a5070d6a3032..fd0a59d6fdce 100644 --- a/code/addons/themes/docs/getting-started/bootstrap.md +++ b/code/addons/themes/docs/getting-started/bootstrap.md @@ -4,7 +4,7 @@ -To get started, **install the package** as a dev dependency +To get started, **install the package** as a dev dependency. yarn: @@ -29,14 +29,11 @@ pnpm add -D @storybook/addon-themes Now, **include the addon** in your `.storybook/main.js` file. ```diff -module.exports = { - stories: [ - "../stories/**/*.stories.mdx", - "../stories/**/*.stories.@(js|jsx|ts|tsx)", - ], +export default { + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'], addons: [ - "@storybook/addon-essentials", -+ "@storybook/addon-themes" + '@storybook/addon-essentials', ++ '@storybook/addon-themes', ], }; ``` @@ -46,10 +43,10 @@ module.exports = { To give your stories access to Bootstrap's styles and JavaScript, import them into your `.storybook/preview.js` file. ```diff -import { Preview } from "@storybook/your-renderer"; +import { Preview } from '@storybook/your-renderer'; -+import "bootstrap/dist/css/bootstrap.min.css"; -+import "bootstrap/dist/js/bootstrap.bundle"; ++import 'bootstrap/dist/css/bootstrap.min.css'; ++import 'bootstrap/dist/js/bootstrap.bundle'; const preview: Preview = { parameters: { /* ... */ }, @@ -65,23 +62,23 @@ Bootstrap now supports light and dark color modes out of the box as well as the To enable switching between these modes in a click for your stories, use our `withThemeByDataAttribute` decorator by adding the following code to your `.storybook/preview.js` file. ```diff --import { Preview } from "@storybook/your-renderer"; -+import { Preview, Renderer } from "@storybook/your-renderer"; -+import { withThemeByDataAttribute } from "@storybook/addon-themes"; +-import { Preview } from '@storybook/your-renderer'; ++import { Preview, Renderer } from '@storybook/your-renderer'; ++import { withThemeByDataAttribute } from '@storybook/addon-themes'; -import "bootstrap/dist/css/bootstrap.min.css"; -import "bootstrap/dist/js/bootstrap.bundle"; +import 'bootstrap/dist/css/bootstrap.min.css'; +import 'bootstrap/dist/js/bootstrap.bundle'; const preview: Preview = { parameters: { /* ... */ }, + decorators: [ + withThemeByDataAttribute({ + themes: { -+ light: "light", -+ dark: "dark", ++ light: 'light', ++ dark: 'dark', + }, -+ defaultTheme: "light", -+ attributeName: "data-bs-theme", ++ defaultTheme: 'light', ++ attributeName: 'data-bs-theme', + }), + ] }; diff --git a/code/addons/themes/docs/getting-started/emotion.md b/code/addons/themes/docs/getting-started/emotion.md index 4d5118d0785d..1671b93b3583 100644 --- a/code/addons/themes/docs/getting-started/emotion.md +++ b/code/addons/themes/docs/getting-started/emotion.md @@ -4,7 +4,7 @@ -To get started, **install the package** as a dev dependency +To get started, **install the package** as a dev dependency. yarn: @@ -26,17 +26,14 @@ pnpm add -D @storybook/addon-themes ## 🧩 Register Addon -Now, **include the addon** in your `.storybook/main.js` file +Now, **include the addon** in your `.storybook/main.js` file. ```diff -module.exports = { - stories: [ - "../stories/**/*.stories.mdx", - "../stories/**/*.stories.@(js|jsx|ts|tsx)", - ], +export default { + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], addons: [ - "@storybook/addon-essentials", -+ "@storybook/addon-themes" + '@storybook/addon-essentials', ++ '@storybook/addon-themes', ], }; ``` @@ -45,14 +42,14 @@ module.exports = { Finally, provide your theme(s) and global styles component to your stories with our `withThemeFromJSXProvider` decorator. -Make the following changes to your `.storybook/preview.js` +Make the following changes to your `.storybook/preview.js`: ```diff --import { Preview } from "@storybook/your-renderer"; -+import { Preview, Renderer } from "@storybook/your-renderer"; -+import { withThemeFromJSXProvider } from "@storybook/addon-themes"; +-import { Preview } from '@storybook/your-renderer'; ++import { Preview, Renderer } from '@storybook/your-renderer'; ++import { withThemeFromJSXProvider } from '@storybook/addon-themes'; +import { ThemeProvider } from '@emotion/react'; -+import { GlobalStyles, lightTheme, darkTheme } from "../src/themes"; // import your custom theme configs ++import { GlobalStyles, lightTheme, darkTheme } from '../src/themes'; // Import your custom theme configs const preview: Preview = { @@ -63,7 +60,7 @@ const preview: Preview = { + light: lightTheme, + dark: darkTheme, + }, -+ defaultTheme: "light", ++ defaultTheme: 'light', + Provider: ThemeProvider, + GlobalStyles: GlobalStyles, + }), diff --git a/code/addons/themes/docs/getting-started/material-ui.md b/code/addons/themes/docs/getting-started/material-ui.md index 267705d29340..1b88fae1451a 100644 --- a/code/addons/themes/docs/getting-started/material-ui.md +++ b/code/addons/themes/docs/getting-started/material-ui.md @@ -4,7 +4,7 @@ -To get started, **install the package** as a dev dependency +To get started, **install the package** as a dev dependency. yarn: @@ -26,17 +26,14 @@ pnpm add -D @storybook/addon-themes ## 🧩 Register Addon -Now, **include the addon** in your `.storybook/main.js` file +Now, **include the addon** in your `.storybook/main.js` file. ```diff -module.exports = { - stories: [ - "../stories/**/*.stories.mdx", - "../stories/**/*.stories.@(js|jsx|ts|tsx)", - ], +export default { + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], addons: [ - "@storybook/addon-essentials", -+ "@storybook/addon-themes", + '@storybook/addon-essentials', ++ '@storybook/addon-themes', ], }; ``` @@ -48,14 +45,14 @@ module.exports = { These can be imported into your `.storybook/preview.js` file. ```diff -import { Preview } from "@storybook/your-renderer"; +import { Preview } from '@storybook/your-renderer'; +// Load Material UI fonts -+import "@fontsource/roboto/300.css"; -+import "@fontsource/roboto/400.css"; -+import "@fontsource/roboto/500.css"; -+import "@fontsource/roboto/700.css"; -+import "@fontsource/material-icons"; ++import '@fontsource/roboto/300.css'; ++import '@fontsource/roboto/400.css'; ++import '@fontsource/roboto/500.css'; ++import '@fontsource/roboto/700.css'; ++import '@fontsource/material-icons'; const preview: Preview = { parameters: { /* ... */ }, @@ -68,21 +65,21 @@ export default preview; While Material UI comes with a default theme that works out of the box. You can create your own theme(s) and provide them to your stories with our `withThemeFromJSXProvider` decorator. -Make the following changes to your `.storybook/preview.js` +Make the following changes to your `.storybook/preview.js`: ```diff --import { Preview } from "@storybook/your-renderer"; -+import { Preview, Renderer } from "@storybook/your-renderer"; -+import { withThemeFromJSXProvider } from "@storybook/addon-themes"; -+import { CssBaseline, ThemeProvider } from "@mui/material"; -+import { lightTheme, darkTheme } from "../src/themes"; // import your custom theme configs +-import { Preview } from '@storybook/your-renderer'; ++import { Preview, Renderer } from '@storybook/your-renderer'; ++import { withThemeFromJSXProvider } from '@storybook/addon-themes'; ++import { CssBaseline, ThemeProvider } from '@mui/material'; ++import { lightTheme, darkTheme } from '../src/themes'; // Import your custom theme configs // Load Roboto fonts -import "@fontsource/roboto/300.css"; -import "@fontsource/roboto/400.css"; -import "@fontsource/roboto/500.css"; -import "@fontsource/roboto/700.css"; -import "@fontsource/material-icons"; +import '@fontsource/roboto/300.css'; +import '@fontsource/roboto/400.css'; +import '@fontsource/roboto/500.css'; +import '@fontsource/roboto/700.css'; +import '@fontsource/material-icons'; const preview: Preview = { parameters: { /* ... */ }, @@ -92,7 +89,7 @@ const preview: Preview = { + light: lightTheme, + dark: darkTheme, + }, -+ defaultTheme: "light", ++ defaultTheme: 'light', + Provider: ThemeProvider, + GlobalStyles: CssBaseline, + }), diff --git a/code/addons/themes/docs/getting-started/styled-components.md b/code/addons/themes/docs/getting-started/styled-components.md index 514e95f25a85..e5e31361f121 100644 --- a/code/addons/themes/docs/getting-started/styled-components.md +++ b/code/addons/themes/docs/getting-started/styled-components.md @@ -4,7 +4,7 @@ -To get started, **install the package** as a dev dependency +To get started, **install the package** as a dev dependency. yarn: @@ -26,17 +26,14 @@ pnpm add -D @storybook/addon-themes ## 🧩 Register Addon -Now, **include the addon** in your `.storybook/main.js` file +Now, **include the addon** in your `.storybook/main.js` file. ```diff -module.exports = { - stories: [ - "../stories/**/*.stories.mdx", - "../stories/**/*.stories.@(js|jsx|ts|tsx)", - ], +export default { + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], addons: [ - "@storybook/addon-essentials", -+ "@storybook/addon-themes" + '@storybook/addon-essentials', ++ '@storybook/addon-themes', ], }; ``` @@ -45,14 +42,14 @@ module.exports = { Finally, provide your theme(s) and global styles component to your stories with our `withThemeFromJSXProvider` decorator. -Make the following changes to your `.storybook/preview.js` +Make the following changes to your `.storybook/preview.js`: ```diff --import { Preview } from "@storybook/your-renderer"; -+import { Preview, Renderer } from "@storybook/your-renderer"; -+import { withThemeFromJSXProvider } from "@storybook/addon-themes"; +-import { Preview } from '@storybook/your-renderer'; ++import { Preview, Renderer } from '@storybook/your-renderer'; ++import { withThemeFromJSXProvider } from '@storybook/addon-themes'; +import { ThemeProvider } from 'styled-components'; -+import { GlobalStyles, lightTheme, darkTheme } from "../src/themes"; // import your custom theme configs ++import { GlobalStyles, lightTheme, darkTheme } from '../src/themes'; // Import your custom theme configs const preview: Preview = { parameters: { /* ... */ }, @@ -62,7 +59,7 @@ const preview: Preview = { + light: lightTheme, + dark: darkTheme, + }, -+ defaultTheme: "light", ++ defaultTheme: 'light', + Provider: ThemeProvider, + GlobalStyles: GlobalStyles, + }), diff --git a/code/addons/themes/docs/getting-started/tailwind.md b/code/addons/themes/docs/getting-started/tailwind.md index 6156c45757a0..c5475c621550 100644 --- a/code/addons/themes/docs/getting-started/tailwind.md +++ b/code/addons/themes/docs/getting-started/tailwind.md @@ -4,7 +4,7 @@ -To get started, **install the package** as a dev dependency +To get started, **install the package** as a dev dependency. yarn: @@ -29,14 +29,11 @@ pnpm add -D @storybook/addon-themes Now, **include the addon** in your `.storybook/main.js` file. ```diff -module.exports = { - stories: [ - "../stories/**/*.stories.mdx", - "../stories/**/*.stories.@(js|jsx|ts|tsx)", - ], +export default { + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], addons: [ - "@storybook/addon-essentials", -+ "@storybook/addon-themes" + '@storybook/addon-essentials', ++ '@storybook/addon-themes', ], }; ``` @@ -46,9 +43,9 @@ module.exports = { To give your stories access to Tailwind styles, import them into your `.storybook/preview.js` file. ```diff -import { Preview } from "@storybook/your-renderer"; +import { Preview } from '@storybook/your-renderer'; -+import "../src/index.css"; ++import '../src/index.css'; const preview: Preview = { parameters: { /* ... */ }, @@ -64,11 +61,11 @@ Tailwind supports light and dark color modes out of the box. These modes can be To enable switching between these modes in a click for your stories, use our `withThemeByClassName` decorator by adding the following code to your `.storybook/preview.js` file. ```diff --import { Preview } from "@storybook/your-renderer"; -+import { Preview, Renderer } from "@storybook/your-renderer"; -+import { withThemeByClassName } from "@storybook/addon-themes"; +-import { Preview } from '@storybook/your-renderer'; ++import { Preview, Renderer } from '@storybook/your-renderer'; ++import { withThemeByClassName } from '@storybook/addon-themes'; -import "../src/index.css"; +import '../src/index.css'; const preview: Preview = { @@ -76,10 +73,10 @@ const preview: Preview = { + decorators: [ + withThemeByClassName({ + themes: { -+ light: "", -+ dark: "dark", ++ light: '', ++ dark: 'dark', + }, -+ defaultTheme: "light", ++ defaultTheme: 'light', + }), + ] }; @@ -92,11 +89,11 @@ export default preview; If you've configured Tailwind to toggle themes with a data attribute, use our `withThemeByDataAttribute` decorator by adding the following code to your `.storybook/preview.js` file. ```diff --import { Preview } from "@storybook/your-renderer"; -+import { Preview, Renderer } from "@storybook/your-renderer"; -+import { withThemeByDataAttribute } from "@storybook/addon-themes"; +-import { Preview } from '@storybook/your-renderer'; ++import { Preview, Renderer } from '@storybook/your-renderer'; ++import { withThemeByDataAttribute } from '@storybook/addon-themes'; -import "../src/index.css"; +import '../src/index.css'; const preview: Preview = { @@ -104,11 +101,11 @@ const preview: Preview = { + decorators: [ + withThemeByDataAttribute({ + themes: { -+ light: "light", -+ dark: "dark", ++ light: 'light', ++ dark: 'dark', + }, -+ defaultTheme: "light", -+ attributeName: "data-theme", ++ defaultTheme: 'light', ++ attributeName: 'data-theme', + }), + ] }; diff --git a/docs/api/main-config-stories.md b/docs/api/main-config-stories.md index b59d0cb93bf0..89b7051588ba 100644 --- a/docs/api/main-config-stories.md +++ b/docs/api/main-config-stories.md @@ -101,7 +101,7 @@ Where to start looking for story files, relative to the root of your project. Type: `string` -Default: `'**/*.@(mdx|stories.@(mdx|js|jsx|mjs|ts|tsx))'` +Default: `'**/*.@(mdx|stories.@(js|jsx|mjs|ts|tsx))'` A glob, relative to `StoriesSpecifier.directory` (with no leading `./`), that matches the filenames to load. diff --git a/docs/snippets/common/component-story-mdx-embed.mdx.mdx b/docs/snippets/common/component-story-mdx-embed.mdx.mdx deleted file mode 100644 index a87ba2dda8d1..000000000000 --- a/docs/snippets/common/component-story-mdx-embed.mdx.mdx +++ /dev/null @@ -1,11 +0,0 @@ -```md - - -import { Story } from '@storybook/addon-docs'; - -# Some header - -And Markdown here - - -``` \ No newline at end of file diff --git a/docs/snippets/common/component-story-mdx-reference-storyid.mdx.mdx b/docs/snippets/common/component-story-mdx-reference-storyid.mdx.mdx deleted file mode 100644 index d79599c9cecb..000000000000 --- a/docs/snippets/common/component-story-mdx-reference-storyid.mdx.mdx +++ /dev/null @@ -1,7 +0,0 @@ -```md - - -import { Story } from '@storybook/addon-docs'; - - -``` \ No newline at end of file diff --git a/docs/snippets/common/main-config-features-legacy-mdx-1.js.mdx b/docs/snippets/common/main-config-features-legacy-mdx-1.js.mdx deleted file mode 100644 index e961bf074cb3..000000000000 --- a/docs/snippets/common/main-config-features-legacy-mdx-1.js.mdx +++ /dev/null @@ -1,12 +0,0 @@ -```js -// .storybook/main.js - -export default { - // Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) - framework: '@storybook/your-framework', - stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], - features: { - legacyMdx1: true, // 👈 Enables MDX v1 support - }, -}; -``` diff --git a/docs/snippets/common/main-config-features-legacy-mdx-1.ts.mdx b/docs/snippets/common/main-config-features-legacy-mdx-1.ts.mdx deleted file mode 100644 index c983311700f4..000000000000 --- a/docs/snippets/common/main-config-features-legacy-mdx-1.ts.mdx +++ /dev/null @@ -1,16 +0,0 @@ -```ts -// .storybook/main.ts - -// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite) -import type { StorybookConfig } from '@storybook/your-framework'; - -const config: StorybookConfig = { - framework: '@storybook/your-framework', - stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], - features: { - legacyMdx1: true, // 👈 Enables MDX v1 support - }, -}; - -export default config; -``` diff --git a/docs/snippets/common/mdx-canvas-doc-block.mdx.mdx b/docs/snippets/common/mdx-canvas-doc-block.mdx.mdx deleted file mode 100644 index dbd2297f3da2..000000000000 --- a/docs/snippets/common/mdx-canvas-doc-block.mdx.mdx +++ /dev/null @@ -1,13 +0,0 @@ -```md - - -import { Canvas, Meta } from '@storybook/addon-docs'; - -import { ExampleComponent} from './ExampleComponent'; - - - - - - -``` \ No newline at end of file diff --git a/docs/snippets/common/mdx-changelog-stories.mdx.mdx b/docs/snippets/common/mdx-changelog-stories.mdx.mdx deleted file mode 100644 index bc0aeb2980a7..000000000000 --- a/docs/snippets/common/mdx-changelog-stories.mdx.mdx +++ /dev/null @@ -1,12 +0,0 @@ -```md - - - -import { Meta } from '@storybook/addon-docs'; - -import Changelog from '../CHANGELOG.md'; - - - - -``` \ No newline at end of file diff --git a/docs/snippets/common/my-component-with-story-content.mdx.mdx b/docs/snippets/common/my-component-with-story-content.mdx.mdx deleted file mode 100644 index 66451f49bbbf..000000000000 --- a/docs/snippets/common/my-component-with-story-content.mdx.mdx +++ /dev/null @@ -1,12 +0,0 @@ -```md - - -import { Canvas } from '@storybook/addon-docs'; - -import { MyComponent } from './MyComponent'; - - -

Some here

- -
-``` diff --git a/docs/snippets/common/storybook-automigration-mdx-legacy.npm.mdx b/docs/snippets/common/storybook-automigration-mdx-legacy.npm.mdx new file mode 100644 index 000000000000..b54577026015 --- /dev/null +++ b/docs/snippets/common/storybook-automigration-mdx-legacy.npm.mdx @@ -0,0 +1,3 @@ +```shell +npx storybook@latest automigrate mdx1to2 +``` diff --git a/docs/snippets/common/storybook-automigration-mdx-legacy.pnpm.mdx b/docs/snippets/common/storybook-automigration-mdx-legacy.pnpm.mdx new file mode 100644 index 000000000000..4c17825bf1a8 --- /dev/null +++ b/docs/snippets/common/storybook-automigration-mdx-legacy.pnpm.mdx @@ -0,0 +1,3 @@ +```shell +pnpm dlx storybook@latest automigrate mdx1to2 +``` diff --git a/docs/snippets/common/storybook-automigration-mdx-legacy.yarn.mdx b/docs/snippets/common/storybook-automigration-mdx-legacy.yarn.mdx new file mode 100644 index 000000000000..277d34f73467 --- /dev/null +++ b/docs/snippets/common/storybook-automigration-mdx-legacy.yarn.mdx @@ -0,0 +1,3 @@ +```shell +yarn dlx storybook@latest automigrate mdx1to2 +``` diff --git a/docs/snippets/common/storybook-main-register-essentials-addon.js.mdx b/docs/snippets/common/storybook-main-register-essentials-addon.js.mdx index 6e7e2fca09fe..ee4ecfbd706c 100644 --- a/docs/snippets/common/storybook-main-register-essentials-addon.js.mdx +++ b/docs/snippets/common/storybook-main-register-essentials-addon.js.mdx @@ -3,7 +3,7 @@ export default { framework: '@storybook/your-framework', - stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], addons: ['@storybook/addon-essentials'], // 👈 Register addon-essentials }; ``` diff --git a/docs/snippets/common/storybook-main-register-essentials-addon.ts.mdx b/docs/snippets/common/storybook-main-register-essentials-addon.ts.mdx index d4e42fd31129..88f505b62b7b 100644 --- a/docs/snippets/common/storybook-main-register-essentials-addon.ts.mdx +++ b/docs/snippets/common/storybook-main-register-essentials-addon.ts.mdx @@ -6,7 +6,7 @@ import type { StorybookConfig } from '@storybook/your-framework'; const config: StorybookConfig = { framework: '@storybook/your-framework', - stories: ['../src/**/*.stories.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], addons: ['@storybook/addon-essentials'], // 👈 Register addon-essentials }; diff --git a/docs/snippets/common/storybook-migration-mdx-stories.npm.mdx b/docs/snippets/common/storybook-migration-mdx-stories.npm.mdx new file mode 100644 index 000000000000..f2f2c30f2fac --- /dev/null +++ b/docs/snippets/common/storybook-migration-mdx-stories.npm.mdx @@ -0,0 +1,3 @@ +```shell +npx storybook@latest migrate mdx-to-csf --glob "src/**/*.stories.mdx” +``` diff --git a/docs/snippets/common/storybook-migration-mdx-stories.pnpm.mdx b/docs/snippets/common/storybook-migration-mdx-stories.pnpm.mdx new file mode 100644 index 000000000000..5f9ac39d6e7c --- /dev/null +++ b/docs/snippets/common/storybook-migration-mdx-stories.pnpm.mdx @@ -0,0 +1,3 @@ +```shell +pnpm dlx storybook@latest migrate mdx-to-csf --glob "src/**/*.stories.mdx” +``` diff --git a/docs/snippets/common/storybook-migration-mdx-stories.yarn.mdx b/docs/snippets/common/storybook-migration-mdx-stories.yarn.mdx new file mode 100644 index 000000000000..499212af80b1 --- /dev/null +++ b/docs/snippets/common/storybook-migration-mdx-stories.yarn.mdx @@ -0,0 +1,3 @@ +```shell +yarn dlx storybook@latest migrate mdx-to-csf --glob "src/**/*.stories.mdx” +``` diff --git a/docs/snippets/html/checkbox-story.mdx.mdx b/docs/snippets/html/checkbox-story.mdx.mdx deleted file mode 100644 index e81434c68848..000000000000 --- a/docs/snippets/html/checkbox-story.mdx.mdx +++ /dev/null @@ -1,45 +0,0 @@ -```md - - -import { Canvas, Meta, Story } from '@storybook/addon-docs'; - -export const Checkbox = (args) => ``; - - - -# Checkbox - -With `MDX`, we can define a story for `Checkbox` right in the middle of our -Markdown documentation. - - - - - - -``` diff --git a/docs/snippets/preact/histogram-story.mdx.mdx b/docs/snippets/preact/histogram-story.mdx.mdx deleted file mode 100644 index e0843151cc72..000000000000 --- a/docs/snippets/preact/histogram-story.mdx.mdx +++ /dev/null @@ -1,27 +0,0 @@ -```md - - -import { Canvas, Meta, Story } from '@storybook/addon-docs/'; - -import { Histogram } from './Histogram'; - - - - - - - } /> - -``` \ No newline at end of file diff --git a/docs/writing-docs/mdx.md b/docs/writing-docs/mdx.md index f7d22dd853d4..afc4c11a86b4 100644 --- a/docs/writing-docs/mdx.md +++ b/docs/writing-docs/mdx.md @@ -12,7 +12,7 @@ In addition, you can write pure documentation pages in MDX and add them to Story -Writing stories directly in MDX was deprecated in Storybook 7. Please reference the [previous documentation](../../../release-6-5/docs/writing-docs/mdx.md) for guidance on that feature. +Writing stories directly in MDX was removed in Storybook 8, and we're no longer supporting it. Please reference the [previous documentation](../../../release-6-5/docs/writing-docs/mdx.md) for guidance on that feature or [migrate](../migration-guide.md#storiesmdx-to-mdxcsf) to the new format. @@ -63,12 +63,6 @@ The first thing you'll notice is that the component documentation is divided int - **CSF** is great for succinctly defining stories (component examples). If you use TypeScript, it also provides type safety and auto-completion. - **MDX** is great for writing structured documentation and composing it with interactive JSX elements. - - -If you’re coming from a previous version of Storybook, you might be accustomed to using MDX both for **documentation** and for defining **stories** in the same `.stories.mdx` file. We’ve deprecated this functionality and plan to remove it in a future version of Storybook. We provide [migration](#automigration) scripts to help you onto the new format. - - - ### Anatomy of MDX Assuming you’re already familiar with writing stories with [CSF](../writing-stories/index.md), we can dissect the MDX side of things in greater detail. @@ -210,9 +204,17 @@ The [`remark-gfm`](https://github.com/remarkjs/remark-gfm) package isn't provide To help you transition to the new version, we've created a migration helper in our CLI. We recommend using it and reaching out using the default communication channels (e.g., [GitHub discussions](https://github.com/storybookjs/storybook/discussions/new?category=help)) for problems you encounter. -```shell -npx storybook@latest automigrate mdx1to2 -``` + + + + + ## Setup custom documentation @@ -386,47 +388,12 @@ By applying this pattern with the Controls addon, all anchors will be ignored in ### The MDX documentation doesn't render in my environment -As Storybook relies on MDX 2 to render documentation, some technical limitations may prevent you from migrating to this version. If that's the case, we've prepared a set of instructions to help you transition to this new version. +As Storybook relies on the latest version of [MDX](https://mdxjs.com/) to render documentation, some technical limitations may prevent you from migrating to this version. If that's the case, we've prepared a set of instructions to help you transition to this new version. #### Storybook doesn't create documentation for my component stories If you run into a situation where Storybook is not able to detect and render the documentation for your component stories, it may be due to a misconfiguration in your Storybook. Check your configuration file (i.e., `.storybook/main.js|ts`) and ensure the `stories` configuration element provides the correct path to your stories location(e.g., `../src/**/*.stories.@(js|jsx|mjs|ts|tsx)`). -#### The documentation doesn't render using `stories.mdx` - -Starting with Storybook 7.0, we've deprecated documenting stories with the `.stories.mdx` file extension. If you're still using the `stories.mdx` extension, we recommend [migrating](#automigration) as soon as possible to avoid any issues, as the majority of APIs and [Doc Blocks](./doc-blocks.md) used by Storybook were overhauled to support MDX 2 and the new MDX compiler (e.g., the [`Meta`](../api/doc-block-meta.md) block). - -#### MDX 1 fallback - -If you're still having issues with MDX documentation, you can enable MDX 1 as a fallback. To do so, you'll need to take some additional steps. - -Run the following command to install the required dependency. - - - - - - - -Update your Storybook configuration (in `.storybook/main.js|ts`), and provide the `legacyMdx1` feature flag to enable MDX 1 support. - - - - - - - ### The migration seems flaky and keeps failing By default, running the [migration command](#automigration) will try and migrate all existing MDX files in your project according to the MDX 2 specification. However, this might not always be possible, and you might run into issues during the migration. To help you troubleshoot those issues, we've prepared some recommendations that might help you.