Home › Blog › GitHub Pages Jekyll Theme: Complete Setup Guide (2026)
Tutorial

GitHub Pages Jekyll Theme: Complete Setup Guide (2026)

Everything you need to know about using Jekyll themes on GitHub Pages — supported themes, remote themes, deployment, and troubleshooting common issues.

Updated 5 min read
GitHub Pages Jekyll Theme: Complete Setup Guide (2026)

GitHub Pages is the most popular way to host a Jekyll site — it’s free, integrates directly with your repository, and rebuilds automatically on every push. This guide covers everything you need to set up a Jekyll theme on GitHub Pages correctly.

How GitHub Pages Builds Jekyll Sites

When you push to a GitHub Pages repository, GitHub runs Jekyll automatically on their servers. This means:

  • No build command needed
  • No server to manage
  • Free HTTPS via GitHub’s CDN
  • Automatic rebuilds on every commit

The limitation: GitHub Pages only supports a specific set of plugins. Themes that require unsupported plugins won’t build on GitHub Pages directly — you’ll need to use GitHub Actions instead.

Option 1: Use an Official GitHub Pages Theme

GitHub maintains 12 official themes that work on GitHub Pages without any plugin setup:

To use one, add to _config.yml:

theme: jekyll-theme-minimal

That’s it — no Gemfile changes needed for GitHub Pages.

Option 2: Use Any Theme via remote_theme

The jekyll-remote-theme plugin (supported by GitHub Pages) lets you use any public GitHub repository as a theme:

Step 1: Update _config.yml

remote_theme: mmistakes/minimal-mistakes
plugins:
  - jekyll-remote-theme

Step 2: Update Gemfile

source "https://rubygems.org"
gem "github-pages", group: :jekyll_plugins
gem "jekyll-remote-theme"

Step 3: Push to GitHub

git add .
git commit -m "Set up Jekyll theme"
git push

GitHub Pages builds your site automatically. Check the Actions tab in your repository to monitor the build.

For themes like Chirpy, Hydejack, or Just the Docs that use unsupported plugins, use GitHub Actions to build and deploy:

Step 1: Create .github/workflows/pages.yml

name: Deploy Jekyll site to Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
          bundler-cache: true
      - name: Build with Jekyll
        run: bundle exec jekyll build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  deploy:
    environment:
      name: github-pages
      url: $
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Step 2: Enable GitHub Pages via Actions

Go to Settings → Pages → Source and select GitHub Actions.

Setting Up Your Repository

Repository naming

Goal Repository name
User/org site yourusername.github.io
Project site Any name (served at yourusername.github.io/repo-name)

Essential _config.yml settings for GitHub Pages

url: "https://yourusername.github.io"
baseurl: ""  # Leave empty for user sites, "/repo-name" for project sites

title: "My Site"
author:
  name: "Your Name"
  email: "you@example.com"

Common mistake: Setting baseurl incorrectly causes broken asset links. For user sites (yourusername.github.io), always set baseurl: "".

Theme Type GitHub Pages Compatible
Minimal Mistakes Blog/Portfolio ✓ via remote_theme
Chirpy Blog ✓ via Actions
Just the Docs Documentation ✓ via Actions
Beautiful Jekyll Blog ✓ via remote_theme
Jekyll Now Blog ✓ direct fork
Hacker Developer ✓ official theme
Minimal Personal ✓ official theme

Troubleshooting Common GitHub Pages Issues

Build fails with “Dependency Error”

The theme uses a plugin not supported by GitHub Pages. Switch to GitHub Actions deployment.

Site builds but CSS is broken

Check your baseurl setting. For project sites it must be /repo-name, for user sites it must be "".

Changes not appearing

GitHub Pages can take 1–2 minutes to rebuild. Check the Actions tab for build status.

remote_theme not loading

Make sure jekyll-remote-theme is listed under plugins: in _config.yml and in your Gemfile.

References

github pages jekyll theme github pages jekyll tutorial
Share LinkedIn