Troubleshooting 3 issues when configuring Jekyll on Github Pages

TL;DR: I encountered several problems when creating my static webiste using GitHub Pages with Jekyll. This blog records how I tackle them, just like the “common issues” section in manuals.

It takes me 6 hours to get this result

I am trying to build a course webpage for a new course for the coming spring semester. Since the website is just for listing out the lecture slides and Jupyter Notebook for the tutorial sessions, a static website should be more than enough.

I decided to use Jekyll as the backend of the website and follow the steps from these two manuals. My procedure is more about the same as the tutorials provided by GitHub Pages or other tutorials available in Medium, so I don’t want to repeat the words.

Yet, those tutorials are probably not flawless. Or, they are missing out some steps required. Following are the issues I’ve encountered when trying to host the webpage:

1. RubyGems environment fail to identify the correct EXECUTABLE DIRECTORY
2. Github Pages does not support my local version of Jekyll (3.8.5 vs 4.0.0)
3. Github Pages fails to identify the location of the css file

I will talk about what these issues are and how did I fix that.

Issue 1: Environment Issue

What’s the problem

When I was trying to use the bundle exec command. The command line threw an error to me like the following:

Could not locate Gemfile or .bundle/ directory

Solution

Create a new project before surving it

I have some issues when executing step 7 from the GitHub Pages manual since it threw a cryptic error when I try to execute bundle exec jekyll VERSION new .. Thus I skipped this step for the first time. This is probably a bad idea. The new command Gemfile will be automatically created inside a directory named myblog at your current location.

jekyll new PROJECT

Replace PROJECT with the project name you are going to use for your website. After that, go inside the directory and you should see a file called Gemfile . That means you are good to go running Jekyll.

Besides, be careful where your path is in your terminal before running jekyll serve . It needs to be EXACTLY in your /PROJECT directory since Jekyll will only check those Gemfile and yml inside the current directory. Error will occur if you’re running the command outside /PROJECT .

Hope you still remember the “Spark Joy” meme

Issue 2: GitHub Pages Dependency Issue

What’s the problem

GitHub Pages does not support the newest version of Jekyll. The version I installed into my laptop is 4.0.0 , while GitHub Pages only support 3.8.5 .

Editing Gemfile to the following still cannot fix the issue:

gem "github-pages", "~> 3.8.5", group: :jekyll_plugins

Solution

1. Check github-pages version (not Jekyll)

2. Declare Jekyll version in Gemfile

3. Recreate lock file

I thought the VERSION is the Jekyll version listed in the “dependency versions” page. NO. It is the version of the github-pages package. The version is actually 202 .

You need to specify these dependency versions in your Gemfile and Jekyll will work both locally and with GitHub Pages by the following steps. Alex Waibel on StackOverflow provided the following code for the most recent configuration (as of 2019–11–29).

First, edit the Gemfile as follows to meet the dependencies versions required by GitHub :

gem "jekyll", "~> 3.8.5"
gem "github-pages","~> 202" , group: :jekyll_plugins
# If you have any plugins, put them here!
group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.11.0"
end

After that, remove the old Gemfile.lock file:

rm Gemfile.lock

Finally, create the revised lock file.

bundle install

The new lock file should configure Jykell to run as version 3.8.5 rather than some newer versions.

Issue 3: GitHub Pages fails to load css

What’s the problem

I push the revised Gemfile to GitHub and open my webpage. The webpage link works, yet the css file does not appear in the server. What I got is some 90’s old-school webpage with some random Times New Roman words on the screen. Yuck.

I ran the webpage on my local computer and nothing goes wrong. There should have something wrong in the file directory then.

Solution

Edit .yml

I’m not the first one with this issue. Some people already asked how to deal with it in StackOverflow. You need to change the two parameters in _config.yml as follows:

baseurl: /PROJECT
url: http://USERNAME.github.io

Push the changes to GitHub again you should see the page rendered with your pretty css.

Ending Remarks

I may give Hugo a go when building static website time.