Docs: Improve MDX new user experience

[karlhorky]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

Problem

Let me start with saying MDX and the experience it enables (when properly set up + configured) is great! The simplicity and ease of Markdown with the power, flexibility and interop of React 😍

However, there are not-uncommon cases where users can fall off the happy path / miss the pit of success if going beyond the simple first examples - there's a long tail of complexity and high chance for breakage in moving beyond simple examples.

Let's take <video> support an MDX document in Next.js as an example:

1. User tries to add <video src="abc.mp4"> to an MDX document, knowing already that they can add HTML to MDX - it works! 👍
2. User would like to import the .mdx file in another location. "abc.mp4" cannot be resolved anymore.
3. User researches, finds rehype-mdx-import-media, using cmd-F, finds that it supports video[src] and tries configuring using the example config
4. Nothing seems to be happening with the <video>, user researches quickly and finds no issues or problems with the <video> syntax. (at this point, knowledgeable, experienced MDX users would have found the bullets under Usage, but during my user journey, I did not understand this on the first try). User instead tries out an image in Markdown syntax and it appears to be working.
5. User reflects and considers that there may be a problem with <video> and rehype-mdx-import-media, but since there are no issues directly related to this plugin, researches in related ecosystems rehype and MDX. User does not find something directly related to lack of <video> support, but eventually finds that there may be behavior of MDX which causes it to treat HTML elements differently than Markdown elements.
6. User researches how to add <video> in MDX syntax and finds the ![](abc.mp4) syntax (which, to be fair, contains the caveat "Depending on your markdown processor,"). This doesn't work out of the box.
7. User researches how to add ![](abc.mp4) syntax support and happens on to @chailotl/remark-videos, which does help - the error message has now changed to Module parse failed: Unexpected character '' (to be fair, this is entering Next.js + webpack territory now)
8. User researches what this could be, thinking this is also related to MDX/remark/rehype/etc but fails. User changes research techniques and finds that it may be related to Next.js and webpack loaders. After some time, finds a webpack loader which should be able to load .mp4 files.
9. User observes working video 👍

Another example would be related to a user trying to include nested MDX content on part of a Next.js page (not a full page with app/page.mdx) - this could lead to A) next-mdx-remote (not fully working with nested MDX), B) mdx-bundler (working with nested MDX but complicated) and then C) back to @next/mdx (which does work, but it is undocumented how to do it - await import(...)).

In my personal evaluation, after years on and off in the MDX ecosystem (having also invested more time and energy than I would say is average for a part-time user): this is not an uncommon experience when working with MDX - as soon as needs exceed the basics a bit, I've seen it be common to have a "rabbit hole"-type debugging experience, through complexity and incompatibilities on various levels.

In my personal evaluation, some of the first documentation problems I perceive relate to new user experience are:

A) Happy Path / Pit of Success

Lack of working, blessed, happy-path setup and integration suggestions for use cases beyond simple content

B) Transitive Dependency Web / Many Moving Parts

The complex web of transitive dependencies that extends from MDX to remark/rehype/recma to other unified packages like the unist-* packages makes it challenging for a senior engineer to understand, navigate and fix / work around incompatibilities - eg. type errors or runtime incompatibilities with remark/rehype/recma plugins and transitive dependencies

Many of these issues may be perceived by experienced developers or those working in the MDX and related ecosystems as "papercuts" or low-barrier issues, but for beginners, it can lead to hitting walls and even quitting. Even for me as an experienced developer, I often find myself spending a lot of time on something that appears to be a simple problem.

---

I don't intend this to be a condemnation or negative criticism of the ecosystem or packages or people involved - just trying to surface a report of the UX pitfalls for an (enthusiastic) user in the ecosystem.

Solution

A) Happy Path / Pit of Success

1. An ecosystem for modern, updated, maintained recipes / cheatsheets / examples - eg. similar to the Next.js examples - to allow both MDX maintainers and the community to contribute helpful, common configurations, setups and integrations (for the first example above, a "Next.js + MDX + imported video" recipe/example would be not much code and would save a lot of time)
2. Potentially also: Modern, updated, maintained end to end / integration tests with latest versions of integrating packages

B) Transitive Dependency Web / Many Moving Parts

