How to Use a Jekyll Theme on GitHub Pages

—> Download the Guide

ℹ

About this guideThis guide walks you through finding a free Jekyll theme, forking it on GitHub, customizing the content, and publishing it as a live website using GitHub Pages — all for free and without needing to install anything on your computer.

✦

PrerequisitesYou will need a free GitHub account (github.com). No coding experience is required, though basic familiarity with editing text files is helpful. All steps are completed in the browser unless noted.

Part 1

What is Jekyll?

Jekyll is a tool that converts plain text files into a complete website. Instead of writing every page in full HTML, you write your content in a simpler format called Markdown, and Jekyll assembles the final site for you using a theme you have chosen.

GitHub Pages has Jekyll built in, which means you can use any Jekyll theme simply by putting the right files in your repository — no installation or command line needed.

Key concepts

Term What it means
Jekyll The tool that builds your site from plain text files and a theme
Theme A pre-designed set of layouts, colours, and styles for your site
Markdown (.md) A simple way to write formatted text — much easier than HTML
_config.yml The main settings file for your Jekyll site (title, author, theme, etc.)
Front matter A block at the top of each page that sets its title, layout, and other options
Fork Making your own copy of someone else’s GitHub repository
Repository (repo) A folder on GitHub that holds all your website files
GitHub Pages GitHub’s free hosting service that publishes your repo as a live website

Part 2

Choose a Jekyll Theme

The fastest way to get a great-looking site is to start with a theme someone else has already built. There are hundreds of free, open-source Jekyll themes available.

Where to find themes

Recommended themes for students

Theme name Best for
Minimal Mistakes Portfolios, blogs, documentation — very popular and well documented
al-folio Academic portfolios, research pages, CVs
Chirpy Blogs and note-taking sites with a clean dark/light mode
Beautiful Jekyll Beginners — simple setup, clear instructions
Cayman (official) Simple project pages and landing pages
Minima (official) The Jekyll default — clean, minimal, great for learning

✦

Recommendation for beginnersStart with Beautiful Jekyll (github.com/daattali/beautiful-jekyll). It has an explicit beginner setup guide, needs no installation, and looks professional straight away.

Part 3

Fork the Theme & Go Live

Forking creates your own copy of the theme’s repository on your GitHub account. You then rename it so GitHub Pages publishes it as your website. No files need to be downloaded.

Step-by-step: fork and publish

1

Find the theme’s GitHub repository

Go to the theme’s GitHub page. For Beautiful Jekyll, this is github.com/daattali/beautiful-jekyll. For other themes, find the GitHub link on the theme gallery page.

2

Fork the repository

Click the Fork button near the top-right of the repository page. GitHub will ask where to fork it — choose your own account. After a few seconds you will have your own copy of the repository.

3

Rename the repository

Go to Settings in your forked repository. Under the Repository name field, change the name to: yourusername.github.io (replacing yourusername with your actual GitHub username). Click Rename.

ℹ

Why this name? GitHub Pages looks for a repository named yourusername.github.io and automatically publishes it as your personal site at that address.
4

Enable GitHub Pages

Go to Settings → Pages in your repository. Under Source, select Deploy from a branch. Choose the main branch (or master, depending on the theme) and click Save.

5

Wait for your site to go live

GitHub will build your site using Jekyll. This usually takes 1–3 minutes. Go back to Settings → Pages and refresh until you see a green banner with your live URL.

6

Visit your live site

Your site is now live at https://yourusername.github.io — it will look exactly like the theme’s demo until you customise it.

Part 4

Customise Your Site

All customisation is done by editing files directly in GitHub’s browser editor. Click any file in your repository, then click the pencil icon to edit it. When you save (commit), your live site updates within a minute or two.

4.1 — Edit _config.yml

This is the most important file. It controls your site’s title, description, author name, and many other settings. Click _config.yml in your repository to open it. A typical _config.yml looks like this:

title: My Website
description: A site about my work and projects
author: Jane Smith
email: jane@example.com

# Theme setting (do not change unless switching themes)
theme: minima

# Social links (delete lines you do not want)
github_username: janesmith
twitter_username: janesmith

