DOCUSAURUS

Jamie Munro shows you how to set up GitHub, Docusaurus and Netlify to generate a professional-looking static documentation site.

OUR EXPERT

Jamie Munro maintains the documentation for healthecco. org, an open source project that uses NLP and graph technologies to bring the world’s health knowledge to researchers and medical decision makers.

QUICKTIPS

The GitHub repository we created during the making of this tutorial is available for reference at https://github. com/Jiros/ docusaurus.

D ocusaurus is an open source documentation application developed by Facebook. It’s one of a growing number of JAMstack static site generators that uses a blend of JavaScript, React and markdown to make it easy for you to deploy clean, professional-looking documentation sites that are easy to maintain. A Docusaurus site can be managed as a git repository, meaning that version control is baked in and, perhaps most importantly, your developers can use their tool of choice to directly edit the content in markdown files, or even edit the files directly on GitHub. Although Docusaurus v2 is technically still in beta, they recommend using it, even in production.

The objective of this tutorial is to deploy a customised documentation site to the cloud using GitHub and a free Netlify account. Netlify, GitHub and Docusaurus are all powerful tools with many different features that we couldn’t possibly hope to cover in a single tutorial, so we’ll only be touching on the bare essentials to get a site configured and deployed.

Docusaurus is (perhaps unsurprisingly for a documentation platform) well documented and there are a number of good ‘getting started with GitHub’ guides available online.

Installasaurus

Docusaurus requires node.js version 12.13 or greater. If you’re using Ubuntu then be aware that the official repository is several versions behind on version 10.19. We recommend grabbing a binary from NodeSource – https://github.com/nodesource/distributions. We tested both the LTS (14) and current node.js (16) binaries on Ubuntu 20.04.2.

To install Node.js version 16 on Debian/Ubuntubased systems, open a new terminal window and type:

$ curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash - $ sudo apt-get install -y nodejs

You can confirm node.js is installed by checking the version at the command line: $ node -v

Because our ultimate goal is to use GitHub to manage and deploy our Docusaurus instance we’ll create a new, empty repository on GitHub, clone it locally and then install Docusaurus. To do this you’ll need to log in (or sign up) to GitHub.com You can create a repository under the Repositories tab by clicking New and entering a name for the repository. This can be anything and will appear as the directory name once you’ve cloned the repository to your local PC.