feat(dev): support overriding components for Markdown elements

You can use an [MDX provider](https://mdxjs.com/docs/using-mdx/#mdx-provider) to override which React components are used for standard Markdown elements. For example, suppose that for all routes under the `/products` path you want to replace all Markdown links with [`<Link>`](../components/link) components instead of HTML `<a>` elements. Create the following route module `app/routes/products.tsx`: ```tsx filename=app/routes/products.tsx import { MDXProvider } from "@mdx-js/react"; import { Link, Outlet } from "@remix-run/react"; export default function Products() { return ( <MDXProvider components={{ a: ({ children, href, ref, ...props }) => href ? ( <Link to={href} {...props}> {children} </Link> ) : ( <a {...props}>{children}</a> ), }} > <Outlet /> </MDXProvider> ); } ``` Then `app/routes/products.hammers.mdx` might look like this: ```mdx filename=app/routes/products.hammers.mdx If you like our hammers, then you should also check out our [nails](/products/nails)! ```
remix-run · lpsinger · Sep 20, 2023 · Nov 30, 2023 · 736ef04b3f6500b6d1dbf2e906afd391468c34e4
commit 736ef04b3f6500b6d1dbf2e906afd391468c34e4
diff --git a/.changeset/beige-experts-rest.md b/.changeset/beige-experts-rest.md
@@ -0,0 +1,7 @@
+---
+"integration-tests": minor
+"@remix-run/dev": minor
+"@remix-run/server-runtime": minor
+---
+
+Support overriding the React components for standard Markdown elements in MDX files
diff --git a/docs/guides/mdx.md b/docs/guides/mdx.md
@@ -179,6 +179,42 @@ export default function Index() {
 
 Clearly this is not a scalable solution for a blog with thousands of posts. Realistically speaking, writing is hard, so if your blog starts to suffer from too much content, that's an awesome problem to have. If you get to 100 posts (congratulations!), we suggest you rethink your strategy and turn your posts into data stored in a database so that you don't have to rebuild and redeploy your blog every time you fix a typo. You can even keep using MDX with [MDX Bundler][mdx-bundler].
 
+## Custom Components
+
+You can use an [MDX provider](https://mdxjs.com/docs/using-mdx/#mdx-provider) to override which React components are used for standard Markdown elements. For example, suppose that for all routes under the `/products` path you want to replace all Markdown links with [`<Link>`](../components/link) components instead of HTML `<a>` elements. Create the following route module `app/routes/products.tsx`:
+
+```tsx filename=app/routes/products.tsx
+import { MDXProvider } from "@mdx-js/react";
+import { Link, Outlet } from "@remix-run/react";
+
+export default function Products() {
+  return (
+    <MDXProvider
+      components={{
+        a: ({ children, href, ref, ...props }) =>
+          href ? (
+            <Link to={href} {...props}>
+              {children}
+            </Link>
+          ) : (
+            <a {...props}>{children}</a>
+          ),
+      }}
+    >
+      <Outlet />
+    </MDXProvider>
+  );
+}
+```
+
+Then `app/routes/products.hammers.mdx` might look like this:
+
+```mdx filename=app/routes/products.hammers.mdx
+# Hammers
+
+If you like our hammers, then you should also check out our [nails](/products/nails)!
+```
+
 ## Advanced Configuration
 
 If you wish to configure your own remark plugins you can do so through the `remix.config.js`'s `mdx` export:

diff --git a/integration/mdx-test.ts b/integration/mdx-test.ts
@@ -18,8 +18,13 @@ test.describe("mdx", () => {
     fixture = await createFixture({
       files: {
         "app/root.tsx": js`
+          import { MDXProvider } from "@mdx-js/react";
           import { Links, Meta, Outlet, Scripts } from "@remix-run/react";
 
+          function AWrapper({children, ...props}) {
+            return <a {...props}><b>{children}</b></a>
+          }
+
           export default function Root() {
             return (
               <html lang="en">
@@ -28,7 +33,9 @@ test.describe("mdx", () => {
                   <Links />
                 </head>
                 <body>
-                  <Outlet />
+                  <MDXProvider components={{a: AWrapper}}>
+                    <Outlet />
+                  </MDXProvider>
                   <Scripts />
                 </body>
               </html>
@@ -83,6 +90,8 @@ export function ComponentUsingData() {
 
 # This is some markdown!
 
+[An awesome link](https://remix.run)
+
 <ComponentUsingData />
         `.trim(),
 
@@ -120,6 +129,7 @@ export function ComponentUsingData() {
     expect(await app.getHtml('meta[name="description"]')).toMatch(
       "Isn't this awesome?"
     );
+    expect(await app.getHtml("a b")).toMatch("An awesome link");
     expect(await app.getHtml("title")).toMatch("My First Post");
     expect(await app.getHtml("#loader")).toMatch(/Mambo Number:.+5/s);
     expect(await app.getHtml("#handle")).toMatch("abc");

diff --git a/packages/remix-dev/compiler/plugins/mdx.ts b/packages/remix-dev/compiler/plugins/mdx.ts
@@ -100,6 +100,7 @@ export const handle = typeof attributes !== "undefined" && attributes.handle;
     let compiled = await mdx.compile(fileContents, {
       jsx: true,
       jsxRuntime: "automatic",
+      providerImportSource: "@mdx-js/react",
       rehypePlugins,
       remarkPlugins,
     });

diff --git a/packages/remix-dev/package.json b/packages/remix-dev/package.json
@@ -27,6 +27,7 @@
     "@babel/traverse": "^7.23.2",
     "@babel/types": "^7.22.5",
     "@mdx-js/mdx": "^2.3.0",
+    "@mdx-js/react": "^2.3.0",
     "@npmcli/package-json": "^4.0.1",
     "@remix-run/node": "2.3.1",
     "@remix-run/router": "1.13.0",

diff --git a/packages/remix-server-runtime/package.json b/packages/remix-server-runtime/package.json
@@ -16,6 +16,7 @@
   "typings": "dist/index.d.ts",
   "module": "dist/esm/index.js",
   "dependencies": {
+    "@mdx-js/react": "^2.3.0",
     "@remix-run/router": "1.13.0",
     "@types/cookie": "^0.5.3",
     "@web3-storage/multipart-parser": "^1.0.0",