Writing good documentation is a mission-critical aspect of building software these days. Whether you are writing something for yourself, for the Open Source community, or your company, it's essential to keep things documented for good reasons:
- It makes developers more productive since they can rely on the docs to understand how to use your software.
- It makes developing the software itself easier promoting knowledge sharing amongst developers.
The process of writing documentation it's often tiresome. Imagine if you need to worry about building the whole foundation to make your documentation available to the public. Amongst many options to provide such foundation, I enjoy Docusaurus the most because:
- It's opinionated, provides you with all the structure you need to ship content fast. Docusaurus will decide how to structure your content, manage plugins, etc.
- Allows further customization with React. You can apply your knowledge of React to extend your documentation with other UI components built in React, as you see fit.
- It's Markdown all the way. Just like Gatsby or Hugo, the seamless interpolation with Markdown makes the experience of writing docs a breeze.
- It's GitHub pages friendly. GitHub pages are one of the sweethearts of free website hosting, especially when hosting documentation for open source projects. It's easy to set up and super convenient. Docusaurus docs have a guide just for this purpose.
- ; this is why I would pick Docusaurus to write docs over and over again. The sharp focus on documentation makes the whole solution even more attractive since you'll find the default way pages are structured very suitable to write documentation. Of course, the Docusaurus ecosystem is vast; simply looking at their showcase page to understand its use goes way beyond simple static documentation websites.
Here are a few tips & tricks that will help you build Docusaurus sites, get past some technical challenges, and better know what Docusaurus has to offer.
MDX is fantastic. It allows you to interpolate Markdown with JSX (React components). It's incredible to be able to simply plugin a React component. Here's a snippet from this blog post markdown file, where we include a React component to collect feedback at the bottom of the article.
You're reading a blog post built on Docusaurus. We use the Blog features to create content. Most things will be there waiting for you to start; add a markdown file under the
blog/ folder and start typing!
Probably one of the handiest features is the ability to access the content of your
docusaurus.config.js through the context React hook. Here's a small component that builds a social media sharable link using information from the config file (this same link produces the sharable paragraph at the bottom of our articles).
index.html to add globals to your application. An alternative would be to ship your global code, i.e., code that you want to run on every page (e.g., a cookies banner component) in your
theme/Footer/index.js. Because Docusaurus includes the footer in all pages, you can write logic that will execute every page, for example, by mounting a React component.
I became aware of the existence of clsx while working with Docusaurus. Look at it whenever you're in need to apply some CSS class conditionally. Here's a small example.
footer--dark would be applied if the condition
footer.style === 'dark' is met.
People delete sites and move sites all the time. It's an awful experience to read a page, click on a reference, and end empty-handed, facing a blank page. Docusaurus offers an out-of-the-box solution to scan for broken links. I highly recommend the usage of to warn you of broken links in your content; this will make it very hard or even impossible for you to ship broken links! Here's how to configure it in your
If you are migrating from another stack and plan on introducing new routes, this small redirect trick will be super useful. You can redirect old routes to the new ones by creating a simple markdown file with the name of the old route, and redirect users to your shinny new page.
It's super easy to set up analytics with the plugin-google-analytics. Here are the steps:
- Install the plugin
- Add append this object into your
And that's all. I hope the above tips unblock your journey of content creation with Docusaurus.
If you liked this article, consider sharing (tweeting) it to your followers.