Cloud-based docs
Jamie Munro shows you how to set up GitHub, Docusaurus and Netlify to generate a professional-looking static documentation site.
Jamie Munro sets up GitHub, Docusaurus and Netlify to generate a professionallooking static documentation site.
Docusaurus 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.
From 13 August 2021 GitHub no longer enables you to authenticate from the terminal using your account password. Instead you’ll need to generate a ‘Personal Access Token’ and set a scope that defines what the token is allowed to do in your repositories. Make a note of your token as you won’t be able to see it once you browse away from the tokens page. This provides more security for your repository. After logging in to GitHub go to https://github.com/settings/tokens to create a new token. For our purposes the token only needs to have access to the options listed under ‘repo’. Whenever you’re prompted for your password in the terminal you can use your personal access token.
Browse to your new, empty repository where GitHub will display some helpful Quick Setup information including the link you’ll need to clone your repository. If you want to store your credentials so you don’t need to re-enter them each time, issue a git command. You can include them in the initial command to clone the repository, which will store them in the config file in a hidden .git directory on your local machine.
Back in a terminal window switch to, or create a directory where you’ll keep the local copy of your repository and type the following command, replacing
/path/to/repo.git with the link from the QuickSetup section on GitHub.
$ git clone https://
For example
$ git clone https://jiros:docusarus_token_value@ github.com/jiros/docusaurus.git
You’ll receive a warning about cloning a blank repository, which you can safely ignore. Change directory into the newly created local repository:
$ cd repo
We’re now ready to install Docusaurus. Note that, in the command below, you can replace docs-site with any name you like. This will create the Docusaurus
installation as a subdirectory in your locally cloned repository directory. ‘Classic’ refers to the template that Docusaurus will use to create your site, which includes a preconfigured theme and some default plugins. We recommend sticking with ‘classic’. There’s a Facebook template, but this has a particular focus on Facebook projects and the Bootstrap template is still experimental.
$ npx @docusaurus/init@latest init docs-site classic
You’ll now have a directory structure that should contain a local copy of your repository and the
Docusaurus installation will be a subdirectory. We will refer to these directories as ‘repo’ and ‘docs-site’.
Docusaurus is a static site generator, which means that it’s designed to take a number of markdown pages and parse them into a series of static pages. When you’re developing your site, however, having to regenerate your pages every time you make a change is not a terribly efficient workflow. Docusaurus includes a development server that will run locally on http:// localhost:3000 and will hot-load any changes you make to your files. This is helpful when you want to quickly see the effect of your updates:
$ cd repo/docs-site
$ npm run start
Create new content
Before we get to customising the site, let’s tidy up and create some new content. Docusaurus expects any content to be saved as markdown files within the repo/ docs-site/docs directory. It’s possible to have subdirectories within this, and out of the box, Docusuarus includes a series of tutorial pages of its own that are split into two subdirectories. We’ll be removing these and creating our own content, but you can always find the same content online at https://docusaurus.sse. codesandbox.io if you need to refer back to it.
Browse to repo/docs-site/docs and delete intro.md
and both tutorial subdirectories.
Docusarus makes a distinction between docs (which appear on the sidebar), pages (which don’t) and blog posts (which have their own section entirely). An important part of all three is the metadata, or ‘Markdown Frontmatter’ that sets the id of the page, how and where it should appear in the sidebar, a URL slug as well as additional options like keywords. Blog pages (which live in the repo/docs-site/blog directory) also allow for one or more categories to be specified.
$ nano repo/docs-site/docs/hello-world.md
--id: hello-world title: Hello World! sidebar_position: 1 sidebar_label: Hello World slug: /hello
--Hello world.
Frontmatter metadata should be at the top of the page and should start and end with three dashes. We won’t linger on formatting content, because we have a lot of ground to cover on our journey to the cloud. You can find a wealth of information on the Docusaurus site about the formatting options available in markdown, how to add images, create links and more.
Add a new subdirectory to /docs called steps and create two more markdown files – step1.md and
step2.md – with the following content, substituting values as necessary in the second file:
--id: step-1 title: The First Step sidebar_label: Step 1 slug: /step1
--This is the first step.
Docusaurus will use the directory structure to generate the sidebar, but it’ll use your directory names exactly as you typed them. To have more control over this, create another file in the steps directory called _category_.json and add the following content. This enables you to edit both the sidebar label and the position that the directory should appear in the sidebar.
{
“label": “All the Steps”,
“position": 2
}
Configuration
Let’s make some basic customisations to our site. There are several different places where we can customise Docusaurus. The illustration, Anatomy of a Docusaur, has an overview of which files need to be edited to change the look and feel of the landing page. Firstly, any images (ie logo, favicon and landing page feature icons) will need to be saved to /repo/docs-site/static/img. We used Inkscape to generate some simple images and retained the ico and svg formats as used by Docusaurus.
The majority of site configuration options are held in
docusaurus.config.js, which lives in the root of your docs-site directory:
$ nano repo/docs-site/docusaurus.config.js
Here you can update the title, organisation name, tagline to those of your project and update the paths of the logo and favicon files to match the names of those you saved earlier.
While we’re here we will also make changes to the navbar section as follows, editing the ‘intro’ navbar item and then copying and pasting a second directly underneath. In Docusaurus you can refer to pages by their id or by their URL slug. Note that files in subdirectories will automatically have the directory name prefixed to their id (for example, steps/step-1 ) even if you don’t explicitly specify this in the file frontmatter on the page itself:
navbar: {
... items: [
{ type: ‘doc’, docId: ‘hello-world’, position: ‘left’, label: ‘Hello’,
},
{ type: ‘doc’, docId: ‘steps/step-1’, position: ‘left’, label: ‘Steps’,
},
Docusaurus is geared towards software projects and includes navbar and footer GitHub links that you can update to point at your project’s GitHub repository. This is usually a separate repository to your documentation repository, but further down the docusaurus.config.js
file there’s also a section under ‘presets’ where you can update the ‘editUrl’ options to reference your documentation repository. This enables you to automatically edit the files in GitHub directly from your
Docusarus instance. When you’re done you can press Ctrl+O to save and Ctrl+X to exit the nano editor.
Stick the landing
Next we’ll update the landing page. This is a separate javascript file that uses some of the variables from docusaurus.config.js and an imported React component to generate its content. The colours are controlled by a custom css file:
$ nano repo/docs-site/src/pages/index.js
Here we’ll simply update the text and link for the landing page’s call-to-action button by changing /docs/ intro to /docs/hello-world and Docusaurus Tutorial - 5 min to Click me before saving and exiting the file.
Docusaurus is powered by React so heavily utilises the concept of components that can be reused elsewhere on the site. The three ‘featured’ items on the landing page are part of a component, which is then imported into the index.js page so to make any changes
to the features we will need to edit the component file. $ nano repo/docs-site/src/components/
HomepageFeatures.js
Here you can edit the three sections listed under ‘const FeatureList’. In particular you can update the title, the path to the related svg file (assuming you have uploaded a suitable replacement to repo/docs-site/ static/img) and description. Once you’re done you can save and exit.
Finally, we’ll give the site a new lick of paint. Replace the existing colour scheme with new values. Docusaurus
has a handy tool (https://docusaurus.io/docs/stylinglayout) that will generate different shades based on an initial primary colour. We used this tool to generate a scheme from #960000:
$ nano repo/docs-site/src/css/custom.css --ifm-color-primary: #960000; --ifm-color-primary-dark: #870000; --ifm-color-primary-darker: #800000; --ifm-color-primary-darkest: #690000; --ifm-color-primary-light: #a50000; --ifm-color-primary-lighter: #ad0000; --ifm-color-primary-lightest: #c30000;
A final push to GitHub
One of the advantages of having your Docusaurus site stored in a git repository is that it’s much easier to deploy your site. There are many roads to the cloud and here we’ve chosen to use Netlify. It’s well suited to the JAMstack and integrates well with GitHub. It also has a free plan so your route to the cloud is toll-free.
First we’ll push our changes from our local machine to GitHub where it’ll be accessible to Netlify. In a terminal change directory to the root of the local repository (repo) and type the following commands:
$ git add -A
$ git commit -m “First draft of docusaurus site”
At this point git may ask you to update your email address and username in order to be able to associate the git commits to your user details. Run the two commands as suggested and then re-run the git commit command:
$ git config --global user.email “you@example.com” $ git config --global user.name “Your Name”
Finally, let’s push the changes to GitHub by typing:
$ git push
Now the online version of your repository will be up to date with the latest changes. You can check this by logging in to GitHub online and then we’re ready to connect to Netlify. Note that every time you make changes locally you’ll need to follow this process to push the changes back up to GitHub.
Once more unto the Cloud
Netlify gives you several options to choose from when signing up and we recommend using the GitHub account you used/created earlier to sign up to Netlify. The sign-up process will ask you for your GitHub credentials and will email a verification code to the email address you used when signing up to GitHub. When you are prompted, click ‘authorise Netlify’ to allow Netlify to access your GitHub account. Netlify will then take you through a series of questions to finish setting up your account, including your name, company and intended use of Netlify.
From the Netlify home page press the ‘New site from Git’ button and under Continuous Deployment select GitHub. You’ll again be prompted to authorise Netlify and to install Netlify in your GitHub repositories and you can choose to allow Netlify to access one or all of your repositories. In the next screen select ‘master’ as the branch to deploy and add the following into the Basic build settings before clicking Deploy:
Base directory: docs-site
Build command: npm run build
Publish: docs-site/build
Netlify will grab your files from GitHub, generate your site and assign it a random Netlify URL. You can see the status of your deploy and find the link to your new site from the Site Overview tab in Netlify.
Click the URL or thumbnail to explore your new site and congratulate yourself on a job well done! Netlify is now set up to continually deploy your site, which means that any new changes which you push to the master branch of your GitHub repository will trigger a new build. The free plan includes 300 build minutes a month, which should be more than enough for most small projects. You can also maximise this by working locally, or on a separate branch before merging or pushing your changes back to the master branch on GitHub.