How MDX is a game changer for your React Project's Documentation

Rate this content

Documentation is essential to any project and it can really "make it or break it".  However documentation is time consuming to draft and can sometimes be forgotten, or updates and amendments to it left behind as the project moves forward.  Additionally, creating your documentation with Markdown has its limitations, so you may not end up with the result you want or that your contributor needs. 

By using MDX you can combine Markdown with code and integrate it into your React project.  Documentation becomes a more streamlined and efficient process and dare I say 

Eddie Jaoude
Eddie Jaoude
28 min
08 Dec, 2023


Sign in or register to post your comment.

Video Summary and Transcription

Good documentation is crucial and can make or break a project. Word of mouth is important in the industry, and great documentation can attract users. MDX is a powerful tool for writing documentation, allowing for customization and reuse of components. Documentation should be treated like code, with testing and continuous improvement. Responsible AI usage is important, and a balanced approach to documentation, including inline comments and different formats, should be used.

Available in Español

1. Introduction to Docs with MDX

Short description:

Hello, React Day Berlin! Today, I'll be talking about Docs with MDX and how it can be a game-changer for your project. Good documentation is crucial, but not many people want to write it. Incorrect and outdated documentation frustrates me. Let's improve the numbers by the end of my talk. Docs are just as important as code. Remember, every pull request with code changes should also have tests and docs.

Thank you so much for that warm welcome. Well, hello, React Day Berlin. My name is Eddie Chow and I'm super excited to geek out with you today on Docs with MDX and how it can be a game-changer for your project.

We all want good documentation, but it seems that not many people want to write it. I get frustrated when docs don't exist. And I also get frustrated when they have a hello world example. I want a real-world example. But you know what really, really gets me? When the documentation is incorrect and out of date. And unfortunately, it happens too often. And let me just clarify, by good, I just mean correct, up to date, and it looks nice. I don't think that's too much for us to ask.

I mean, who likes reading good documentation? Let's have a show of hands. I mean, hopefully, most of us. Great. Thank you so much. Great to see you all awake as well. Like I said, nothing fancy, it's what we expect. I mean, who likes writing documentation? Okay, a few people, some people unsure. Okay, well, hopefully, we can improve those numbers by the end of my talk.

Docs are just as important as code. And if there's one thing you take away from this entire talk, please remember that. We might not treat it like that, though. We don't get the same buzz. And also, we don't get the same street cred from our peers as well. When someone says, I wrote this cool feature, I used library X, and everyone's like, oh yeah, great. And if someone says, I documented feature X, literally silence, you don't get that same street cred. And I think that has a role to play as well. But hopefully, we can all agree that documentation is important, and it's our responsibility to have good documentation. Tests are also really important, but that's a separate discussion, and we did chat about that yesterday here at TestJS. So I believe every pull request that has code changes should also have tests and docs as well.

2. Importance of Documentation

Short description:

Why is documentation important? Out-of-date documentation can be worse than no documentation. It can mislead users and cause frustration. Just like riding a bicycle with no brakes, documentation should be reliable. Missing steps in documentation can lead to errors and confusion. It's important to contribute to open source projects by reviewing and improving documentation.

Why? Because everything should be reviewed. What is worse than no documentation? Yes, there is something worse than no documentation. Out-of-date documentation. Why? Because people trust it. So when something goes wrong, it's even more painful. We're guiding people down the wrong path, so no docs can actually be better. People know to go look at the code, or try and figure it out, or phone a friend.

Have you ever ridden a bicycle with no brakes? I actually have. Earlier this year in Bangkok, we're at a hotel, we want to go to the park, and they said, you know, we can borrow our bikes. But they have no brakes. But because we knew it had no brakes, we went slower. I made sure Sarah went in front, so I could use her to stop. No, I'm just kidding. But if a bike has brakes, you expect them to work. And the same with documentation.

I mean, how many of you have seen this before? I'm sure you've seen this a lot of times. My core project, and then no documentation. That's one scenario. Another scenario is docs with missing steps. Hopefully some people can shout out what the two steps are missing here. Yes, so before install dependencies, navigate into the new directory that was created by the Git clone, and then install dependencies, and then run npm run dev. There's nothing wrong with this. This isn't incorrect. It is just missing some steps. If someone gets an error on that second step, and Googles it, they're probably going to get, you know, try and install dependencies. Okay, package.js is not found. Right, navigate into the directory, install dependencies. And they'll get there because this is great. And by the way, you'll see this on so many open source projects, so it's a great way to contribute is to go through the documentation and don't make any assumptions because if you're familiar with projects like this, then you'll know what commands to run. But people who are new to tech or new to the project won't.


