Docs: Clarify that @next/mdx can replace next-mdx-remote

[karlhorky]

What is the documentation issue?

Since a few months / years, I have encountered articles such as MDX in Next.js - Space Jelly by @colbyfayock which are based on the (incorrect) assumption that @next/mdx cannot pull in content from other sources such as files outside of the app directory:

The trick here though is that to use the official Next.js MDX package, our content needs to be located inside of the app directory, just like any other page file.

But in our example, say we have a content directory in the root of our project with a dump of our MDX, and it’d be tedious, and frankly a bit overwhelming to put that all inside of the app directory with the page filename pattern, we can instead use Next MDX Remote to render our content from where it is.

This is an incorrect assumption, as files outside of the app directory can be pulled in via static imports and dynamic import():

1. static import
   • https://nextjs.org/docs/app/building-your-application/configuring/mdx#using-imports

   • next.js/examples/app-dir-mdx/app/page.tsx

     Line 4 in 3127e86

     import Content from "./message.mdx";

2. dynamic import()
   • Import MDX components dynamically #12151 (comment)
   • @wesbos in Dynamically load Server Components #51016 (reply in thread)

Apart from the aforementioned blog posts, there seems to be a bunch of community confusion on what is possible using @next/mdx:

• MDX support width appDir enabled #47523
• MDX Blog (v14 App router) with `[slug]` path structure. #58575
• Using mdx provider in a server component #50897
• Recommended way to pass an MDX file from `getServerSideProps` as a prop to a component? #47621
• more...

Even the Next.js MDX docs section "Remote MDX" seem to (incorrectly) implicitly indicate that @next/mdx cannot do this:

If your MDX files or content lives somewhere else, you can fetch it dynamically on the server. This is useful for content stored in a separate local folder, CMS, database, or anywhere else. A popular community package for this use is next-mdx-remote.

@next/mdx can achieve the same things as next-mdx-remote and mdx-bundler and rsc-mdx, without the significant, non-obvious downsides with the alternatives:

• next-mdx-remote/rsc doesn't allow for importing MDX files within MDX files
• mdx-bundler requires complicated manual configuration to share components to imported .mdx files (not to mention pulling in a bunch of extra bundling dependencies and running the bundling outside of the existing webpack / Turbopack bundler config)

cc @manovotny @leerob @wooorm @remcohaszing

Is there any context that might help us understand?

I'm hoping the context is included above. I can add more if needed.

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/app/building-your-application/configuring/mdx