Deploying Your Thesis to GitHub Pages

Step-by-step guide to get your thesis live at https://yourusername.github.io/thesis

Prerequisites

1 — Test locally first

1
2
3

cd jekyll-theme
bundle install
bundle exec jekyll serve --livereload

Open http://localhost:4000 — you should see your thesis homepage.
The --livereload flag auto-refreshes the browser when you save a file.

2 — Create a GitHub repository

  1. Go to github.com/new
  2. Name it thesis (or anything — you’ll use this in the URL)
  3. Set visibility: Public (required for free GitHub Pages)
  4. Do not initialise with a README — you’ll push your own files

3 — Push the theme to GitHub

Inside your jekyll-theme/ folder:

1
2
3
4
5
6

git init
git add .
git commit -m "Initial thesis theme"
git branch -M main
git remote add origin https://github.com/YOURUSERNAME/thesis.git
git push -u origin main

4 — Enable GitHub Pages

  1. Go to your repo on GitHub
  2. Click Settings → Pages (left sidebar)
  3. Under Source, select:
    • Branch: main
    • Folder: / (root)
  4. Click Save

GitHub will show a green banner: “Your site is published at https://yourusername.github.io/thesis”

It takes 1–3 minutes to build on the first deploy.

5 — Update _config.yml

Set the correct baseurl and url so links work:

1
2

baseurl: "/thesis"          # your repo name, with leading slash
url: "https://yourusername.github.io"

Then commit and push:

1
2
3

git add _config.yml
git commit -m "Set baseurl for GitHub Pages"
git push

6 — Subsequent updates

Every git push to main triggers an automatic rebuild (~1 min):

1
2
3

git add .
git commit -m "Add Chapter 5 content"
git push

Check the Actions tab in your repo to watch the build status.

Troubleshooting

Problem Fix
Site shows 404 Check baseurl in _config.yml matches your repo name exactly
CSS not loading Make sure baseurl is set — links need the prefix
Build fails Check Actions tab → click the failed run → read the error
Chapters not appearing Filenames in _chapters/ must end in .md; check front matter chapter: field
Local build fails Run bundle update to refresh dependencies

Custom domain (optional)

To use thesis.yourname.com instead of the GitHub URL:

  1. Buy a domain (Namecheap, Cloudflare, etc.)
  2. Add a CNAME file to your repo root containing just: thesis.yourname.com
  3. In your domain registrar, add a CNAME DNS record pointing to yourusername.github.io
  4. In GitHub repo Settings → Pages, enter your custom domain
  5. Tick Enforce HTTPS

DNS propagation takes 10–60 minutes.

Keeping the theme updated

If you make changes to CSS or JS locally, preview with bundle exec jekyll serve
before pushing — GitHub Pages builds can take a minute and it’s faster to catch
issues locally.

For larger edits (new features, layout changes), work on a dev branch
and merge to main when ready:

1
2
3
4
5
6

git checkout -b dev
# make changes…
git add . && git commit -m "New feature"
git checkout main
git merge dev
git push