Why isn't jekyll github pages serving my assets

You're here because:

  1. You wanted to use Github Pages to host your blog using Jekyll.
  2. You followed this documentation.
  3. Local build looks good, so you decide to push everything your remote repository.
  4. Awesome! Everything is smooth so far, so you go to your new website, expecting to see the exact same thing that you saw just a few minutes ago.
  5. But wait, something looks off... Why does your site looks so badly formatted?

What is happening here?

To answer this question, let's open the developer tools and navigate to the networks tab. If you're lucky, you will see 404 errors from the browser trying to serve your assets, e.g css files. Now hover your mouse over the failed network request and see where the request is coming from. Most likely, your site is trying to request assets from a nonexistent path.

Example

For example, let's assume you have your blog hosted on https://[username].github.io/blog, and you see that from your previous investigation, your site is trying to request my css from https://[username].github.io/assets/main.css. Obviously that's not the right place, so what should be the correct path? It should be from https://[username].github.io/blog/assets/main.css.

Problem

Now the question is how do you tell Jekyll to change where it's trying to serve my assets?

Solution

The easiest solution that I found was by adding/editing the baseurl in your Gemfile. Using the previous example, you would add baseurl: /blog to the Gemfile. Push your new changes to your remote repository, wait for github pages to rebuild, and your assets should now be served correctly.