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.



  • 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 For example, if your username is octocat, repository should be named

Clone your repo locally

$ git clone
$ cd

Setting up local environment

  1. 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:

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
$ 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 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.

  1. Create in your project file .github/workflows/github-pages.yml
  2. Copy the following contents into that file
name: Build and deploy Jekyll site to GitHub Pages

      - master

    runs-on: ubuntu-latest
      - uses: actions/checkout@v2
      - uses: helaili/jekyll-action@v2
          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

  1. Go to Personal access tokens on GitHub.
  2. Generate a new token:
    • give it public_repo permissions
    • setup expiration date
    • save the generated value locally
  3. Go to your repository’s settings on GitHub and then to the Secrets tab.
  4. 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, 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, do the following:

  1. Register a domain you like
  2. Follow official GitHub instructions
  3. 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 ¯\_(ツ)_/¯)


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