GitHub

This article outlines the custom configuration for GitHub Pages deployments.

npm

npm run deploy

Yarn

yarn deploy

pnpm

pnpm run deploy

Prerequisites

Using the docusaurus deploy command is a convenient way to build the website and push to the gh-pages branch

CLI

package.json

// ...
{
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "deploy": "docusaurus deploy",
  "dependencies": {
    "@docusaurus/core": "^3.5.2",
    "dotenv": "^16.4.5",
    // ...
  },
  }
}
// ...

Config

docusaurus.config.ts

const config: Config =  {
  // ...
  url: 'https://your-website-url.com',
  baseUrl: '/',
  projectName: 'you-project-name.github.io',
  organizationName: 'your-organization-name',
  deploymentBranch: 'gh-pages',
  trailingSlash: false,
  
    customFields: {
    GIT_USER: process.env.GIT_USER,
    USE_SSH: process.env.USE_SSH,
    GIT_USER_NAME: process.env.GIT_USER_NAME,
    GIT_USER_EMAIL: process.env.GIT_USER_EMAIL,
  },

};

GitHub Actions

Template 1

.github/workflows/deploy.yml

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: 'lts/*'

      - name: Install dependencies
        run: |
          cd website
          npm install
          npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: website/build

Template 2

.github/workflows/deploy.yml

name: GitHub Pages

on:
  push:
    branches:
      - main
    paths:
      - '.github/workflows/deploy.yml'
      - 'website/**'
  pull_request:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    defaults:
      run:
        working-directory: website
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

      - run: npm ci
      - run: npm run build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./website/build
      

Test Deployment

.github/workflows/test-deploy.yml

name: Test deployment

on:
  pull_request:
    branches:
      - main

jobs:
  test-deploy:
    name: Test deployment
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 'lts/*'

      - name: Install dependencies
        run: |
          cd website
          npm install
          npm run build