Troubleshooting

Having problems? This guide covers common issues and how to fix them.

Images Not Showing

Problem: Your image code looks correct but the image doesn’t appear.

Common causes:

1. File path doesn’t match actual location

Check:

{% include images/figure.html
  image-path="images/photo.jpg"   ← Must match actual location
%}

2. Filename doesn’t match EXACTLY

File names are case-sensitive! Check:

Fix: Make sure your code matches the filename EXACTLY, including capitalization and extension.

3. Relative vs. Absolute paths

Recommendation: Always use absolute paths starting with / to avoid confusion.

Site Not Updating / Build Failed

Problem: You made changes but your site isn’t updating after 5+ minutes, or GitHub Actions shows a build failure.

Most common cause: A syntax error is preventing Jekyll from building your site.

Step-by-step fix:

Step 1: Find the error

Step 2: Understand what it’s telling you The error message usually looks like:

Liquid Exception: Liquid syntax error (line 42): Expected end_of_string but found...
  in /home/runner/work/my-site/guides/getting-started.md

This tells you:

Step 3: Go to that file and fix it

Step 4: Save your fix

Step 5: Check if it worked

Syntax Errors in Include Blocks

Problem: Your component code isn’t working.

Common mistakes:

1. Missing or incorrect delimiters

❌ Wrong:

{ include figure.html %}           ← Missing %
{& include figure.html %}          ← Wrong symbol
{% include images/figure.html }           ← Missing %

✅ Correct:

{% include images/figure.html %}

2. Mismatched quotes

❌ Wrong:

{% include images/figure.html
  caption="This is broken'        ← Mismatch " and '
  width='50%"                     ← Mismatch ' and "
%}

✅ Correct:

{% include images/figure.html
  caption="This works correctly"
  width="50%"
%}

3. Missing closing tag

❌ Wrong:

{% include images/figure.html
  image-path="/assets/images/photo.jpg"

✅ Correct:

{% include images/figure.html
  image-path="/assets/images/photo.jpg"
%}                                ← Don't forget closing %}

YAML Front Matter Errors

Problem: Page won’t build due to front matter issues.

Every page needs front matter at the very top:

✅ Correct:

---
title: My Page
layout: xanthan
date: 2024-12-02
---

# Page content starts here

Common mistakes:

❌ Must start on first line (no blank lines before ---) ❌ Must have three dashes --- not two -- ❌ Must close with --- on its own line ❌ Indentation matters in YAML (use spaces, not tabs)

Problem: Links to other pages return 404 errors.

Check:

  1. File extension in URL:
    • Link to /about not /about.md
    • Jekyll converts .md to .html automatically
  2. Correct path: 
    ❌ [Link](guides/getting-started.md)
✅ [Link](/guides/getting-started)
✅ [Link](guides/getting-started)
  3. Baseurl issues:
    • If using a project site (not username.github.io), check _config.yml
    • Baseurl should be /repository-name/

Styles Not Applying

Problem: CSS changes aren’t showing up.

  1. Hard refresh your browser:
    • Windows/Linux: Ctrl + Shift + R
    • Mac: Cmd + Shift + R
  2. Check file location:
    • CSS files should be in /assets/css/
    • Linked correctly in _includes/page-header.html
  3. CSS syntax errors:
    • Missing semicolons ;
    • Unclosed brackets }
    • Invalid property names

Still Stuck?

Before asking for help:

  1. Check the error message - It usually tells you exactly what’s wrong
  2. Compare your code to working examples on the component pages
  3. Look for typos - Most issues are small syntax errors
  4. Try removing recent changes - Did it work before? What changed?

Getting help: