Skip to main content

Deploying a Docusaurus Site to Github Pages

· 2 min read
Erik

When I first tried to deploy Docusaurus 2 site to Github Pages 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.

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",
// ...
}

Then 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. However, if you have some errors during deployment make sure your Github username and repository name is spelled correctly. I actually had a typo in mine and 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 suggested in the docs.

info

You'll have to run the deploy command every time you want to deploy. However, it's possible to automate that step when a git push or pull request merge occurs by setting up a Github Action. The documentation has template workflow yml files you can copy and paste into your project root directory. It should work, just ensure that if you're using NPM instead of Yarn to update the references.