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.
Contents
- 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
- give it
- 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.