GitHub Pages Deployment for Docusaurus

Complete workflow for deploying Docusaurus multi-instance educational textbooks to GitHub Pages with GitHub Actions automation.

Overview

This skill provides:

•GitHub Actions CI/CD workflows for automated deployment
•Multi-instance deployment support (main-site + module sites)
•Custom domain configuration with HTTPS
•Build optimization for production
•Caching strategies for faster builds
•Troubleshooting guides for common issues

Prerequisites

•Node.js 20+ (LTS)
•npm 9+
•Git repository with Docusaurus project
•GitHub repository with Pages enabled
•Repository write access (for Actions)

Quick Start

Option 1: Single Site Deployment

bash

# 1. Configure docusaurus.config.js
url: 'https://<username>.github.io',
baseUrl: '/<repo-name>/',
organizationName: '<username>',
projectName: '<repo-name>',

# 2. Copy workflow file
cp .claude/skills/github-pages-deploy/templates/deploy-single.yml .github/workflows/deploy.yml

# 3. Push to trigger deployment
git add . && git commit -m "Add deployment workflow" && git push

Option 2: Multi-Instance Deployment (This Project)

bash

# 1. Run setup script
node .claude/skills/github-pages-deploy/scripts/setup-deployment.js

# 2. Configure GitHub repository settings
# Settings > Pages > Source: GitHub Actions

# 3. Push changes
git add . && git commit -m "Configure GitHub Pages deployment" && git push

Deployment Architecture

Single Site Flow

code

main branch push
    └── GitHub Actions Workflow
        ├── Checkout code
        ├── Setup Node.js (cached)
        ├── Install dependencies (cached)
        ├── Build site (npm run build)
        └── Deploy to GitHub Pages
            └── https://<user>.github.io/<repo>/

Multi-Instance Flow (This Project)

code

main branch push
    └── GitHub Actions Workflow
        ├── Checkout code
        ├── Setup Node.js (cached)
        ├── Install dependencies (cached)
        ├── Build all sites in parallel:
        │   ├── main-site → /physical-ai-textbook/
        │   ├── module1-ros2 → /physical-ai-textbook/module1/
        │   ├── module2-simulation → /physical-ai-textbook/module2/
        │   ├── module3-isaac → /physical-ai-textbook/module3/
        │   └── module4-vla → /physical-ai-textbook/module4/
        ├── Merge build outputs
        └── Deploy combined site to GitHub Pages

Phase 1: Configuration Setup

Step 1: Verify Docusaurus Config

Each Docusaurus instance needs these settings in docusaurus.config.js:

javascript

const config = {
  // Production URL (your GitHub Pages URL)
  url: 'https://physical-ai-course.github.io',

  // Base path (repository name for project sites)
  baseUrl: '/physical-ai-textbook/',

  // GitHub deployment config
  organizationName: 'physical-ai-course', // GitHub org/username
  projectName: 'physical-ai-textbook',    // Repository name

  // Deployment branch (usually 'gh-pages')
  deploymentBranch: 'gh-pages',

  // Use trailing slash for consistency
  trailingSlash: false,

  // Error handling
  onBrokenLinks: 'warn',
  onBrokenMarkdownLinks: 'warn',
};

Step 2: Module-Specific baseUrl

For multi-instance deployments, each module needs unique baseUrl:

Site	baseUrl	Final URL
main-site	`/physical-ai-textbook/`	`https://...github.io/physical-ai-textbook/`
module1-ros2	`/physical-ai-textbook/module1/`	`https://...github.io/physical-ai-textbook/module1/`
module2-simulation	`/physical-ai-textbook/module2/`	`https://...github.io/physical-ai-textbook/module2/`
module3-isaac	`/physical-ai-textbook/module3/`	`https://...github.io/physical-ai-textbook/module3/`
module4-vla	`/physical-ai-textbook/module4/`	`https://...github.io/physical-ai-textbook/module4/`

See references/docusaurus-config.md for complete configuration examples.

Phase 2: GitHub Actions Setup

Step 1: Create Workflow Directory

bash

mkdir -p .github/workflows

Step 2: Copy Appropriate Workflow

For multi-instance deployment (this project):

bash

cp .claude/skills/github-pages-deploy/templates/deploy-multi-instance.yml .github/workflows/deploy.yml

For single site deployment:

bash

cp .claude/skills/github-pages-deploy/templates/deploy-single.yml .github/workflows/deploy.yml

