Improve migration docs for MDX2 markdown import

[mihkeleidast]

Describe the bug

Importing a markdown file (changelog) that includes some "special syntax" causes the mdx page to not render.

Minimal markdown:

# Changelog

- <IconSort/> prop definitions

Co-authored-by: Foo Bar <foo@google.com>

The two issues in there are:

• <IconSort/> is not wrapped in backticks, so mdx2 treats it as a component, but does not find the import
• It does not like the email syntax <foo@google.com>
  • Error in browser: Failed to fetch dynamically imported module: http://localhost:9001/src/docs/changelog.stories.mdx?t=1667071749836&import
  • Error in console:

    10:29:17 PM [vite] Internal server error: Unexpected character `@` (U+0040) in name, expected a name character such as letters, digits, `$`, or `_`; whitespace before attributes; or the end of the tag (note: to create a link in MDX, use `[text](url)`)
 Plugin: storybook:mdx-plugin
 File: /foo/bar/CHANGELOG.md:undefined:undefined

To Reproduce

No response

System

No response

Additional context

Works without errors with SB6.5 and mdx1

[shilman]

@JReinhold would love to brainstorm about this one. the issue is that MDX2 has gotten a lot more strict about markdown syntax than MDX1, so things that "transcluded" properly don't anymore.

We could either:

1. Explain to users in the migration notes
2. Figure out a different way to import and render markdown in MDX

[JReinhold]

I have a strong preference for option 1., otherwise it feels like we're making our own flavor of MDX2, and that's just an API surface that's really difficult to support down the line.

But we can talk this over in more detail.

[mihkeleidast]

I would have no objections if this was mostly a migration docs fix - I had only three offending lines, so not hard to fix. However, it would be very nice if the error message could be improved so it would point to the offending place in the markdown file, manually trying to figure out what is wrong in a file thousands of lines long is a bit of a hassle.

[tmeasday]

@shilman shall we change the title of this one to essentially be 1?

[shilman]

Here's the plan:

• Implement Markdown utility block as part of [Feature Request][v7]: Allow rendering custom Markdown just as in v6 #20586
• Add migration instruction to use Markown utility block as replacement for addon-docs transcludeMarkdown
• Deprecate transcludeToMarkdown option & reference migration instructions

[shilman]

Zoinks!! I just released https://github.com/storybookjs/storybook/releases/tag/v7.0.0-beta.36 containing PR #20796 that references this issue. Upgrade today to the @next NPM tag to try it out!

npx sb@next upgrade --prerelease