Repository navigation
how to contribute debugging
This page covers common errors encountered during local development and deployment, with step-by-step fixes.
Build fails with YAML parse error or a Liquid error pointing to _config.yml.
Special characters (:, &, #, |, >) in unquoted YAML string values.
# Wrong
title: My Site: Research & Teaching
# Right
title: "My Site: Research & Teaching"Other common mistakes:
- Inconsistent indentation (must be 2 spaces, no tabs).
- Missing closing quotes or braces.
- Deleting
baseurl:instead of leaving it empty.
bundle exec jekyll build 2>&1 | head -30
# Or use an online validator: https://www.yamllint.com/Site loads but has no styling, broken layout, or missing JavaScript functionality.
Incorrect url and baseurl in _config.yml.
For a personal/organization site:
url: https://username.github.io
baseurl: # Leave empty, do not delete the lineFor a project site:
url: https://username.github.io
baseurl: /repository-name/Then clear browser cache (Ctrl+Shift+R or open an incognito window) and redeploy.
Address already in use when starting the dev server.
docker compose down
docker compose uplsof -i :4000 | grep LISTEN | awk '{print $2}' | xargs kill
# Or use a different port:
bundle exec jekyll serve --port 5000docker compose up fails or exits with errors.
- Update the image:
docker compose pull. - Rebuild:
docker compose up --build. - Check disk space and available RAM.
- For M1/M2 Macs: update Docker Desktop.
- Linux: ensure your user is in the docker group —
sudo usermod -aG docker $USER(then log out and back in).
Local build works but CI fails.
Fix:
- Go to repo Settings → Pages → Source.
- Set it to
Deploy from a branch. - Ensure the branch is
gh-pages, notmain. - Wait a few minutes and re-run the workflow.
Related posts feature crashes.
Cause: Empty blog posts or posts with only stop words confuse classifier-reborn.
Fix: Add meaningful content to the post, or disable related posts in the post frontmatter:
related_posts: falsePR fails the prettier.yml CI check even though local builds passed.
npm install --save-dev prettier @shopify/prettier-plugin-liquid
npx prettier . --write
git add .
git commit -m "style: Format code with prettier"- Filename format:
YYYY-MM-DD-title.md(hyphens, no spaces). - File is in
_posts/, not a subdirectory. - Required frontmatter:
layout: post,title,date. - Date is not in the future (Jekyll skips future-dated posts by default).
- Blog is enabled:
blog.enabled: truein_config.yml.
- File is at
_bibliography/papers.bib. - BibTeX syntax is correct (no missing commas, unmatched braces).
- Entry has a unique citation key.
- Publications page is enabled in
_config.yml.
docker compose run --rm web jekyll build 2>&1 | grep -i bibtex- Wrong path in Markdown (use relative paths from repo root).
- File doesn't exist at the specified location.
- Case sensitivity matters on Linux/macOS.
For BibTeX PDF links, use just the filename:
pdf={my-paper.pdf} # Resolves to assets/pdf/my-paper.pdf- Enable in
_config.yml:search_enabled: true. - Ensure
_config.ymlhas a validurl. - Rebuild the site. The search index is generated during build.
- Check TROUBLESHOOTING.md in the repo root.
- Search GitHub Issues.
- Ask in Discussions.
- Testing — local verification and CI checks
- Development Workflow — Docker setup and build verification
- How to Contribute — PR process and commit conventions