-
-
Notifications
You must be signed in to change notification settings - Fork 9.4k
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
Conversation
There was a problem hiding this 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! 🚀
Is this example correct, or should the markdown import include
|
Arh no I'm sorry @IanVS, it should include |
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 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 isimport 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:This will make it possible to import valid, plain MD into MDX files without issues.
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 @IanVStranscludeMarkdown
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
.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
MIGRATION.MD
Maintainers
make sure to add the
ci:merged
orci:daily
GH label to it.["cleanup", "BREAKING CHANGE", "feature request", "bug", "documentation", "maintenance", "dependencies", "other"]