Write staggering documentation for your React Projects
In the last few days, I started to improve the documentation of many of my open source projects in GitHub. I realized that by the time I made them I didn’t put much effort in making a clear documentation for developers that want to use it or contribute to it.
I’m going to pick one library I made as an example for this article: react-hotkey-tooltip. In a nutshell, it is a React component which allows you to bind hotkeys in your application and display a tooltip with the combination of the hotkey. It’s much simpler to see it in action.
I had already written a documentation for this library but it was uncompleted and really hard to maintain , you can check it here. And I rewrite it, using MDX language and this is the result!
Despite the fact the new page has more content to read and the UI is absolutely different, it took me only 1 day to develop it while the old one around 1 week. And that’s a huge big difference!
How I did it before?
I wrote the old docs page with React, so everything is a component. This may sound ordinary for you, but when you are writing documentation you have to focus on the content and not if you close the tags of p correctly. Let’s see a simple comparison between a list in React and in Markdown.
// React
const MyList = () => {
<p>My list contains</p>
<ul>
<li>Part A</li>
<li>Part B</li>
<li>Part C</li>
</ul>
}export default MyList;// Markdown
My list contains
* Part A
* Part B
* Part C
The Markdown version is much more readable, but the problem is that you can’t render React component inside of it … And a documentation page without real examples could not be that useful.
A workaround for this problem is to embed code using an application that render my component (e.g. CodeSandbox). The disadvantage I see with that is you end up with a split documentation, in one part the body with the full description and in the other the examples or demos …
For this reason, I had discarded markdown and choose React. It demanded me a lot of work, and you can easily see it by looking at the tree file structure:
How I do it now?
I learned from my mistakes and I absolutely wanted to use markdown to write the new documentation page! That was when I MDX showed up in my life 😄
MDX is a JSX in Markdown loader, parser, and renderer for ambitious projects. It combines the readability of Markdown with the expressivity of JSX . The best of both worlds. 🌐
In simple words, you can write down Markdown along with React components!
I decide to select a framework that help me with the documentation (at least for the router and the responsiveness). I choose docz, which is a documentation framework MDX based with zero configuration. I highly recommend it!
It automatically searches for any .mdx file in your project, creates a page parsing markdown and JSX and adds it to the router of the application. This is a simple example for ColorfulButton, combining Markdown and JSX 🎉
---
name: My Colorful Button
---import ColorfulButton from './ColorfulButton';# Colorful Button## Default lookThis is how my button looks by default<ColorfulButton>
Click me!
</ColorfulButton>## Color variationThis is how it looks using different colors :D<ColorfulButton color="dodgerblue">
Blue Button
</ColorfulButton><ColorfulButton color="deeppink">
Pink Button
</ColorfulButton>
At last, I want to show the file tree structure of the new documentation page for react-hotkey-tooltip using MDX. For each .mdx file a new route is automatically added to the application. Also you can create custom component for documentation as helpers, such as NextSection which takes a URL and allow the user to navigate to another page.
To sum up
In case you want to create your own documentation page, avoid at all cost writing with plain HTML (or a web framework) and jump into Markdown. You’ll notice the improvement in the development speed.
In case you want to show the behavior of a component next to the documentation, please please do not split your documentation. Write it with MDX giving you a centralized place with description and examples. The transition is really easy because it doesn’t replace Markdown, it extends with JSX!
Last words 👋
One more thing before you leave, I decided to start a newsletter so in case you want to hear about what I’m posting please consider following it! No SPAM, no hiring, no application marketing, just tech posts 👌
