How to fix missing CSS files in Jekyll


In this video, we go over another issue you might run into with Jekyll themes. It’s a continuation of the previous video where I explained the importance of specifying versions in your Gemfile.


Previously on Jekyll Land, we failed to install a working version of the moving theme. So now, let’s see if we can get the theme working by specifying the latest version in the Gemfile. Let’s save the Gemfile, and run bundle install.

Aha, now Bundler is giving us a helpful error. If you recall, in the previous episode, Bundler was very sneaky and installed an older version without telling us. You could argue that since it knows which version it will install, it should warn us when it’s going to install an older version. I agree. I think that would be a much better user experience.

In any case, let’s take a look at this error now. It’s saying it can’t find compatible versions for the Jekyll gem. Our Gemfile wants at least version 4.2 of Jekyll but the moving theme wants versions of Jekyll less than 4.1.

So what are our options? Well, we have several, and I go through them all in detail in my upcoming course for Jekyll beginners. If you’re already part of my list, stay tuned for more details. If not, subscribe with the link below this video.

For now, we want to try out the theme so we can see another issue you might run into with Jekyll themes. Because the moving theme does not allow Jekyll versions higher than 4.0, the only way we can install this theme as a gem is to downgrade Jekyll in our project.

We’ll do that by changing the Jekyll version in the Gemfile to 4.0.0, and then we’ll need to run bundle update instead of bundle install.

Looking at the output, we can see that it installed moving 0.3.4, which is what we want. We can also double check in our Gemfile.lock.

So now let’s see if our site works. We’ll run our js alias to start the server. We can double check by visiting our site and seeing that it still looks unstyled, and we can see in the developer tools that there are 2 missing CSS files.

As we did before, let’s open the gem folder and see where the CSS files are referenced. It’s in the same file as before, but this time, the CSS files are included in the gem.

So, if the files are there, why can’t the browser find them?

Let’s take a closer look at the code that points to the CSS file. It points to the file in the assets/css folder, but it has this site.url inside the double curly brackets. Those double braces are part of a templating language called Liquid.

It’s telling Jekyll to enter the value of site.url before the assets folder. This value comes from the url attribute in the config file. Let’s see what our config file looks like. OK, so we can see that our url is blank, which explains why the browser is looking for the file at localhost:4000/assets/css/.

But our Jekyll site lives in a separate path, as defined by the baseurl attribute. The problem is that the moving theme is assuming our Jekyll site lives at the root of our website, which is not a great assumption to make because it’s very common to have a Jekyll site, such as a blog, live in a subpath of a site.

So how can we fix this? First, let’s test the theory that it’s an url versus baseurl issue by changing the variable from site.url to site.baseurl. Note that I’m making this change directly in the moving gem’s source code.

This is purely for testing purposes and because it’s the fastest way to show you. Please don’t try this at home! I explain why in more detail in my upcoming course.

For this change to take effect, we have to stop and restart the server. Let’s refresh the browser. Nice! It looks much better now, but the agate.css file is still missing.

What does it do? Do we care if it’s missing? So far, the styling seems right. Let’s take a look at the example Jekyll post.

Ah! The code snippet is missing syntax higlighting. Let’s take a look at the agate.css file to see if that’s what it does. Yeah, all of these CSS attributes start with .hljs which comes from the HighlightJS tool, and we can see that it’s being loaded in the head.html file.

OK, so let’s make the same fix for agate.css by changing site.url to site.baseurl. Then stop and start the server. And refresh. Et voilĂ ! We’ve got syntax highlighting. Super! And no more browser errors.

OK, so now that we’ve identified the issue, how can we make this more flexible so that it can work whether or not we use a baseurl? Well, Jekyll provides a Liquid filter called relative_url which will add the baseurl if it exists. Let’s try it out.

Nice. Now let’s try removing the baseurl so that our site lives at the root. And we’ll need to stop and start the server again. And refresh. Still works. Awesome!

Now that we fixed the theme for ourselves, it would be nice to fix it for everyone else. In my upcoming course, I show you step by step how to contribute this fix to the moving GitHub repo. After learning this specific workflow, you’ll be able to contribute to any open source repo.

Alright. That’s it for today. Thanks for watching. See you in the next one!