Check out more articles and videos

We constantly think of articles and videos that might spark Git people interest / skill us up or help building a stellar career

Full Stack Documentation
JSNation 2022JSNation 2022
28 min
Full Stack Documentation
Top Content
Interactive web-based tutorials have become a staple of front end frameworks, and it's easy to see why — developers love being able to try out new tools without the hassle of installing packages or cloning repos.But in the age of full stack meta-frameworks like Next, Remix and SvelteKit, these tutorials only go so far. In this talk, we'll look at how we on the Svelte team are using cutting edge web technology to rethink how we teach each other the tools of our trade.
Gateway to React: The Story
React Summit US 2023React Summit US 2023
32 min
Gateway to React: The Story
A behind the scenes look at the design and development of the all-new React docs at The new launched this year introducing new methodologies like challenges and interactive sandboxes and subtle inclusivity features, like "international tone" and culturally agnostic examples. Not only have the new docs changed how people learn React, they've inspired how we think about developer education as a community. In this talk, you will learn how the React team and some ambitious community members made the "React docs rock" for a generation of front end developers and how these new patterns and established techniques can be applied in your favorite projects.
Opensource Documentation—Tales from React and React Native
React Finland 2021React Finland 2021
27 min
Opensource Documentation—Tales from React and React Native
Documentation is often your community's first point of contact with your project and their daily companion at work. So why is documentation the last thing that gets done, and how can we do it better? This talk shares how important documentation is for React and React Native and how you can invest in or contribute to making your favourite project's docs to build a thriving community
Documenting components with stories
React Finland 2021React Finland 2021
18 min
Documenting components with stories
Most documentation systems focus on text content of one form or another: WYSIWYG editors, markdown, code comments, and so forth. Storybook, the industry-standard component workshop, takes a very different approach, focusing instead on component examples, or stories.
In this demo, I will introduce an open format called Component Story Format (CSF).
I will show how CSF can be used used to create interactive docs in Storybook, including auto-generated DocsPage and freeform MDX documentation. Storybook Docs is a convenient way to build a living production design system.
I will then show how CSF stories can be used create novel forms of documentation, such as multiplayer collaborative docs, interactive design prototypes, and even behavioral documentation via tests.
Finally, I will present the current status and outline a roadmap of improvements that are on their way in the coming months.
TypeScript for Library Authors: Harnessing the Power of TypeScript for DX
TypeScript Congress 2022TypeScript Congress 2022
25 min
TypeScript for Library Authors: Harnessing the Power of TypeScript for DX
Using real-life open-source examples, we'll explore the power of TypeScript to improve your users' experience. We'll cover best practices for library authors, as well as tips and tricks for how to take a library to the next level. This talk will cover: 
- how to leverage the type inference to provide help to your users; - using types to reduce the need and complexity of your documentation - for example, using function overloads, string literal types, and helper (no-op) functions; - setting up testing to ensure your library works (and your types do too!) with tools like tsd and expect-type; - treating types as an API and reducing breaking changes whilst shipping enhancements; - I'd draw on my experience with libraries like nuxt3, sanity-typed-queries and typed-vuex and show what we managed to do and what I'd do differently in future. 

The Legendary Fountain of Truth: Componentize Your Documentation!
React Advanced Conference 2021React Advanced Conference 2021
24 min
The Legendary Fountain of Truth: Componentize Your Documentation!
"In Space, No One Can Hear You Scream." The same goes for your super-brand-new-revolutionary project: Documentation is the key to get people speaking about it.Building well-fitted documentation can be tricky. Having it updated each time you release a new feature had to be a challenging part of your adventure. We tried many things to prevent the gap between doc and code: code-generated documentation, live examples a-la-Storybook, REPL...It's time for a new era of documentation where people-oriented content lives along with code examples: this talk will guide you from Documentation Best Practices – covered from years of FOSS collaborative documentation – to the new fancy world of Components in Markdown: MDX, MDJS, MD Vite, and all.Let's build shiny documentation for brilliant people!