This guide covers common issues and their solutions. For more information, see FAQ.md or check GitHub Discussions.
Problem: GitHub Actions shows an error when deploying.
Solution:
_config.yml has correct url and baseurl:
url: https://username.github.io and baseurl: (empty)url: https://username.github.io and baseurl: /repo-name/main (or master) branch, NOT gh-pagesFor YAML syntax errors:
bundle exec jekyll build locally to see the exact error:, &, #) in YAML stringsProblem: You set a custom domain (e.g., example.com), but it resets to blank after deployment.
Solution:
CNAME (no extension) in your repository rootexample.com (one domain per line)(See DNS configuration instructions in INSTALL.md for initial custom domain setup.)
Problem: Local build works, but GitHub Actions fails with Unknown tag 'toc'.
Solution:
Deploy from a branchgh-pages (NOT main)Problem: docker compose up fails or shows errors.
Solution:
docker compose pulldocker compose up --buildFor permission issues:
sudo usermod -aG docker $USERProblem: Gemfile.lock conflicts or bundle errors.
Solution:
Gemfile.lock: rm Gemfile.lockbundle updatebundle installbundle exec jekyll serveProblem: “Address already in use” when running jekyll serve.
Solution - Docker:
docker compose down # Stop the running container
docker compose up # Start fresh
Solution - Local Ruby:
# Find and kill the Jekyll process
lsof -i :4000 | grep LISTEN | awk '{print $2}' | xargs kill
# Or specify a different port
bundle exec jekyll serve --port 5000
Problem: Site looks broken: no colors, fonts wrong, links don’t work.
Common cause: Incorrect url and baseurl in _config.yml.
Solution:
Personal/organization site:
url: https://username.github.io
baseurl: # MUST be empty (not deleted)
Project site:
url: https://username.github.io
baseurl: /repository-name/ # Must match your repo name
Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)Ctrl+F5 (Windows/Linux) or Cmd+R (Mac)Checklist:
baseurl correct (and not accidentally deleted)?Problem: You changed _config.yml color settings but nothing changed.
Solution:
_sass/_variables.scssdocker compose up --build (Docker) or bundle exec jekyll build (Ruby)Problem: Created a post in _posts/ but it’s not on the blog page.
Checklist:
YYYY-MM-DD-title.md (e.g., 2024-01-15-my-post.md)_posts/ directory (not in a subdirectory)---
layout: post
title: My Post Title
date: 2024-01-15
---
_config.yml: blog_page: trueTo fix:
bundle exec jekyll build and check for error messagesProblem: You added a BibTeX entry to papers.bib but it’s not showing on the publications page.
Checklist:
_bibliography/papers.bib@article{einstein1905, ...}publications_page: true in _config.ymlTo debug BibTeX errors:
# Local Ruby setup
bundle exec jekyll build 2>&1 | grep -i bibtex
# Docker
docker compose run --rm web jekyll build 2>&1 | grep -i bibtex
Problem: Image paths broken or showing as missing.
Common causes:
Solutions:
Correct path format:
assets/img/assets/pdf/@article{mykey,
pdf={my-paper.pdf}, % File should be at assets/pdf/my-paper.pdf
}
Problem: GitHub Actions fails with YAML error, or build is silent.
Common mistakes:
# ❌ Wrong: Unquoted colons or ampersands
title: My Site: Research & Teaching
# ✅ Correct: Quote special characters
title: "My Site: Research & Teaching"
# ❌ Wrong: Inconsistent indentation
nav:
- name: Home
url: /
- name: About # Extra space!
url: /about/
# ✅ Correct: Consistent 2-space indentation
nav:
- name: Home
url: /
- name: About
url: /about/
To find errors:
bundle exec jekyll build shows the exact error linebaseurl:)Problem: RSS feed at /feed.xml is empty or broken.
Solution:
_config.yml fields:
title: Your Site Title
description: Brief description
url: https://your-domain.com # MUST be absolute URL
baseurl is correctProblem: Search box is empty or always returns nothing.
Solution:
_config.yml:
search_enabled: true
_config.yml has a valid url (required for search)Problem: You enabled Giscus in _config.yml but comments don’t show.
Solution:
_config.yml has correct settings:
disqus_shortname: false # Make sure this is false
giscus:
repo: username/repo-name
repo_id: YOUR_REPO_ID
category_id: YOUR_CATEGORY_ID
Problem: Related posts feature crashes or shows errors.
Solution:
_config.yml, that’s fine:
related_blog_posts:
enabled: false
Gemfile has all dependencies installed:
bundle install
bundle exec jekyll build
Problem: Code blocks don’t have syntax highlighting or look wrong.
Solution:
Use proper markdown syntax:
```python
# Your code here
print("hello")
```
For inline code:
Use `code-here` for inline code.
Check that your language is supported by Pygments (Python, Ruby, JavaScript, etc. are all supported)
If you’re stuck:
Most issues are resolved by:
url and baseurl in _config.yml