diff --git a/docs/configure/overview.md b/docs/configure/overview.md index 671cddfc57e9..83eed8505c43 100644 --- a/docs/configure/overview.md +++ b/docs/configure/overview.md @@ -45,11 +45,12 @@ Additionally, you can also provide additional feature flags to your Storybook co | Configuration element | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `storyStoreV7` | Configures Storybook to load stories [on demand](#on-demand-story-loading), rather than during boot up.
`features: { storyStoreV7: true }` | -| `buildStoriesJson` | Generates a `stories.json` file to help story loading with the on demand mode.
`features: { buildStoriesJson: true }` | +| `buildStoriesJson` | Generates a `stories.json` file to help story loading with the on demand mode.
`features: { buildStoriesJson: true }` | | `emotionAlias` | Provides backwards compatibility for Emotion. See the [migration documentation](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#emotion11-quasi-compatibility) for context.
`features: { emotionAlias: false }` | | `babelModeV7` | Enables the new [Babel configuration](./babel.md#v7-mode) mode for Storybook.
`features: { babelModeV7: true }` | | `postcss` | Disables the implicit PostCSS warning. See the [migration documentation](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#deprecated-implicit-postcss-loader) for context.
`features: { postcss: false }` | | `modernInlineRender` | Enables Storybook's modern inline rendering mode.
`features: { modernInlineRender: false }` | +| `previewMdx2` | Enables experimental support for [MDX 2](../writing-docs/mdx.md#mdx-2).
`features: { previewMdx2: true }` | ## Configure story loading diff --git a/docs/faq.md b/docs/faq.md index 811a1ac20433..a76ebab17e5b 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -285,6 +285,78 @@ See our documentation on how to customize the [Storyshots configuration](./writi Currently there's an issue when using MDX stories with IE11. This issue does not apply to [DocsPage](./writing-docs/docs-page.md). If you're interested in helping us fix this issue, read our Contribution guidelines and submit a pull request. + +### Why aren't my code blocks highlighted with Storybook MDX + +Out of the box, Storybook provides syntax highlighting for a set of languages (e.g., Javascript, Markdown, CSS, HTML, Typescript, GraphQL) that you can use with your code blocks. If you're writing your custom code blocks with MDX, you'll need to import the syntax highlighter manually. For example, if you're adding a code block for SCSS, adjust your story to the following: + + + + + + + +
+💡 Check react-syntax-highlighter's documentation for a list of available languages. +
+ +Applying this small change will enable you to add syntax highlight for SCSS or any other language available. + +### Why aren't my MDX 2 stories working in Storybook? + +MDX 2 introduced some changes to how the code is rendered. For example, if you enabled it in your Storybook and you have the following code block: + +``` + + +``` + +You'll need to update it to make it compatible with MDX 2. + +``` + +``` + +See the following [issue](https://github.com/mdx-js/mdx/issues/1945) for more information. + + +### Why can't I import my own stories into MDX 2? + +This is a known issue with MDX 2. We're working to fix it. For now you can apply the following workaround: + +```md + + +import { Story } from '@storybook/addon-docs'; + +import * as stories from './Button.stories.jsx'; + + +``` + + ### Why are my mocked GraphQL queries failing with Storybook's MSW addon? If you're working with Vue 3, you'll need to install [`@vue/apollo-composable`](https://www.npmjs.com/package/@vue/apollo-composable). With Svelte, you'll need to install [`@rollup/plugin-replace`](https://www.npmjs.com/package/@rollup/plugin-replace) and update your `rollup.config` file to the following: @@ -327,25 +399,7 @@ Yes, check the [addon's examples](https://github.com/mswjs/msw-storybook-addon/t No, currently, the MSW addon only has support for GraphQL queries. If you're interested in including this feature, open an issue in the [MSW addon repository](https://github.com/mswjs/msw-storybook-addon) and follow up with the maintainer. -### Why aren't my code blocks highlighted with Storybook MDX - -Out of the box, Storybook provides syntax highlighting for a set of languages (e.g., Javascript, Markdown, CSS, HTML, Typescript, GraphQL) that you can use with your code blocks. If you're writing your custom code blocks with MDX, you'll need to import the syntax highlighter manually. For example, if you're adding a code block for SCSS, adjust your story to the following: - - - - - - -
-💡 Check react-syntax-highlighter's documentation for a list of available languages. -
- -Applying this small change will enable you to add syntax highlight for SCSS or any other language available. ### How can my code detect if it is running in Storybook? diff --git a/docs/snippets/common/storybook-main-enable-mdx2.js.mdx b/docs/snippets/common/storybook-main-enable-mdx2.js.mdx new file mode 100644 index 000000000000..fe80c1d4c8b7 --- /dev/null +++ b/docs/snippets/common/storybook-main-enable-mdx2.js.mdx @@ -0,0 +1,11 @@ +```js +// .storybook/main.js|ts + +module.exports = { + stories: ['../stories/**/*.stories.mdx', '../stories/**/*.stories.@(js|jsx|ts|tsx)'], + addons: ['@storybook/addon-links', '@storybook/addon-essentials'], + features: { + previewMdx2: true, // 👈 MDX 2 enabled here + }, +}; +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-mdx2-install.npm.js.mdx b/docs/snippets/common/storybook-mdx2-install.npm.js.mdx new file mode 100644 index 000000000000..6f6b5f63daad --- /dev/null +++ b/docs/snippets/common/storybook-mdx2-install.npm.js.mdx @@ -0,0 +1,3 @@ +```shell +npm install @storybook/mdx2-csf --save-dev +``` \ No newline at end of file diff --git a/docs/snippets/common/storybook-mdx2-install.yarn.js.mdx b/docs/snippets/common/storybook-mdx2-install.yarn.js.mdx new file mode 100644 index 000000000000..6c80c7bba428 --- /dev/null +++ b/docs/snippets/common/storybook-mdx2-install.yarn.js.mdx @@ -0,0 +1,3 @@ +```shell +yarn add --dev @storybook/mdx2-csf +``` \ No newline at end of file diff --git a/docs/writing-docs/mdx.md b/docs/writing-docs/mdx.md index 9f72289a4126..1da98f82ec28 100644 --- a/docs/writing-docs/mdx.md +++ b/docs/writing-docs/mdx.md @@ -248,3 +248,32 @@ Unless you use a custom [Webpack configuration](../builders/webpack.md#extending Be sure to update [.storybook/main.js](../configure/overview.md#configure-story-rendering) file to load `.stories.mdx` stories, as per the addon-docs installation instructions. + +## MDX 2 + +Starting with Storybook 6.5, [MDX 2](https://mdxjs.com/blog/v2/) is introduced as an experimental opt-in feature. To enable it, you'll need to take additional steps. Documented below is our recommendation. + +Run the following command to add the necessary dependency. + + + + + + + +Update your Storybook configuration (in `.storybook/main.js|ts`) and add the `previewMdx2` feature flag as follows: + + + + + + \ No newline at end of file