1. Create docs content dedicated to common interop problems with transitive dependencies and solutions for these and rank highly on search engines with this content
   1. Potentially also: docs pages for other common papercuts
2. Additional combined UIs for the API docs for MDX, remark/rehype/recma, unified packages, eg:
   1. Allowing for seamless navigation among the docs "owners" without having to jump between multiple layers or websites (even just including the types of other libraries without having to click on links would be a great start)
   2. Search Add site search to the new MDX website #1776

---

If this issue or or parts of this issue are accepted, then I'm ok with this becoming the parent "umbrella issue" to track multiple initiatives.

Alternatives

Create additional tooling to avoid the issue, such as:

• CLI tools like mdx doctor which will find common issues like mismatching or duplicated transitive dependencies and other setup problems
• Additional editor-level tools to navigate and resolve issues
• Additional tools for integrations such as Next.js, to either offer features to smooth over the experience or to raise issues that users should resolve
• Additional chat-based UI for the docs for MDX, remark/rehype/recma, Unified packages, to allow for easier, faster navigation and search, when users don't use the exact wording or terms in the docs

But I think that these alternatives are complex and time-consuming to build and maintain, would not be able to effectively address all issues and would also require docs and outreach to make sure that users actually used them.

[ChristianMurphy]

Hey @karlhorky! 👋
Thanks for taking the time to share you experience and some ideas to improve the experience.
There is always interest in improving developer experience.

A few themes I'm hearing from you (correct me if I repeat these back inaccurately)

1. You were/are looking for a fairly custom solution. Not using an existing video player react component or video transcoding platform
2. You found various community plugins in varying degree of support/documentation/repair
3. The references/examples you used mainly came from next js

A few themes I'll share from my perspective before responding more in depth

