Installation Guide

Whether you just downloaded a free theme or purchased a premium one, this guide walks you through every step — from a fresh install to a live site with your own domain.

Prerequisites

Before you begin, make sure you have the following installed on your machine:

• Ruby (version 2.7 or higher) — ruby-lang.org
• Bundler — install it with gem install bundler
• Git — git-scm.com
• A GitHub account (free) if you’re hosting on GitHub Pages

To verify your setup, run:

ruby -v
bundler -v
git --version

1. Installing a Jekyll Theme

Step 1 — Get the theme files

For free/open source themes, clone or download the theme repository:

git clone https://github.com/theme-author/theme-name.git my-site
cd my-site

For premium themes, unzip the downloaded archive and navigate into the folder:

unzip theme-name.zip -d my-site
cd my-site

Step 2 — Install dependencies

bundle install

This reads the Gemfile and installs Jekyll plus any plugins the theme requires.

Step 3 — Run locally

bundle exec jekyll serve

Open your browser at http://localhost:4000 — you should see the theme running. Jekyll will watch for file changes and rebuild automatically.

Step 4 — Customise the theme

Open _config.yml in your editor. At minimum, update:

title: "Your Site Name"
description: "A short description of your site"
url: "https://yourdomain.com"   # your final URL
author:
  name: "Your Name"
  email: "you@example.com"

Each theme has its own additional config options — refer to the theme’s own documentation for the full list.

2. Deploying to GitHub Pages

GitHub Pages is the simplest way to host a Jekyll site — it’s free, reliable, and Jekyll-native.

Step 1 — Create a GitHub repository

Go to github.com/new and create a new repository.

• For a user or organisation site (lives at yourusername.github.io), name it exactly yourusername.github.io
• For a project site (lives at yourusername.github.io/project), use any name you like

Step 2 — Push your site

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

Step 3 — Enable GitHub Pages

1. Go to your repository on GitHub
2. Click Settings → Pages (left sidebar)
3. Under Source, select Deploy from a branch
4. Choose branch main and folder / (root) → click Save

GitHub will build and deploy your site within a minute or two. The URL will be shown at the top of the Pages settings screen.

Step 4 — Check for unsupported plugins

GitHub Pages runs Jekyll in safe mode and only supports a whitelist of plugins. If your theme uses a plugin that isn’t on the list, you have two options:

• Use GitHub Actions to build and deploy (see below) — this removes the plugin restriction entirely
• Switch to Netlify, which has no plugin restrictions

Deploying via GitHub Actions (recommended for complex themes)

Create the file .github/workflows/deploy.yml in your repository:

name: Deploy Jekyll site

on:
  push:
    branches: [main]

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

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true

      - name: Build site
        run: bundle exec jekyll build
        env:
          JEKYLL_ENV: production

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: $
          publish_dir: ./_site

Then in Settings → Pages, change the source to Deploy from a branch → gh-pages.

3. Deploying to Netlify

Netlify is an excellent alternative to GitHub Pages — it supports all Jekyll plugins, deploys in seconds, and gives you a generous free tier with SSL included.

Step 1 — Push your site to GitHub

Netlify deploys from a Git repository, so make sure your site is pushed to GitHub (or GitLab / Bitbucket).

Step 2 — Connect Netlify to your repository

1. Go to netlify.com and sign in (or create a free account)
2. Click Add new site → Import an existing project
3. Choose GitHub and authorise Netlify
4. Select your repository from the list

Step 3 — Configure the build settings

Netlify will usually auto-detect Jekyll. Confirm these settings:

Click Deploy site. Netlify will build and publish your site — usually in under 30 seconds.

Step 4 — Add a netlify.toml file (recommended)

Adding a netlify.toml to your repository root locks in your build settings and makes them version-controlled:

[build]
  command   = "bundle exec jekyll build"
  publish   = "_site"

[build.environment]
  JEKYLL_ENV = "production"
  RUBY_VERSION = "3.2.0"

[[redirects]]
  from = "/*"
  to   = "/404.html"
  status = 404

Step 5 — Environment variables

For themes that use API keys or private config values, add them in Netlify under Site configuration → Environment variables rather than committing them to your repository.

4. Setting Up a Custom Domain

On GitHub Pages

1. Go to Settings → Pages in your repository
2. Under Custom domain, enter your domain (e.g. www.yourdomain.com) and click Save
3. GitHub will create a CNAME file at the root of your repository automatically

Then update your DNS records with your domain registrar:

For a www subdomain:

For an apex/root domain (e.g. yourdomain.com):

Wait for DNS propagation (up to 48 hours, usually much faster). Once active, tick Enforce HTTPS in the Pages settings.

On Netlify

1. In your Netlify site dashboard, go to Domain management → Add a domain
2. Enter your domain and click Verify
3. Netlify will show you the DNS records to add

For a www subdomain:

For an apex/root domain, Netlify recommends using their DNS or adding an ALIAS / ANAME record (not all registrars support this — check with yours):

Once your DNS is pointed at Netlify, SSL is provisioned automatically via Let’s Encrypt — no configuration needed.

5. Setting Up a Subdomain

A subdomain (e.g. blog.yourdomain.com) is useful if your Jekyll site is just one part of a larger project.

Add a CNAME record with your registrar:

Then follow the same custom domain steps above, entering blog.yourdomain.com as the custom domain in GitHub Pages or Netlify.

Update _config.yml to match:

url: "https://blog.yourdomain.com"
baseurl: ""

6. Keeping Your Theme Updated

Free / open source themes

If you cloned the theme repository directly, you can pull updates:

git remote add upstream https://github.com/theme-author/theme-name.git
git fetch upstream
git merge upstream/main

Resolve any merge conflicts (usually in _config.yml or your custom files), then push.

Premium themes

Premium themes ship as a zip download. When an update is released:

1. Download the new version
2. Carefully compare _config.yml changes and apply them to your own config
3. Replace the theme’s core files (_layouts, _includes, _sass, assets) while preserving your content (_posts, _pages, etc.)

7. Common Issues

bundle install fails with a Ruby version error The theme requires a different Ruby version than you have installed. Use a Ruby version manager like rbenv or RVM to switch versions:

rbenv install 3.2.0
rbenv local 3.2.0
bundle install

GitHub Pages shows a build error Go to your repository → Settings → Pages and look for the error message. Common causes are an unsupported plugin or a Liquid syntax error in your content.

CSS/JS not loading after deploying to a subdirectory Set baseurl in _config.yml to match your subdirectory path:

baseurl: "/my-project"  # for yourusername.github.io/my-project
url:     "https://yourusername.github.io"

Site builds fine locally but is broken on GitHub Pages Run JEKYLL_ENV=production bundle exec jekyll serve locally to simulate the production environment and surface any environment-specific errors.

Need Help?

• Browse themes and read individual theme documentation on JekyllHub
• Check the official Jekyll documentation
• Ask the community on the Jekyll Talk forum
• Email us at hello@jekyllhub.com