Host Docusaurus on Github Pages with Github Actions

Docusaurus is a powerful tool for technical documentation. It is a markdown based site generator that makes documenting your Open Source or company project a breeze. It supports MDX that allows the use of React components in markdown, making it more interactive and easy to reuse parts of your documentation. This tutorial shows how to host your Docusaurus site to Github using Github Actions. Github hosting is free for public repositories.

What we want:

1. When a new pull request is made to main, there's an action that ensures the site builds successfully, without actually deploying. This job will be called test-deploy.
2. When a pull request is merged to the main branch or someone pushes to the main branch directly, it will be built and deployed to GitHub Pages. This job will be called deploy.

Pre-requisites

• A working Docusaurus website
• A Github account
• A Github repository that hosts your Docusaurus source code
• This tutorial deploys code that is on the main branch
• This tutorial uses yarn
• The source and the deployment repositories are the same
• Your local builds serves correfctly via yarn serve

Open your /docusaurus.config.js and add the following infos:

| Name | Description | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | organizationName | The GitHub user or organization that owns the deployment repository. | | projectName | The name of the deployment repository. | | deploymentBranch | The name of the deployment branch. It defaults to'gh-pages' for non-organization GitHub Pages repos (projectName not ending in .github.io). Otherwise, it needs to be explicit as a config field or environment variable. |

Create a local github actions in your project at .github/workflows

# https://docusaurus.io/docs/deployment#deploy

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main  

permissions:
  contents: write

jobs:
  deploy:
    name: Deploy to GitHub Pages
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: yarn

      - name: Install dependencies
        run: yarn install --frozen-lockfile
      - name: Build website
        run: yarn build

      # Popular action to deploy to GitHub Pages:
      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          # Build output to publish to the `gh-pages` branch:
          publish_dir: ./build
          # The following lines assign commit authorship to the official
          # GH-Actions bot for deploys to `gh-pages` branch:
          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
          # The GH actions bot is used by default if you didn't specify the two fields.
          # You can swap them out with your own user credentials.
          user_name: github-actions[bot]
          user_email: <REDACTED>+github-actions[bot]@users.noreply.github.com

This code

• Is triggered on branch main
• Installs the Node project with yarn
• Build the Node project with yarn
• The peaceiris/actions-gh-pages@v3 action manages the gh-pages that will be used for deployment
• Deploys the docusaurus site on branch main with the GITHUB_TOKEN variable

• Wait for your action to build. This will create the gh-pages branch used for deployment

• Go to your Github repository > Settings > Pages

  • Source: choose Deploy from branch
  • Branch: choose gh-pages

After a minute refresh the page. The website should be deployed:

Let's head to ``:

Change the baseUrl on your docusaurus config to match the repository's name:

Push and wait for the action to be built then refresh the page:

Our website is available at https://servable-core.github.io/documentation/

We want our website to be available from our custom domain docs.servable.app.

Here is the official documentation for adding custom domains.

Once again in Settings > Page choose

Head to your DNS provider and create a CNAME record that points to your current deployment:

That's it.

When using custom domain make sure the baseUrl is reset to /

Inspirations and references

• https://docusaurus.io/docs/deployment#deploy