Deployment Guide

This guide covers deploying your Jekyll site to GitHub Pages.

Automatic Deployment (Current Setup)

Your site is configured for automatic deployment via GitHub Pages. Every time you push to the main branch, GitHub automatically builds and deploys your site.

How It Works

1. You make changes locally
2. Commit and push to GitHub
3. GitHub Pages detects the push
4. GitHub builds your Jekyll site
5. Site is automatically deployed to https://joshuachelashaw.com

Deployment Workflow

1. Create or Edit Content

# Create a new blog post
nano _posts/2024-11-16-my-new-post.md

# Or edit existing files
nano index.md

2. Test Locally

Always test before deploying:

bundle exec jekyll serve
# Visit http://localhost:4000 to preview

3. Commit Changes

git add .
git commit -m "Add new blog post about [topic]"

4. Push to GitHub

git push origin main

5. Verify Deployment

• Wait 1-2 minutes for GitHub Pages to build
• Visit your site: https://joshuachelashaw.com
• Check the Actions tab on GitHub for build status

Deployment Checklist

Before pushing to production:

• Test site locally (bundle exec jekyll serve)
• Check all links work
• Verify images load correctly
• Test on mobile viewport
• Check both light and dark mode
• Proofread content
• Verify SEO descriptions are present
• Check that navigation works
• Clear browser cache and test

GitHub Pages Settings

Current Configuration

• Repository: stu-jc/stu-jc.github.io
• Branch: main
• Source: Root directory
• Custom Domain: joshuachelashaw.com
• HTTPS: Enabled

Checking Build Status

1. Go to your GitHub repository
2. Click the Actions tab
3. View the latest workflow run
4. Green checkmark = successful deployment
5. Red X = build failed (check logs)

Common Deployment Issues

Build Fails on GitHub

Check:

• _config.yml syntax is correct
• All front matter is valid YAML
• No syntax errors in Liquid templates
• All referenced files exist

Solution:

# Test build locally first
bundle exec jekyll build

# If it works locally but not on GitHub:
# 1. Check GitHub Pages settings
# 2. Review Actions logs for specific errors
# 3. Ensure Gemfile.lock is committed

Site Not Updating

Possible causes:

1. GitHub Pages cache (wait 5-10 minutes)
2. Browser cache (hard refresh: Cmd+Shift+R on Mac, Ctrl+Shift+R on Windows)
3. DNS cache if using custom domain

Solution:

# Force rebuild by making a commit
git commit --allow-empty -m "Trigger rebuild"
git push origin main

# Or clear browser cache

Custom Domain Not Working

Check:

1. CNAME file exists with domain name
2. DNS records point to GitHub Pages:

   A records:
   185.199.108.153
   185.199.109.153
   185.199.110.153
   185.199.111.153
   

3. HTTPS is enforced in repository settings

Advanced Deployment Options

Manual Build and Deploy

If you need to build locally and deploy manually:

# Build the site
bundle exec jekyll build

# The output is in _site/
# You can upload this directory to any web server

Using GitHub CLI

# Install GitHub CLI
brew install gh

# Authenticate
gh auth login

# Quick deploy workflow
git add .
git commit -m "Your message"
git push
gh pr create  # If using pull requests

Performance Optimization

Before Deploying

1. Optimize Images

   # Use ImageOptim or similar tools
   # Or use online tools like TinyPNG
   

2. Minify CSS (optional)

   # Add to _config.yml
   sass:
     style: compressed
   

3. Check Site Size

   du -sh _site/
   

Rollback Strategy

If Something Goes Wrong

Option 1: Revert Last Commit

git revert HEAD
git push origin main

Option 2: Reset to Previous Commit

git log  # Find the commit hash
git reset --hard <commit-hash>
git push --force origin main

Option 3: Use GitHub Web Interface

1. Go to repository on GitHub
2. Find the file that needs reverting
3. Click “History”
4. Find previous version
5. Click “…” → “View file”
6. Edit and commit

Monitoring

Check Site Health

# Test site is accessible
curl -I https://joshuachelashaw.com

# Check for broken links (install broken-link-checker)
npm install -g broken-link-checker
blc https://joshuachelashaw.com

Google Search Console

1. Add your site to Google Search Console
2. Submit your sitemap: https://joshuachelashaw.com/sitemap.xml
3. Monitor indexing and search performance

CI/CD Enhancements (Optional)

Add Custom GitHub Actions

Create .github/workflows/deploy.yml:

name: Deploy Jekyll site

on:
  push:
    branches: [ main ]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true
      - run: bundle exec jekyll build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: $
          publish_dir: ./_site

Deployment Timeline

• Local Changes: Instant
• Commit & Push: 1-5 seconds
• GitHub Build: 30-90 seconds
• DNS Propagation: 0-48 hours (only for domain changes)
• Total Time: Usually under 2 minutes

Quick Deploy Commands

Save these aliases in your ~/.zshrc or ~/.bash_profile:

# Quick deploy
alias deploy='git add . && git commit -m "Update site" && git push'

# Deploy with message
function deploym() {
    git add .
    git commit -m "$1"
    git push
}

# Use: deploym "Add new blog post"

Support

If deployment fails:

1. Check GitHub Status
2. Review GitHub Pages documentation
3. Check repository Actions tab for errors
4. Verify DNS settings at your domain registrar

Happy deploying! 🚀