Deploying a Docusaurus Site to Github Pages

When I first tried to deploy a Docusaurus 2 site to Github Pages after following the Docusaurus Github Pages instructions it didn't quite work. It took a bit of trial and error, but I finally got it down. Some of it was human error on my part.

Instructions

The first step is to enable Github Pages in your repository settings. I chose the Classic Pages option in the Source dropdown.

Then update your docusaurus.config.js to include the following values:

docusaurus.config.js

const config = {
  // ...
  organizationName: 'your_github_username',
  projectName: 'your_github_repo_name',
  trailingSlash: false,
  deploymentBranch: "gh-pages",
  // ...
}

Finally, if you're using npm you can run:

npm run deploy

or if you're using yarn

yarn deploy

This will deploy it to Github Pages. If you encounter some errors during deployment make sure your Github username and repository name are spelled correctly. I actually had a typo in mine that had me scratching my head. It actually took a while to realize it. 🤦🏻‍♂️

note

I have SSH keys set up so didn't have to use GIT_USER=<GITHUB_USERNAME> before the deployment command as was suggested in the docs.

info

You'll have to run the deploy script every time you want to deploy. However, it's possible to automate this step by setting up a Github Action. This way when a git push or pull request merge occurs it will automatically kick off a deployment.

The Docusaurus documentation site has workflow templates written in .yml files, which you can copy and paste into your project root directory. It should work once that is done, just ensure that if you're using NPM instead of Yarn to update the references appropriately in the template!

Instructions​

Instructions