Deploying a Docusaurus documentation to Github Pages

This is a quick guide to deploy your Docusaurus docs to Github Pages.

Docusaurus is a static-site generator created by Meta / Facebook that provides easy to use documentation features. It's great to quickly bootstrap docs for a project.

Documentation example

Docusaurus classic documentation template with little to no configuration example

I had some difficulty understanding the Docusaurus deploy to Github Pages process, so I decided to write this guide as a personal note and to help others who may need it.

My goal was to add more robust documentation to an existing open-source project that I maintain. The project already had its directory structure, I wanted to simple create a docs/ folder, put the Docusaurus project in there, and have the website up and running on Github Pages.

Github Pages serves the raw content of the gh-pages branch of your repo in the https://<username>.github.io/<my-cool-repo>/ URL.

This means that we need to keep only the files generated by the docusaurus build command on the gh-pages branch, not the source files.

gh-pages branch example

The gh-pages branch of a repository with Docusaurus docs hosted on Github Pages.

main branch example

The main branch of the same repository. The docs folder contains the Docusaurus project.

Docusaurus has a quick command to deploy on Github Pages: docusaurus deploy, but it requires some additional config.

On the docusaurus.config.js

const config = {
  // ...
  url: 'https://<organizationName>.github.io',
  baseUrl: '/<projectName>/', // This is used for the site navigation.
  organizationName: '<username>', // Usually your GitHub org/user name.
  projectName: '<projectName>', // Usually your repo name.
  trailingSlash: false
  // ...
};

When you execute the command, Docusaurus will generate your files, push them to the gh-pages branch and your docs will be deployed.

To run the command use:

GIT_USER=<username> && USE_SSH=true && yarn deploy

Change the environment variables to suit your needs.