Troubleshooting

This guide covers common issues you might encounter and how to resolve them.

Build Errors

Gemfile Lock Conflict

Error:

Could not find gem 'jekyll (~> 4.3)' in any of the gem sources

Solution: Delete Gemfile.lock and reinstall:

rm Gemfile.lock
bundle install

Plugin Not Found

Error:

Unknown tag 'include components/...'

Solution: Ensure all plugins are in your Gemfile:

group :jekyll_plugins do
  gem "jekyll-feed"
  gem "jekyll-seo-tag"
  gem "jekyll-sitemap"
  gem "jekyll-paginate-v2"
end

Then run:

bundle install

Liquid Syntax Error

Error:

Liquid syntax error: Unknown tag 'raw'

Solution: This usually means you’re using Liquid tags in a context where they’re not supported. Wrap code examples in raw/endraw tags to prevent Liquid processing.

YAML Front Matter Error

Error:

YAML Exception: mapping values are not allowed here

Solution: Check your front matter for:

Missing colons
Incorrect indentation
Special characters not in quotes

# Wrong
title: My Post: A Guide

# Correct
title: "My Post: A Guide"

GitHub Pages Issues

Site Not Building

Symptoms:

Push completes but site doesn’t update
No build error in GitHub Actions

Solutions:

Check GitHub Pages settings:
- Go to Settings > Pages
- Verify source branch is correct
Check for build restrictions:
- Go to Settings > Actions > General
- Ensure Actions are allowed
View build logs:
- Go to Actions tab
- Click on the latest workflow run

404 on All Pages

Cause: Incorrect baseurl configuration

Solution:

# For username.github.io/repo-name
url: "https://username.github.io"
baseurl: "/repo-name"

# For custom domain
url: "https://example.com"
baseurl: ""

Assets Not Loading

Symptoms:

CSS/JS files return 404
Images not displaying

Solution: Use relative_url filter for all assets:

<link href="{{ '/assets/css/style.css' | relative_url }}" rel="stylesheet">
<img src="{{ '/assets/images/logo.png' | relative_url }}" alt="Logo">

Remote Theme Not Working

Error:

Build Error: could not read file

Solutions:

Check the remote theme syntax:
```
remote_theme: E-Segments/minima-plus
```
Add the remote theme plugin:
```
plugins:
  - jekyll-remote-theme
```
Verify the theme repository exists and is public

Search Not Working

Search Returns No Results

Causes:

Search index not generated
JavaScript error

Solutions:

Verify search.json exists:
- Visit yoursite.com/assets/search.json
- Check it contains your content
Check browser console for errors:
- Press F12 > Console tab
- Look for red error messages

Ensure search is enabled:

theme_config:
  features:
 search: true

Search Index Too Large

Symptom: Search loads slowly or fails

Solution: Limit content indexed in assets/search.json:

{% for post in site.posts limit: 100 %}
  <!-- Index only recent posts -->
{% endfor %}

Lunr.js Not Loading

Error:

ReferenceError: lunr is not defined

Solution: Check that Lunr.js CDN is accessible. If blocked, download and serve locally:

<script src="/minima-plus/assets/js/lunr.min.js"></script>

Dark Mode Issues

Dark Mode Not Toggling

Causes:

JavaScript error
localStorage blocked

Solutions:

Check browser console for errors
Clear localStorage:
```
localStorage.removeItem('theme');
```

Verify dark mode is enabled:

theme_config:
  features:
 dark_mode: true

Flash of Wrong Theme

Symptom: Page briefly shows light mode before switching to dark

Solution: Add this script to <head> before CSS:

<script>
  if (localStorage.theme === 'dark' || (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
    document.documentElement.classList.add('dark');
  }
</script>

Styles Not Changing

Cause: CSS not using Tailwind dark mode classes

Solution: Use dark: prefix for dark mode styles:

.my-element {
  background: white;
}

.dark .my-element {
  background: #1e293b;
}

Changelog Not Loading

GitHub API Rate Limit

Error:

API rate limit exceeded

Solutions:

Wait: Rate limit resets hourly

Cache locally: Download releases once:

curl -s https://api.github.com/repos/owner/repo/releases > _data/releases.json

Use GitHub token (for higher limits): Add to GitHub Actions workflow:
```
env:
  GITHUB_TOKEN: $
```

No Releases Showing

Causes:

Repository has no releases
github_repo not configured

Solution:

# _config.yml
github_repo: "username/repo"

Create releases on GitHub:

Go to your repository
Click “Releases” > “Create a new release”
Add version tag and release notes

Markdown Not Rendering

Symptom: Release notes show raw markdown

Solution: The theme uses marked.js to render markdown. Verify it’s loading:

<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>

Pagination Problems

Pagination Not Working

Causes:

Plugin not installed
Wrong front matter

Solutions:

Install the plugin:
```
gem "jekyll-paginate-v2"
```

Configure in _config.yml:

pagination:
  enabled: true
  per_page: 6

Add to page front matter:

---
layout: blog
pagination:
  enabled: true
---

All Posts on One Page

Cause: Using site.posts instead of paginator.posts

Solution:

{% for post in paginator.posts %}
  <!-- Post content -->
{% endfor %}

Wrong Post Count

Cause: Drafts included in count

Solution: Run without drafts:

bundle exec jekyll serve

To include drafts:

bundle exec jekyll serve --drafts

Component Issues

Component Not Rendering

Causes:

Wrong include path
Missing parameters

Solution: Check the include path matches exactly:

{% include components/card.html title="Test" %}

Not:

{% include card.html %}

Styles Missing

Cause: CSS not loaded or component outside prose

Solution: Wrap components properly:

<div class="not-prose">
  {% include components/card.html %}
</div>

JavaScript Not Running

Cause: Script loaded before DOM ready

Solution: Ensure scripts run after DOM loads:

document.addEventListener('DOMContentLoaded', function() {
  // Component initialization
});

Performance Issues

Slow Build Time

Solutions:

Exclude unnecessary files:

exclude:
  - node_modules/
  - vendor/
  - .git/
  - "*.md"

Use incremental builds:
```
bundle exec jekyll serve --incremental
```

Limit collection size:

collections:
  docs:
 output: true
 limit: 50  # In development

Large Page Size

Solutions:

Optimize images:
- Use WebP format
- Compress with tools like TinyPNG
- Use responsive images

Lazy load images:

<img src="image.jpg" loading="lazy" alt="Description">

Minimize CSS/JS:
```
sass:
  style: compressed
```

Getting More Help

If your issue isn’t covered here:

Search existing issues: GitHub Issues
Check Jekyll documentation: Jekyll Docs
Ask the community: Jekyll Talk Forum
Open a new issue: Include:
- Error message
- Jekyll version (jekyll -v)
- Ruby version (ruby -v)
- Relevant config/code

Quick Reference

Issue	Quick Fix
Build fails	`rm Gemfile.lock && bundle install`
404 errors	Check `baseurl` in `_config.yml`
Search broken	Verify `/assets/search.json` exists
Dark mode stuck	`localStorage.removeItem('theme')`
Changelog empty	Add `github_repo` to config
Pagination off	Add `jekyll-paginate-v2` plugin