What to edit:

  • title — the name of your site, shown in the browser tab and header
  • description — a short tagline shown in some themes and in search results
  • author — your name
  • email — your contact email (only add this if you are happy for it to be public)
  • github_username / twitter_username — adds social links automatically
  • url — set this to https://yourusername.github.io

⚠

Important: YAML files are sensitive to spacing. Use exactly 2 spaces for indentation — never tabs. A single formatting error will stop your site from building.

4.2 — Edit or Replace Pages

Most themes include a homepage (index.md or index.html) and an About page (about.md). Click either file to edit it.

Understanding front matter

Every Jekyll page starts with a block of settings between triple dashes. This is called front matter:

---
layout: page
title: About Me
permalink: /about/
---

Write your page content here using Markdown.

## My Background
I am a student studying computer science...

Front matter fields:

  • layout — which design template to use (e.g. page, post, home)
  • title — the page title shown in the browser and often in the page header
  • permalink — the URL path for this page
  • date — used on blog posts (format: YYYY-MM-DD)

4.3 — Writing Content in Markdown

Jekyll pages and blog posts are written in Markdown — a simple system where plain text symbols create formatted output. Here are the most useful elements:

# Heading 1  (large title)
## Heading 2  (section heading)
### Heading 3  (sub-section heading)

Normal paragraph text — just type freely.

**Bold text**   and   _italic text_

- Bullet point one
- Bullet point two

1. Numbered item one
2. Numbered item two

