When I wanted to start my blog up again, I knew I wanted to use Jekyll. However, it had been a long time since I had set up a Jekyll site from scratch, and I ran into some roadblocks that were mostly caused by my outdated knowledge of Jekyll and GitHub Pages. Here’s the process I used to get this site up and running in January 2021 using Windows 10 1909 and WSL 2 running Ubuntu 20.04 LTS. These instructions are adapted from Colin Westwater’s tutorial.
Checking GitHub’s Compatibility
The first thing to do is to check the GitHub Pages Dependencies. The instructions on this page use Jekyll 3.9.0 because that’s the latest version that is compatible with GitHub Pages as of this writing. There are other version dependencies for different gems, but I did not run into any issues with the default jekyll install. If you start adding more gems, you’ll need to refer back to that page to determine the latest version you can install.
Installing Ruby and Jekyll
Open up a WSL 2 shell for Ubuntu 20.04 LTS and run the following to install Ruby and a couple of other dependencies:
sudo apt update && sudo apt upgrade -y sudo apt install -y ruby-full build-essential zlib1g-dev
Now we will set up environment variables so that Ruby installs gems to our home directory. WSL has some permissions restrictions for gem installs, so this is essential:
echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc source ~/.bashrc
jekyll. Again, I’m using 3.9.0 here, but you should replace that with whatever the latest version GitHub Pages supports.
gem install bundler gem install jekyll --version 3.9.0
Initializing the Website
Make a directory for your website, go into that directory, and run
git init jekyll 3.9.0 new .
This will inialize the Git repository and create all the folder structure and set up a site with the default “Minima” theme. Open up the
Gemfile that was created, and change the commented-out line containing
github-pages to look like this:
gem "github-pages", "~> 209", group: :jekyll_plugins
209 as the version number here because that’s what the Dependency Versions page tells me to use. It’s important to lock this version number in so that you are always using the version of
github-pages that matches with the version of
jekyll you’re using.
Gemfile mentions, comment out the
gem "jekyll" line and update the versions of all the gems in this file to match those found in the Dependency Versions page. Then, run this to pull all the correct gem versions:
You can preview the site by running
bundle exec jekyll serve
git add and
git commit to commit your site to the
main branch. If the default branch is
master, go ahead and commit to that branch, then rename it to `main by running:
git branch -m main
For more information, check out the GitHub Documentation.
Modifying the Minima CSS
This is a little beyond the scope of this post, but I wanted to note this here for future reference. If you’re using the Minima theme, and you want to customize the CSS, you’ll need to create
assets/main.scss and put this at the top of the file:
--- --- @import "minima";
This applies to any gem-based Jekyll theme. You need to place your own
.scss file in the same location as the base theme. If you load up your website in your browser, use the inspector to find out where the CSS is being loaded from. The documentation for your theme may also tell you the proper procedure.
Publishing the Site
Create a new GitHub repository called
soandso is replaced with whatever you like. Then, follow the instructions in GitHub to push your code to that repository. For me, I didn’t have to do any additional configuration, and my site was immediately available at the URL matching the repository name.