Deploy to GitHub Pages

By Amr

Deploy your Zer0-Mistakes Jekyll site to GitHub Pages with automatic builds.

Estimated reading time: 3 minutes

• Share on Reddit
• Share on LinkedIn
• Share on Twitter

• ---

• Page Improvements

• Improve Page Polish content, structure, and presentation of this page
• Expand Page Add depth, examples, and missing sections to this page
• Update Page Refresh outdated content, versions, links, and screenshots
• Fix Page Issue Report a typo, broken link, layout glitch, or content bug
• SEO Optimize Improve discoverability, metadata, and structured data
• Accessibility Audit Audit this page for WCAG 2.1 AA compliance

• ---

• Site Improvements

• UI/UX Improvement Propose a design or UX refinement for the theme
• New Feature Propose a new site-wide feature or capability
• Component Enhancement Improve a Jekyll layout, include, or shared component
• Performance Optimization Improve load time, Core Web Vitals, and asset delivery

Edit on GitHub

Table of Contents

Deploy to GitHub Pages

GitHub Pages provides free hosting for Jekyll sites with automatic builds on every push.

Prerequisites

• GitHub account
• Your Jekyll site in a GitHub repository

Setup

Step 1: Configure Your Repository

1. Go to your repository on GitHub
2. Navigate to Settings → Pages
3. Under Source, select your branch (usually main)
4. Click Save

Step 2: Configure Jekyll

Update your _config.yml for GitHub Pages:

# For user sites (username.github.io) — recommended for forks:
url: "https://username.github.io"
baseurl: ""  # Empty — user site deploys at root

# For project sites (username.github.io/repo-name):
# url: "https://username.github.io"
# baseurl: "/repository-name"

# Use remote theme for GitHub Pages compatibility
remote_theme: "bamr87/zer0-mistakes"

# Required plugins (GitHub Pages whitelist)
plugins:
  - jekyll-remote-theme
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-seo-tag

Tip: Fork into <your-username>.github.io so you don’t need to change baseurl at all. See docs/FORKING.md for the recommended workflow.

Step 3: Push and Deploy

git add .
git commit -m "Configure for GitHub Pages"
git push origin main

GitHub will automatically build and deploy your site.

Repository Types

User/Organization Site (Recommended for Forks)

• Repository name: username.github.io
• URL: https://username.github.io
• baseurl: ""
• No additional configuration needed — works out of the box with the theme defaults
• See Forking Guide

Project Site

• Repository name: Any other name
• URL: https://username.github.io/repository-name
• baseurl: "/repository-name" (must be set in _config.yml)

Custom Domain

To use a custom domain:

1. Go to Settings → Pages
2. Enter your domain in Custom domain
3. Check Enforce HTTPS
4. Configure DNS at your domain registrar

See Custom Domain Setup for detailed DNS configuration.

Troubleshooting

Build Failures

Check the Actions tab for build logs:

1. Go to repository → Actions
2. Click the failed workflow
3. Review error messages

Common issues:

• Invalid front matter (YAML syntax)
• Missing dependencies
• Plugin not in GitHub Pages whitelist

Site Not Updating

1. Verify the push was successful
2. Check Actions for build status
3. Wait a few minutes for CDN propagation
4. Try hard refresh (Ctrl+Shift+R)

404 Errors

• Check baseurl matches your repository name
• Verify file exists at the expected path
• Ensure front matter permalink is correct

GitHub Pages Limitations

Feature	Status
Custom plugins	Not supported (whitelist only)
Build time	~10 minutes max
Repository size	1 GB limit
Bandwidth	100 GB/month
Build minutes	10/hour, 2000/month

Alternative: GitHub Actions

For more control, use GitHub Actions to build:

# .github/workflows/jekyll.yml
name: Deploy Jekyll

on:
  push:
    branches: [main]

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

This allows custom plugins and more build control.

Next Steps

• Custom Domain Setup
• Netlify Deployment — For more hosting features

See also

• [[Deployment]]
• [[Custom Domain Setup]]
• [[Deploy to Netlify]]
• [[Docker]]