[Link text](https://example.com)
![Image alt text](/assets/img/photo.jpg)

`inline code`

```
code block
```

✦

Tip: You can preview your Markdown as you write using dillinger.io or the GitHub editor’s Preview tab. No need to wait for your site to rebuild each time.

4.4 — Adding Blog Posts

Jekyll treats files in the _posts folder as blog posts. Each filename must follow this exact format:

YYYY-MM-DD-your-post-title.md

For example: 2024-03-15-my-first-post.md

Creating a new post:

  • In your repository, click the _posts folder
  • Click Add file → Create new file
  • Name it using the date format above
  • Add front matter at the top, then write your content below it
  • Commit the file — your post will appear on your site within a minute
---
layout: post
title: My First Post
date: 2024-03-15
categories: [blog, general]
---

Welcome to my blog. This is my first post.

## What I have been working on

This week I started learning about...

4.5 — Adding Images

Most themes include an assets folder (often assets/img or images) for storing images.

  • Navigate to the assets/img folder (create it if it does not exist)
  • Click Add file → Upload files, drag your image in and commit
  • Reference the image in your Markdown like this:
![Description of image](/assets/img/your-image.jpg)

✦

File names: Use lowercase letters and hyphens instead of spaces (e.g. my-photo.jpg not My Photo.jpg). Spaces in file names cause errors on GitHub Pages.

4.6 — Changing the Theme’s Colours and Fonts

Most themes have a dedicated CSS or SCSS file for customising colours and fonts. Look for files such as:

assets/css/main.scss
_sass/variables.scss
_sass/_variables.scss
assets/css/style.scss

Open this file and look for colour variables near the top:

// Primary colours — change these to customise your site
$primary-color: #4B2E83;
$link-color: #7B52AB;
$background-color: #FFFFFF;
$text-color: #222222;

// Font settings
$font-family: 'Georgia', serif;
$font-size-base: 16px;

✦

Colour codes: Colours are written as 6-digit hex codes (e.g. #4B2E83). You can find hex codes for any colour by searching ‘colour picker’ in Google.

Part 5

File Structure Reference

Understanding what each file and folder does will help you find the right file to edit.

File or folder Purpose
_config.yml Main settings file: site title, author, theme, plugins, social links
index.md / index.html Your homepage content
about.md Your About page (some themes call this about.html)
_posts/ Folder containing blog posts, named YYYY-MM-DD-title.md
_layouts/ HTML templates that define the structure of each page type
_includes/ Reusable HTML snippets (header, footer, navigation)
_sass/ or _css/ Stylesheets controlling colours, fonts, and layout
assets/ Images, custom CSS, and JavaScript files
_site/ The built output Jekyll generates — do not edit this directly
Gemfile Lists the Ruby gems (plugins) the site depends on
README.md Description of the theme, shown on GitHub but not on your site

Part 6

Troubleshooting

Most problems with Jekyll and GitHub Pages are caused by one of a small number of common issues. Work through this section before asking for help.

Checking build errors

When GitHub Pages fails to build your site, it sends an email to your GitHub account address. You can also check via your repository’s Actions tab — a red cross indicates a failed build.

  • Click the failed build in the Actions tab
  • Click the build job to expand it
  • Look for the error message in the logs — it usually names the file and line with the problem

Common problems and fixes

Problem Most likely cause and fix
Site not updating after commit GitHub Pages can take 1–3 minutes. Wait and do a hard refresh (Ctrl+Shift+R). Check the Actions tab for build errors.
Build error: YAML exception _config.yml has a formatting error. Check for tabs instead of spaces, or a missing colon. YAML requires exactly 2-space indentation.
Images not showing Check the file path is correct and uses forward slashes. File names are case-sensitive on GitHub — photo.jpg and Photo.jpg are different files.
Page shows raw Markdown text The front matter block is missing or malformed. Make sure — appears on its own line at the very top of the file with no spaces before it.
Blog post not appearing Check the filename follows YYYY-MM-DD-title.md exactly. Also check the date is not in the future.
Styles look broken or missing A path in _config.yml is wrong. Make sure baseurl is empty (”) and url is set to https://yourusername.github.io
Site shows 404 page GitHub Pages is not enabled, or the repo is not named correctly. Go to Settings → Pages and check the source branch is set.
Changes to _config.yml not applying _config.yml changes require a full rebuild. Make a trivial edit to another file and commit it to trigger a new build.

Useful debugging steps

  • Always check the Actions tab first — the error message is usually specific and searchable
  • Validate your YAML at yamllint.com by pasting your _config.yml contents
  • Validate your Markdown at markdownlint.com if pages look wrong
  • If the whole site looks broken after a change, revert the last commit by clicking the commit history, finding the previous version, and restoring it
  • Search the theme’s GitHub Issues page — someone has likely had the same problem

Part 7

Going Further

Add a custom domain

You can attach a real domain name (e.g. yourname.com) to your GitHub Pages site for free — you only pay for the domain itself (~£8–12/year). In your repository, go to Settings → Pages → Custom domain, enter your domain, and follow the DNS instructions. GitHub provides a free SSL certificate automatically.

Use Jekyll plugins

GitHub Pages supports a small set of approved Jekyll plugins. Useful ones include:

  • jekyll-seo-tag — automatically adds SEO metadata to every page
  • jekyll-sitemap — generates a sitemap.xml for search engines
  • jekyll-feed — generates an RSS feed of your blog posts

To enable a plugin, add it to the plugins section of _config.yml:

plugins:
  - jekyll-seo-tag
  - jekyll-sitemap
  - jekyll-feed

Set up Jekyll locally (optional)

Installing Jekyll locally lets you preview changes instantly in your browser before committing.

  • Install Ruby from ruby-lang.org (required by Jekyll)
  • Run: gem install bundler jekyll in your terminal
  • Clone your repository using GitHub Desktop or git clone
  • Run: bundle exec jekyll serve inside the project folder
  • Open http://localhost:4000 in your browser to see a live preview

✦

GitHub Desktopdesktop.github.com is a free visual app that makes cloning, committing, and pushing changes much easier than using the command line. Recommended for students new to Git.

Recommended learning resources

  • Jekyll documentation — jekyllrb.com/docs — the official reference, well written for beginners
  • GitHub Pages documentation — docs.github.com/pages — covers advanced topics like custom domains and actions
  • GitHub Skills — skills.github.com — free interactive courses including a dedicated GitHub Pages course
  • Markdown Guide — markdownguide.org — complete reference for Markdown syntax
  • MDN Web Docs — developer.mozilla.org — the best reference for HTML and CSS when you want to go deeper

Jekyll & GitHub Pages Guide · For Students