Step 3: Enable GitHub Pages

•Go to repository Settings
•Navigate to Pages (left sidebar)
•
Under Build and deployment:
- •Source: Select GitHub Actions
•Save changes

Step 4: Configure Repository Permissions

•Go to Settings > Actions > General
•Scroll to Workflow permissions
•Select Read and write permissions
•Check Allow GitHub Actions to create and approve pull requests
•Save

Phase 3: Build Scripts

Add Build Scripts to Root package.json

json

{
  "scripts": {
    "build": "npm run build:all",
    "build:all": "npm run build:main && npm run build:modules",
    "build:main": "npm run build --workspace=main-site",
    "build:modules": "npm run build:module1 && npm run build:module2 && npm run build:module3 && npm run build:module4",
    "build:module1": "npm run build --workspace=module1-ros2",
    "build:module2": "npm run build --workspace=module2-simulation",
    "build:module3": "npm run build --workspace=module3-isaac",
    "build:module4": "npm run build --workspace=module4-vla",
    "build:deploy": "node .claude/skills/github-pages-deploy/scripts/build-for-deploy.js"
  }
}

Phase 4: Deployment Verification

Local Build Test

bash

# Install dependencies
npm install

# Build all sites
npm run build:all

# Check build outputs
ls -la main-site/build/
ls -la module1-ros2/build/
ls -la module2-simulation/build/
ls -la module3-isaac/build/
ls -la module4-vla/build/

Local Preview

bash

# Serve main site build
npx serve main-site/build

# Or use Docusaurus serve
cd main-site && npm run serve

Post-Deployment Verification

After GitHub Actions completes:

•Check Actions tab for successful run
•Visit your GitHub Pages URL
•Verify all module links work
•Test navigation between modules
•Check assets load correctly (images, CSS, JS)

Troubleshooting

See references/troubleshooting.md for detailed solutions.

Quick Fixes

Issue	Cause	Solution
404 on deployment	Wrong baseUrl	Verify baseUrl matches repo name
CSS not loading	Asset path mismatch	Check url and baseUrl in config
Module links broken	Cross-instance linking	Use absolute URLs for module links
Build fails	Node version	Ensure Node 20+ in workflow
Permissions denied	Actions permissions	Enable read/write in repo settings

Custom Domain Setup

Step 1: Add CNAME

Create static/CNAME in main-site:

code

yourdomain.com

Step 2: Configure DNS

Add these DNS records at your domain registrar:

For apex domain (example.com):

code

A    @    185.199.108.153
A    @    185.199.109.153
A    @    185.199.110.153
A    @    185.199.111.153

For subdomain (docs.example.com):

code

CNAME    docs    <username>.github.io.

Step 3: Update docusaurus.config.js

javascript

url: 'https://yourdomain.com',
baseUrl: '/',  // Change to / for custom domain

Step 4: Enable HTTPS

•Go to Settings > Pages
•Check Enforce HTTPS

Resources

•
Templates: templates/
- •deploy-single.yml - Single site workflow
- •deploy-multi-instance.yml - Multi-instance workflow
•
Scripts: scripts/
- •setup-deployment.js - Automated setup
- •build-for-deploy.js - Build merger script
•
References: references/
- •docusaurus-config.md - Configuration guide
- •troubleshooting.md - Common issues
- •custom-domain.md - Domain setup guide

GitHub Pages Deployment for Docusaurus

Overview

Prerequisites

Quick Start

Option 1: Single Site Deployment

Option 2: Multi-Instance Deployment (This Project)

Deployment Architecture

Single Site Flow

Multi-Instance Flow (This Project)

Phase 1: Configuration Setup

Step 1: Verify Docusaurus Config

Step 2: Module-Specific baseUrl

Phase 2: GitHub Actions Setup

Step 1: Create Workflow Directory

Step 2: Copy Appropriate Workflow

Step 3: Enable GitHub Pages

Step 4: Configure Repository Permissions

Phase 3: Build Scripts

Add Build Scripts to Root package.json

Phase 4: Deployment Verification

Local Build Test

Local Preview

Post-Deployment Verification

Troubleshooting

Quick Fixes

Custom Domain Setup

Step 1: Add CNAME

Step 2: Configure DNS

Step 3: Update docusaurus.config.js

Step 4: Enable HTTPS

Resources

External Resources