Deployment

This article outlines the custom deployment configuration of this website for GitHub Pages and Cloudflare Pages deployments and assumes that you have knowledge of package managers, continuous integration, and workflows.

Configuration

Using the docusaurus build command is a convenient way to build the website and push to the gh-pages branch. Note that the following configuration is REQUIRED.

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

CLI

Here are some custom scripts that you can invoke with your package manager:

package.json

{
  // ...
  "scripts": {
    // ...
    "start:fast": "npm run docusaurus start -- --host 0.0.0.0 --no-open",
    "serve:fast": "docusaurus build && docusaurus serve --host 0.0.0.0 --no-open",
    "deploy:cf":"npm run build && wrangler pages deploy ./build",
    "rm:pckg": "pwsh -Command \"Remove-Item -Path 'node_modules', 'yarn.lock', 'package-lock.json' -Recurse -Force -ErrorAction SilentlyContinue\""
  }
}

Script	Description
start:fast	Does not automatically open in the browser and accessible externally or in your local network. Example: Run ipconfig /all and get your local address 192.168.0.150:3000
serve:fast	Does not automatically open in the browser and a combination of build and serve commands to build the static files of the website for production.

Alternative commands.

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build

npm

npm run build && npm run serve

Yarn

yarn build&& yarn serve

pnpm

pnpm run build&& pnpm run serve

npm

npm run build && npm run serve -- --build --port 80 --host 0.0.0.0

Yarn

yarn build&& yarn serve --build --port 80 --host 0.0.0.0

pnpm

pnpm run build&& pnpm run serve --build --port 80 --host 0.0.0.0

Bash

GIT_USER=<GITHUB_USERNAME> yarn deploy

Windows

cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"

Powershell

cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && npm run deploy'

SSH Deployments

Using SSH

USE_SSH=true yarn deploy

Not using SSH

GIT_USER=<Your GitHub username> yarn deploy

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: 20

      - 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
          cname: yourapp.pages.dev # Optional: For Cloudflare deployment

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: 20

      - 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
    # Review gh actions docs if you want to further define triggers, paths, etc
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

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: 20

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

Important

This website is currently being served on Cloudflare Pages, a platform known for its fast performance and scalability. However, the configuration of the site can be easily adjusted or updated at any time to meet new requirements or to incorporate changes. Whether you're looking to modify settings, update the content, or switch to a different hosting solution, you have the flexibility to reconfigure the website as needed.