GitHub Pages Deployment Guide

The Challenge

GitHub Pages is designed for static sites, but our starter kit is a dynamic Express.js application. We solved this by creating a build process that:

• Converts dynamic EJS templates to static HTML
• Fixes path issues for GitHub Pages subdirectories
• Automatically deploys via GitHub Actions

Step 1: Project Setup

First, make sure your project has the necessary build scripts and files:

Required Scripts

Add these scripts to your package.json:

{
  "scripts": {
    "clean": "node scripts/clean-docs.js",
    "copy-icons-docs": "node scripts/copy-icons.js --target=docs",
    "copy-static-assets": "node scripts/copy-static-assets.js",
    "generate-static-site": "node scripts/generate-static-site.js",
    "build-css": "sass --load-path=node_modules scss/main.scss docs/css/styles.css",
    "prebuild": "npm run clean",
    "build": "npm-run-all copy-icons-docs copy-static-assets build-css generate-static-site"
  }
}

Required Build Scripts

Create these files in your scripts/ directory:

• clean-docs.js - Cleans the output directory
• copy-icons.js - Copies Bootstrap Icons
• copy-static-assets.js - Copies JS, manifest, etc.
• generate-static-site.js - Converts EJS to HTML

Step 2: Build Process

Our build process solves several key challenges:

Run the Build

npm run build

This command will:

1. Clean the /docs directory
2. Copy Bootstrap Icons to /docs/fonts/
3. Copy static assets to /docs/
4. Compile SASS to /docs/css/
5. Generate static HTML files with correct paths

Step 3: GitHub Actions Setup

Create .github/workflows/deploy.yml for automatic deployment:

name: Build and Deploy to GitHub Pages

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "18"
          cache: "npm"

      - name: Install dependencies
        run: npm install

      - name: Build for GitHub Pages
        run: npm run build

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs
          force_orphan: true

Step 4: GitHub Pages Configuration

Configure your GitHub repository for Pages deployment:

1. Go to your repository on GitHub

   Navigate to your GitHub repository in a web browser.

2. Access Settings

   Click on the "Settings" tab in your repository.

3. Find Pages Section

   Scroll down and click on "Pages" in the left sidebar.

4. Configure Source

   Under "Source", select "Deploy from a branch".

5. Select Branch and Folder

   Choose "main" branch and "/docs" folder, then click "Save".

Step 5: Deploy Your Site

Now you're ready to deploy!

Manual Deployment

You can also deploy manually:

# Build the site locally
npm run build

# Commit and push the changes
git add .
git commit -m "Deploy to GitHub Pages"
git push origin main

Troubleshooting Common Issues