Merge pull request #18246 from storybookjs/chore_docs_adds_mdx2_steps

Chore: (DOCS) Adds MDX 2 documentation
storybookjs · May 17, 2022 · f837e31 · f837e31
2 parents 64b07fe + 73cf6ba
commit f837e31
Show file tree

Hide file tree

Showing 6 changed files with 120 additions and 19 deletions.
diff --git 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. <br/> `features: { storyStoreV7: true }`                                                                                     |
-| `buildStoriesJson`    | Generates a `stories.json` file to help story loading with the on demand mode. <br/> `features: { buildStoriesJson: true }`                                                                           |
+| `buildStoriesJson`    | Generates a `stories.json` file to help story loading with the on demand mode. <br/> `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.<br/> `features: { emotionAlias: false }` |
 | `babelModeV7`         | Enables the new [Babel configuration](./babel.md#v7-mode) mode for Storybook. <br/> `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. <br/> `features: { postcss: false }`       |
 | `modernInlineRender`  | Enables Storybook's modern inline rendering mode. <br/> `features: { modernInlineRender: false }`                                                                                                                                    |
+| `previewMdx2`         | Enables experimental support for [MDX 2](../writing-docs/mdx.md#mdx-2).<br/>`features: { previewMdx2: true }`                                                                                                                        |
 
 ## Configure story loading
 

diff --git 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 <strong>not</strong> apply to [DocsPage](./writing-docs/docs-page.md). If you're interested in helping us fix this issue, read our <a href="https://github.com/storybookjs/storybook/blob/next/CONTRIBUTING.md">Contribution guidelines</a> 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:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+   'common/my-component-with-custom-syntax-highlight.mdx.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<div class="aside">
+💡 Check <code>react-syntax-highlighter</code>'s <a href="https://github.com/react-syntax-highlighter/react-syntax-highlighter">documentation</a> for a list of available languages.
+</div>
+
+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:
+
+```
+<style>{`
+  .class1 {
+    ...
+  }
+
+  .class2 {
+    ...
+  }
+`}</style>
+
+```
+
+You'll need to update it to make it compatible with MDX 2.
+
+```
+<style>
+  {`
+    .class1 {
+      ...
+    }
+
+    .class2 {
+      ...
+    }
+  `}
+</style>
+```
+
+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
+<!-- Button.stories.mdx -->
+
+import { Story } from '@storybook/addon-docs';
+
+import * as stories from './Button.stories.jsx';
+
+<Story name="Basic" story={stories.Basic} />
+```
+
+
 ### 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:
-
-<!-- prettier-ignore-start -->
-
-<CodeSnippets
-  paths={[
-   'common/my-component-with-custom-syntax-highlight.mdx.mdx',
-  ]}
-/>
 
-<!-- prettier-ignore-end -->
-
-<div class="aside">
-💡 Check <code>react-syntax-highlighter</code>'s <a href="https://github.com/react-syntax-highlighter/react-syntax-highlighter">documentation</a> for a list of available languages.
-</div>
-
-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
@@ -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
+  },
+};
+```
diff --git a/docs/snippets/common/storybook-mdx2-install.npm.js.mdx b/docs/snippets/common/storybook-mdx2-install.npm.js.mdx
@@ -0,0 +1,3 @@
+```shell
+npm install @storybook/mdx2-csf --save-dev
+```
diff --git a/docs/snippets/common/storybook-mdx2-install.yarn.js.mdx b/docs/snippets/common/storybook-mdx2-install.yarn.js.mdx
@@ -0,0 +1,3 @@
+```shell
+yarn add --dev @storybook/mdx2-csf
+```
diff --git 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.
 
 </div>
+
+## 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.
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-mdx2-install.yarn.js.mdx',
+    'common/storybook-mdx2-install.npm.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+Update your Storybook configuration (in `.storybook/main.js|ts`) and add the `previewMdx2` feature flag as follows:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-main-enable-mdx2.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->