From bb423bd59ceaf29d3c000b95a19e13ede8f31045 Mon Sep 17 00:00:00 2001
From: Kyle Gach <kyle.gach@gmail.com>
Date: Fri, 19 Jan 2024 16:57:26 -0700
Subject: [PATCH 1/2] Remove mentions of MDX 2

- Remove Breaking changes section
- Move GFM instructions to Troubleshooting section
- Remove blockquotes, which render in a huge font
---
 docs/faq.md                   |  8 +--
 docs/writing-docs/autodocs.md |  4 +-
 docs/writing-docs/mdx.md      | 94 +++++++++++------------------------
 3 files changed, 35 insertions(+), 71 deletions(-)

diff --git a/docs/faq.md b/docs/faq.md
index 55840449c2fa..424f201aed61 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -21,7 +21,7 @@ Here are some answers to frequently asked questions. If you have a question, you
 - [I see a "No Preview" error with a Storybook production build](#i-see-a-no-preview-error-with-a-storybook-production-build)
 - [Can I use Storybook with Vue 3?](#can-i-use-storybook-with-vue-3)
 - [Why aren't my code blocks highlighted with Storybook MDX](#why-arent-my-code-blocks-highlighted-with-storybook-mdx)
-- [Why aren't my MDX 2 stories working in Storybook?](#why-arent-my-mdx-2-stories-working-in-storybook)
+- [Why aren't my MDX stories working in Storybook?](#why-arent-my-mdx-stories-working-in-storybook)
 - [Why are my mocked GraphQL queries failing with Storybook's MSW addon?](#why-are-my-mocked-graphql-queries-failing-with-storybooks-msw-addon)
 - [Can I use other GraphQL providers with Storybook's MSW addon?](#can-i-use-other-graphql-providers-with-storybooks-msw-addon)
 - [Can I mock GraphQL mutations with Storybook's MSW addon?](#can-i-mock-graphql-mutations-with-storybooks-msw-addon)
@@ -371,9 +371,9 @@ Yes, with the release of version 6.2, Storybook now includes support for Vue 3.
 
 Out of the box, Storybook provides syntax highlighting for a set of languages (e.g., Javascript, Markdown, CSS, HTML, Typescript, GraphQL) you can use with your code blocks. Currently, there's a known limitation when you try and register a custom language to get syntax highlighting. We're working on a fix for this And will update this section once it's available.
 
-## Why aren't my MDX 2 stories working in Storybook?
+## Why aren't my MDX 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:
+MDX 2 introduced some changes to how the code is rendered. For example, if you have the following code block:
 
 ```
 <style>{`
@@ -388,7 +388,7 @@ MDX 2 introduced some changes to how the code is rendered. For example, if you e
 
 ```
 
-You'll need to update it to make it compatible with MDX 2.
+You'll need to update it to make it compatible with MDX 2+.
 
 ```
 <style>
diff --git a/docs/writing-docs/autodocs.md b/docs/writing-docs/autodocs.md
index e902c99eb942..4c1dcaea5fdb 100644
--- a/docs/writing-docs/autodocs.md
+++ b/docs/writing-docs/autodocs.md
@@ -230,7 +230,9 @@ Out of the box, Storybook has a set of components that you can use to customize
 
 <Callout variant="info" icon="💡">
 
-This is not a Storybook issue but a breaking change introduced with MDX 2. For more information on this and other breaking changes, see our [MDX documentation](./mdx.md#breaking-changes).
+This is not a Storybook issue but a detail of how MDX works. From their [migration guide](https://mdxjs.com/migrating/v2/#update-mdx-content):
+
+“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 `<h1>hi</h1>`”
 
 </Callout>
 
diff --git a/docs/writing-docs/mdx.md b/docs/writing-docs/mdx.md
index afc4c11a86b4..d40ae287025c 100644
--- a/docs/writing-docs/mdx.md
+++ b/docs/writing-docs/mdx.md
@@ -121,7 +121,7 @@ The `Meta` block defines where the document will be placed in the sidebar. In th
 
 <!-- prettier-ignore-end -->
 
-MDX2 supports standard markdown ([”commonmark”](https://commonmark.org/)) by default and can be extended to support [GitHub-flavored markdown (GFM)](https://github.github.com/gfm) and other extensions (see [Breaking changes](#breaking-changes), below).
+MDX supports standard markdown ([”commonmark”](https://commonmark.org/)) by default and can be extended to support [GitHub-flavored markdown (GFM)](https://github.github.com/gfm) and other extensions (see [Breaking changes](#breaking-changes), below).
 
 <!-- prettier-ignore-start -->
 
@@ -151,70 +151,7 @@ In addition to Doc Blocks, MDX can incorporate arbitrary React components, makin
 
 ### Known limitations
 
-While MDX2 supports a variety of runtimes ([React](https://mdxjs.com/packages/react/), [Preact](https://mdxjs.com/packages/preact/), [Vue](https://mdxjs.com/packages/vue/)), Storybook’s implementation is React-only. That means your documentation is rendered in React, while your stories render in the runtime of your choice (React, Vue, Angular, Web Components, Svelte, etc.).
-
-## Breaking changes
-
-There are many breaking changes if you move from MDX 1 to version 2. As far as we know, all of these are due to changes in the MDX library itself rather than changes to Storybook’s usage. Nevertheless, as an MDX user, you will probably need to update your MDX files as part of the upgrade. MDX has published its own [Migration guide](https://mdxjs.com/migrating/v2/#update-mdx-files). Here, we try to summarize some of the fundamental changes for Storybook users.
-
-### Custom components apply differently
-
-From the MDX migration guide:
-
-> 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 `<h1>hi</h1>`
-
-This means that the first heading in the following example gets replaced, whereas the second does not. It may not sound like a significant change, but in practice, it is highly disruptive and manifests itself in various ways. Unfortunately, this cannot be automatically converted in a safe way.
-
-<!-- prettier-ignore-start -->
-
-```md
-# Some heading
-
-<h1>another heading</h1>
-```
-
-<!-- prettier-ignore-end -->
-
-### Lack of GitHub Flavored Markdown (GFM)
-
-Also, from the MDX migration guide:
-
-> We turned off GFM features in MDX by default. GFM extends CommonMark to add autolink literals, footnotes, strikethrough, tables, and task lists. If you do want these features, you can use a plugin. How to do so is described in [our guide on GFM](https://mdxjs.com/guides/gfm/).
-
-In Storybook, you can apply MDX options, including plugins, in the main configuration file:
-
-<!-- prettier-ignore-start -->
-
-<CodeSnippets
-paths={[
-  'common/storybook-main-config-remark-options.js.mdx',
-  'common/storybook-main-config-remark-options.ts.mdx',
-]}
-/>
-
-<!-- prettier-ignore-end -->
-
-<Callout variant="info" icon="💡">
-
-The [`remark-gfm`](https://github.com/remarkjs/remark-gfm) package isn't provided by default during migration. We recommend installing it as a development dependency if you use its features.
-
-</Callout>
-
-### Automigration
-
-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.
-
-<!-- prettier-ignore-start -->
-
-<CodeSnippets
-  paths={[
-    'common/storybook-automigration-mdx-legacy.npm.mdx',
-    'common/storybook-automigration-mdx-legacy.pnpm.mdx',
-    'common/storybook-automigration-mdx-legacy.yarn.mdx',
-  ]}
-/>
-
-<!-- prettier-ignore-end -->
+While MDX supports a variety of runtimes ([React](https://mdxjs.com/packages/react/), [Preact](https://mdxjs.com/packages/preact/), [Vue](https://mdxjs.com/packages/vue/)), Storybook’s implementation is React-only. That means your documentation is rendered in React, while your stories render in the runtime of your choice (React, Vue, Angular, Web Components, Svelte, etc.).
 
 ## Setup custom documentation
 
@@ -386,9 +323,34 @@ By applying this pattern with the Controls addon, all anchors will be ignored in
 
 ## Troubleshooting
 
+### Markdown tables aren't rendering correctly
+
+As of MDX 2, GFM is no longer included by default:
+
+“We turned off GFM features in MDX by default. GFM extends CommonMark to add autolink literals, footnotes, strikethrough, tables, and task lists. If you do want these features, you can use a plugin. How to do so is described in [our guide on GFM](https://mdxjs.com/guides/gfm/).”
+
+In Storybook, you can apply MDX options, including plugins, in the main configuration file:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+paths={[
+  'common/storybook-main-config-remark-options.js.mdx',
+  'common/storybook-main-config-remark-options.ts.mdx',
+]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<Callout variant="info" icon="💡">
+
+The [`remark-gfm`](https://github.com/remarkjs/remark-gfm) package isn't provided by default during migration. We recommend installing it as a development dependency if you use its features.
+
+</Callout>
+
 ### The MDX documentation doesn't render in my environment
 
-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.
+As Storybook relies on [MDX 3](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
 

From 9a78132a526f3a81af52788f34bb222cb3efbeaf Mon Sep 17 00:00:00 2001
From: Kyle Gach <kyle.gach@gmail.com>
Date: Mon, 22 Jan 2024 10:14:14 -0700
Subject: [PATCH 2/2] Generalize MDX formatting guidance

---
 docs/faq.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/faq.md b/docs/faq.md
index 424f201aed61..7258501324ed 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -373,7 +373,7 @@ Out of the box, Storybook provides syntax highlighting for a set of languages (e
 
 ## Why aren't my MDX stories working in Storybook?
 
-MDX 2 introduced some changes to how the code is rendered. For example, if you have the following code block:
+MDX can be picky about how your code is formatted with line breaks. This is especially true with code blocks. For example, this will break:
 
 ```
 <style>{`
@@ -388,7 +388,7 @@ MDX 2 introduced some changes to how the code is rendered. For example, if you h
 
 ```
 
-You'll need to update it to make it compatible with MDX 2+.
+But this will work:
 
 ```
 <style>