1. Inherent and irreducible complexity. All problems have a degree of complexity which can't be reduced or abstracted away. Parsers/Compilers has a significant amount of theory and complexity surrounding them.
2. MDX is Stadium project. Unified/Micromark/Remark/MDX have millions of active developer users, and 3 active maintainers currently. (see more on project types here: https://blas.com/working-in-public/)
3. Incorrect documentation is worse than no documentation. Document needs to: work, reflect the latest version of dependencies, and reflect best practices. If it does not do all of these, it is a worse experience for the developer than trying to read the source itself.
4. Infinite solution space. MDX is a programming language with a content focus. It can do anything, people use it in wildly varied and creative ways from document editing, interactive experience creation, learning management system foundations, and much much more. The number of hypothetical uses are infinite, and even in practice have been growing exponentially since the project's inception.

User would like to import the .mdx file in another location. "abc.mp4" cannot be resolved anymore

Hindsight being 20/20 this feels like it could/should have been made an absolute path instead of a relative path so it would resolve the same anywhere?

Nothing seems to be happening with the

Not judging, just observing.
It is fairly common both in the issue tracker and in discussions for adopters to try stuff without reading the readme. Not understand the abstraction or what the plugin does. Then open an issue/discussion and suggest: more documentation.

More documentation won't help people that don't read documentation in the first place. 😅

as soon as needs exceed the basics a bit, I've seen it be common to have a "rabbit hole"-type debugging experience, through complexity

As you move from the higher level abstraction to lower level ones for more advanced use cases it does get more complex.
We offer some introductory materials to the concepts in https://unifiedjs.com/learn/
It really could be it's own book, there was even a start on one once upon a time https://github.com/unifiedjs/handbook but it was never finished.

and incompatibilities on various levels.

Could you expand what you mean by this?

The complex web of transitive dependencies that extends from MDX to remark/rehype/recma to other unified packages like the unist-* packages makes it challenging for a senior engineer to understand, navigate and fix / work around incompatibilities - eg. type errors or runtime incompatibilities with remark/rehype/recma plugins and transitive dependencies

Unified has a large API surface.
The types are the most effective way to see if things are compatible.
If they aren't issues are welcome!

If you need help typing your own custom plugins, we have recipes at https://unifiedjs.com/learn/ which offer some best practices for working with the typings, which maintain strong type guarantees.

Lack of working, blessed, happy-path setup and integration suggestions for use cases beyond simple content

If you have concrete suggestions on common use cases you see beyond content ideas are welcome!
The tricky part here isn't finding other uses (see infinite solution space above) but boiling that down to use cases many adopters have.

An ecosystem for modern, updated, maintained recipes

We have this! https://unifiedjs.com/learn/
And more at https://mdxjs.com/

examples - eg. similar to the Next.js examples

I land pretty strongly against example folders like this, they aren't maintained and tested the way they should be, and that can cause more confusion that it can help (see Incorrect documentation is worse than no documentation above)
For people that prefer to see code using the project. Every official Unified/Micromark/Remark/MDX project has 100% test coverages which offer a lot of highly tested examples.

allow both MDX maintainers and the community to contribute helpful, common configurations, setups and integrations

This is great in theory but doesn't happen in practice (see MDX is Stadium project above)

Even when contributions trickle through, they don't necessarily follow the best practices of the project.
Case and point, the official plugins list https://github.com/remarkjs/remark/pulls?q=is%3Apr+add+plugin+is%3Aclosed and the amount of back and forth it takes to get the typings working and basic tests in place.

first example above, a "Next.js + MDX + imported video" recipe/example would be not much code and would save a lot of time

This is a good example of why this is challenging.
I appreciate that you may have had a reason to use imports and self host a video.
That is not something I would recommend for a broader audience.
As a whole I'd recommend using a video hosting platform that handles transcoding, and a react component that offers an accessible interface around that video platform along with adaptive playback.
None of that needs customization at the MDX platform level.

Potentially also: Modern, updated, maintained end to end / integration tests with latest versions of integrating packages

I interpret this as meaning canary testing.
And I'm open to that, we already have a step like that for unified https://github.com/unifiedjs/unified/blob/242105bd6e18c61ca10f37d99529b89f1be37518/.github/workflows/main.yml#L25-L48 testing a few trusted downstream packages.

Create docs content dedicated to common interop problems with transitive dependencies and solutions for these

I still don't know what interop problems you are referring to.
Most of the ones I know of boil down to: please update your dependencies to the latest.
And the signal to know to do that is TypeScript is erroring.

rank highly on search engines with this content

We don't have a marketing team to go SEO chasing.
This is an open source project with a few maintainers (see MDX is Stadium project above)

Additional combined UIs for the API docs for MDX, remark/rehype/recma, unified packages

There is some linking between sites already.
Open to more linking.

even just including the types of other libraries without having to click on links would be a great start

I don't understand this comment.
Are you looking for hosted TSDoc?

CLI tools like mdx doctor which will find common issues like mismatching or duplicated transitive dependencies and other setup problems

Unified and all the umbrella projects have a large API surface, just versions doesn't communicate necessarily have enough information to communicate if they are compatible or not.
You may or may not care about a breaking change.

For that finer grained reporting we have TypeScript typings, which report when and where things mismatch.
I'm not sure making a second less capable version and less accurate version of is a good use of time.
Though open to other opinions.

Additional editor-level tools to navigate and resolve issues

That is what https://github.com/mdx-js/mdx-analyzer is here for, and it grows in capabilities regularly. (as you are aware regularly contributing issues)
If you have specific recommendation for the editor tools, feel free to share them!

Additional tools for integrations such as Next.js, to either offer features to smooth over the experience or to raise issues that users should resolve

This would be a great thing to raise with the Next team who manage the Next integrations

Additional chat-based UI for the docs for MDX, remark/rehype/recma, Unified packages, to allow for easier, faster navigation and search, when users don't use the exact wording or terms in the docs

Contributions to get intelligent search working again are welcome #1776

I don't think the team has the budget or interest in running a full LLM chat bot for the MDX docs (with July 2024 LLM cost and capabilities anyway).
If a project like https://githubnext.com/projects/copilot-for-docs/ comes around again we may consider enabling it.

[wooorm]

Thanks for sharing your thoughts!

Here are some responses to different parts. There’s a lot. Sometimes duplicated. So I haven’t responsed to everything. Let me know if there’s something I’m missing.

Let's take <video> support an MDX document in Next.js as an example:

Docs: Improve MDX new user experience

Given that the <video> issue was also raised in #2503, I do wonder whether this issue here is more about new users or people migrating. Info on things that worked before but no longer should be in a migration guide (this case, https://mdxjs.com/migrating/v2/#update-mdx-content), but not in the current guide for newcomers.

That MDX 2 release was big. I don’t see MDX change much ever again.

knowing already that they can add HTML to MDX - it works! 👍

I think this fundamental: MDX is not HTML. It isn’t markdown + HTML. If you want that, use markdown itself
MDX is JavaScript. It isn’t static. It’s a literal programming language. For when you find that you are writing a lot of tags like <em> and <a> often, you can use * and []() instead.
With this thinking, it makes more sense: would a <video src={whatGoesHere} /> work in a JavaScript file? That depends. It has a lot to do with where that JavaScript runs. Or how you configured your tools.
Then, videos on the web are also complex: only .mp4 is often not what you want.
Finally, MDX isn’t coupled to React (or even to HTML).
The problem this user faces has very little to do with MDX. It has much more to do with how else this user chooses to make a website.

Making websites is complex; compilers are complex.

User researches, finds rehype-mdx-import-media, using cmd-F, finds that it supports video[src] and tries configuring using the example config

user researches quickly

knowledgeable, experienced MDX users would have found the bullets under Usage

What’s that joke? PEBCAK 😅
At some point people, not just experienced people, are supposed to read. https://github.com/remcohaszing/rehype-mdx-import-media.
I think Christian mentions this too: we can’t solve this with more docs. People gotta read.
You have to see the example, which is a shortcut for turning A into B, and then think: is B what I want? Does that work for me? If not, this plugin isn’t for me. If yes, do I need a plugin or do I write it?

This leads to the following generated HTML:
(from your references issue remcohaszing/rehype-mdx-import-media#3)

After some time, finds a webpack loader which should be able to load .mp4 files.

Right, reiterating what I said above: how to use <video> in MDX with React through Webpack on Next.js, has very little to do with MDX, and more to do with how to use <video> with React through Webpack on Next.js.

Coming back to your earlier “User would like to import the .mdx file in another location. "abc.mp4" cannot be resolved anymore.” Answer that first. You don’t need all these plugins. Write it:

import myVideoSource from './some-video.mp4'

<video src={myVideoSource} controls />

Another example would be related to a user trying to include nested MDX content on part of a Next.js page

I don’t fully understand, can you explain?

A) Happy Path / Pit of Success

Lack of working, blessed, happy-path setup and integration suggestions for use cases beyond simple content

I don’t think these use cases are that simple or that they have that much to do with MDX.

An ecosystem for modern, updated, maintained recipes / cheatsheets / examples - eg. similar to the Next.js examples -
Potentially also: Modern, updated, maintained end to end / integration tests with latest versions of integrating packages

This is incredibly hard to keep up to date. I’m betting it costs Vercel tons, millions, to maintain that.
And, I’m hearing chatter about how RSC and Next.js and Webpack are too complex? So, does this really solve it for them?
MDX can be used with any JSX runtime, any frontent framework (react/preact/vue/svelte/solid/etc), any bundler, any, what you call it, next/remix/gatsby/astro.
I don’t think what you want is possible. The money or the time is missing. And the community can already help: they sometimes do (and it’s appreciated) but not that much.

Create docs content dedicated to common interop problems with transitive dependencies and solutions for these and rank highly on search engines with this content
Potentially also: docs pages for other common papercuts

Please raise these issues when you encounter them? I don’t know them.

Additional combined UIs for the API docs for MDX, remark/rehype/recma, unified packages, eg:
Allowing for seamless navigation among the docs "owners" without having to jump between multiple layers or websites (even just including the types of other libraries without having to click on links would be a great start)

unifiedjs.com has all the readmes. Still, it’s more than 500 readmes.
The code is >75 times the size as the source repo for Linux. It’s massive.

CLI tools like mdx doctor which will find common issues like mismatching or duplicated transitive dependencies and other setup problems

I think this makes more sense as a separate issue where you explain what is going on for you.
But, this feels like this is a problem of having multiple Reacts? npm ls react finds that?

Additional tools for integrations such as Next.js, to either offer features to smooth over the experience or to raise issues that users should resolve

This sounds like something on top of MDX: I think there’s lots of room above MDX for more site builder like tools.

If this issue or or parts of this issue are accepted, then I'm ok with this becoming the parent "umbrella issue" to track multiple initiatives.

I’m going to move this to a discussion. There’s lots of room for issues, but issues can be closed at some point.