Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Disable Markdown transclusion and support ?raw .md files #20790

Merged
merged 8 commits into from
Jan 27, 2023

Conversation

JReinhold
Copy link
Contributor

@JReinhold JReinhold commented Jan 26, 2023

What I did

This PR changes how plain .md files are handled and can be imported.

Previously Webpack (opt-in) and Vite could handle plain MD files using the MDX loader. However MDX2 got very strict with syntax, which results in perfectly valid .md files crashing the MDX loader, because it is invalid MDX syntax. This is confusing and have caused frustration. An example of a valid .md file that would break when imported is:

{ this is perfectly valid markdown, but MDX treats this as an expression }

This behavior is being replaced with support for handling ?raw imports. This means that it's now possible to import .md files as plain strings and do whatever necessary with them afterwards. The syntax for that is import ReadMe from './README.md?raw';

A follow-up PR will make this actually useful, by introducing a Markdown doc block that can handle these raw imports, like this:

// example.mdx
import { Markdown } from '@storybook/blocks';
import ReadMe from './README.md?raw';

<Markdown>{ReadMe)</Markdown>

This will make it possible to import valid, plain MD into MDX files without issues.

  1. Vite builder now doesn't use the mdxLoader to handle .md files, it is only used to handle .mdx files. This might be interesting to you @joshwooding as you originally built this in Fix markdown import in mdx builder-vite#429 cc @IanVS
  2. The transcludeMarkdown option has been removed. it was only implemented for Webpack, and it did the same as described above, except it was opt-in. Now it's not possible to opt-in to that anymore.

How to test

  • Create a sandbox with Webpack and with Vite
  • import a .md file in an .mdx file with the raw tag, and see that it renders as a plain string without breaking.

Stories for the Markdown block will also test this in the follow-up PR.

Checklist

  • Make sure your changes are tested (stories and/or unit, integration, or end-to-end tests)
  • Make sure to add/update documentation regarding your changes
  • If you are deprecating/removing a feature, make sure to update
    MIGRATION.MD

Maintainers

  • If this PR should be tested against many or all sandboxes,
    make sure to add the ci:merged or ci:daily GH label to it.
  • Make sure this PR contains one of the labels below.

["cleanup", "BREAKING CHANGE", "feature request", "bug", "documentation", "maintenance", "dependencies", "other"]

@JReinhold JReinhold changed the title Docs: Disable MDX transclusion and support ?raw .md files Docs: Disable Markdown transclusion and support ?raw .md files Jan 26, 2023
@JReinhold JReinhold self-assigned this Jan 26, 2023
@JReinhold JReinhold requested a review from shilman January 26, 2023 01:02
@JReinhold JReinhold marked this pull request as ready for review January 26, 2023 01:17
@JReinhold JReinhold mentioned this pull request Jan 26, 2023
5 tasks
Copy link
Member

@shilman shilman left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Love this PR when combined with the telescoping changes. Great job! 🚀

@IanVS
Copy link
Member

IanVS commented Jan 26, 2023

Is this example correct, or should the markdown import include ?raw? (Just trying to understand how this will work)

// example.mdx
import { Markdown } from '@storybook/blocks';
import ReadMe from './README.md';

<Markdown>{ReadMe)</Markdown>

@JReinhold
Copy link
Contributor Author

Is this example correct, or should the markdown import include ?raw? (Just trying to understand how this will work)

// example.mdx
import { Markdown } from '@storybook/blocks';
import ReadMe from './README.md';

<Markdown>{ReadMe)</Markdown>

Arh no I'm sorry @IanVS, it should include ?raw, I was too hasty with that example. Updated.

@JReinhold JReinhold merged commit 4d71923 into next Jan 27, 2023
@JReinhold JReinhold deleted the disable-markdown-transclusion branch January 27, 2023 22:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants