Docusaurus

First of all, I have to say that Docusaurus is a BLAST to work with. I should know, I recently created the documentation websites for React Redux with it!

Like React, Docusaurus is an open source project that originated at Facebook. There are many factors to a successful open source project, such as technology, community and usability. However, documentation is often neglected. Docusaurus was introduced at the end of 2017 to address and reduce the friction of maintaining documentation.

Docusaurus is a site generator designed to make your life easier. You don't have to worry about boring stuff like infrastructure and design details. All you have to do is to provide documentation written in Markdown, write a home page in React and tweak some configuration. After that, your documentation website is ready to launch.

Install Docusaurus

Docusaurus is easily initialised using a script. It will set up all of the infrastructure for you.

Ensure you have the latest Node and your favourite package manager (npm or yarn) installed. Then create a project, if none exists, and change your directory to this project's root.

Then all you have to do is to run the Docusaurus initialisation script.

$ npx docusaurus-init

After running the initialisation script you will have a runnable example website to use as your site's base.

To run the example:

1. In the root of your project, rename docs-examples-from-docusaurus to docs.
2. Change directory to the website folder.
3. Rename blog-examples-from-docusaurus to blog.
4. To start the local web-server run npm start from within the website folder.

You will now have the example site loaded in your web browser at http://localhost:3000.

Make it your own

Out of the box the example features some built-in React components to personalize the home/root page of your website. The primary color is specified in siteConfig.js and is reflected various places across the website.

You can customise your site with the config in website/siteConfig.js according to the comprehensive siteConfig documentation (pun intended). The documentation markdown files are added to the docs folder. Similarly, you can add your blog posts in the blog folder. sidebars.json is where you specify the layout and content of the sidebar for your documentation using the id of markdown files. You can also create custom pages for your site. This is easily done with React in the pages folder and with static assets (like CSS and images) in the static folder.

Meet Slash

Slash is the official mascot of Docusaurus, a reference to how one would start code documentation in most programming languages with /. The observant reader might spot multiple variations of her on the offical Docusaurus website. At Facebook, they have actual Slash plushies -- and rumors say that you could get one if you create a documentation page with Docusaurus.

Slash will not write your docs, that’s still on you, but she can make the process of doing so a lot less painful.