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

First-class MDX support #10064

Open
wants to merge 5 commits into
base: v2
Choose a base branch
from
Open

First-class MDX support #10064

wants to merge 5 commits into from

Conversation

devongovett
Copy link
Member

@devongovett devongovett commented Dec 28, 2024

Closes #8625, closes #7922, closes #7934

This adds first-class support for MDX, built into the JS transformer like JSX and TS. It's implemented in Rust using mdx-rs, which produces an SWC AST that we process directly without re-parsing.

It comes with support for a bunch of features that integrate it deeply with Parcel:

  • Support for dependencies. For example, images and links automatically become dependencies just like with HTML.
  • A table of contents is extracted and attached to asset.meta.ssgMeta, which exposed by the React SSG packager and can be used by layouts.
  • Static exports are extracted as well. These can be used to expose metadata, similar to front matter but natively to MDX.
  • The code block meta string is parsed as JSX props when possible and passed into the CodeBlock component, which can be customized.
  • When the special render option in code block meta strings is used, the code is extracted into an asset and at runtime passed into the CodeBlock component, allowing for live examples.

For example:

```tsx render
<div>Hello world!</div>
```

would render

<CodeBlock lang="tsx" render={<div>Hello world!</div>}>
  &lt;div&gt;Hello world!&lt;/div&gt;
</CodeBlock>

and then CodeBlock can decide what to do with each part. The default CodeBlock implementation renders a <pre><code> with the code, followed by the render value, but this can be customized by injecting your own CodeBlock component. You can also use a custom <CodeBlock> to implement things like syntax highlighting.

CSS code blocks can also be "rendered", which will inject the CSS into the corresponding CSS bundle for the page.

This is not a breaking change because @parcel/transformer-mdx will continue to be used if it is already installed. If it can't be resolved, the JS transformer will handle it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

MDX Plugin out of date
1 participant