How to create a blog with Jekyll 4 and host it for free on GitHub

Today I want to note down how I created this very blog using GitHub Pages and Jekyll 4 – a static site generator.

Why? Because GitHub uses Jekyll 3.9.0, whereas the current version of Jekyll is 4.2.1, see all Jekyll releases.

To do this I had to go through various sources and here is the complete guide.

Prerequisites
Setting up GitHub repository
Setting up local environment
Setting up deployment using GitHub Actions
(Optional) Setting up custom domain
Example

Prerequisites

GitHub account
Installed Git locally
Basic knowledge of HTML and CSS – later for styling your blog
(Optional) Money for the custom domain

Setting up GitHub repository

First, create a public GitHub repository. The name of the repository should be username.github.io. For example, if your username is octocat, repository should be named octocat.github.io.

Clone your repo locally

$ git clone git@github.com:username/username.github.io.git
$ cd username.github.io

Setting up local environment

Install Ruby. MacOS has Ruby installed by default but let’s get a new one with Homebrew.

$ brew install ruby

Find out where brew ruby and gems are

$ brew info ruby

Here’s what I have here:

...
By default, binaries installed by gem will be placed into:
  /usr/local/lib/ruby/gems/3.0.0/bin

You may want to add this to your PATH.

...


If you need to have ruby first in your PATH, run:
  echo 'export PATH="/usr/local/opt/ruby/bin:$PATH"' >> /Users/myusername/.bash_profile
...

Add both of them to your PATH

echo 'export PATH="/usr/local/opt/ruby/bin:/usr/local/lib/ruby/gems/3.0.0/bin:$PATH"' >> ~/.bash_profile

Relaunch terminal and verify you use the brew ruby now

$ which ruby
/usr/local/opt/ruby/bin/ruby
$ ruby -v
ruby 3.0.3p157 (2021-11-24 revision 3fb7d2cadc) [x86_64-darwin20]

Now install jekyll and bundler

$ gem install --user-install bundler jekyll

Add .gem to your PATH

echo 'export PATH="$HOME/.gem/ruby/3.0.0/bin:$PATH"' >> ~/.bash_profile

Initiate a new Jekyll site (--force option is here in case you already have some files in your directory that you don’t need and wish to overwrite)

$ jekyll new . --force

Build and run the site locally

$ bundle exec jekyll serve

Open http://127.0.0.1:4000 in your browser – you should see the website there.

Setting up deployment using GitHub Actions

Jekyll has almost working instructions on how to do that.

Here’s what to do to make it work correctly.

Create in your project file .github/workflows/github-pages.yml
Copy the following contents into that file

name: Build and deploy Jekyll site to GitHub Pages

on:
  push:
    branches:
      - master


jobs:
  github-pages:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: helaili/jekyll-action@v2
        with:
          target_branch: 'gh-pages'
          token: ${{ secrets.ACTIONS }}

NOTE: target_branch is missing from Jekyll docs and token name can’t start with GITHUB, so I choose the name ACTIONS.

Setup the token in GitHub

Go to Personal access tokens on GitHub.
Generate a new token:
- give it public_repo permissions
- setup expiration date
- save the generated value locally
Go to your repository’s settings on GitHub and then to the Secrets tab.
Create a token with the name ACTIONS (name should be the same as in the yaml file) and provide it the saved value from the generated token.

Add all generated files and commit them to GitHub

Check what is tracked by git

$ git status

If there’s anything you don’t want to add to GitHub, add those files to .gitignore.

Add, commit and push your files

$ git add --all
$ git commit -m "Initial commit"
$ git push -u origin master

Verify your changes

Go to the Actions tab of the repository and see that the workflow is completed successfully.

Once it is completed, navigate to https://username.github.io, where username is your GitHub username. Success, the blog is ready and is published for everyone to see!

(Optional) Setting up custom domain

If you want your blog to run at some address other than username.github.io, do the following:

Register a domain you like
Follow official GitHub instructions
Add CNAME file to the root of your project and add there your domain (according to the documentation, it should be created automatically, but it did not happen ¯\_(ツ)_/¯)

Example

If you need a specific example, you can visit the source code of this blog.

Contents