Documenting your project can be a pain in the ass and is often neglected. Docusaurus removes the pain of maintaining documentation.
3 min read
By Svein Petter Gjøby
December 1, 2018
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.
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:
npm startfrom within the
You will now have the example site loaded in your web browser at http://localhost:3000.
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
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
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.