GitHub provides free hosting of static web pages through its Pages service. In this tutorial, I will describe how I set up a free developer blog with GitHub Pages and a static web page generator called Jekyll. Jekyll is written in Ruby and has built-in support for GitHub Pages.
GitHub Pages is a great way to publish your dev blog since it’s free, and the provided github.io address can quite suitably refer to your GitHub profile. GitHub Pages publishes static web pages, and Jekyll makes producing them much more convenient than writing them in hand. Jekyll is also the recommended way to generate GitHub Pages.
In the following, I will first show how to install Jekyll and its dependencies. Then, I will show how to create a repository for the site, initialize the site with Jekyll, and configure GitHub to publish it. In the end, I will also show how to change the site’s theme and look at other ways to customize the site.
Installing Ruby, Jekyll, and Bundler
Jekyll requires at least Ruby version 2.5.0, RubyGem, GCC, and Make. GitHub also recommends installing Bundler to reduce Jekyll build errors and prevent environment-related bugs. Complete Jekyll installation instructions can be found here. Since GCC and Make are common development dependencies, I will not provide instructions on installing them in this context. I will, however, go through the installation of Ruby, RubyGem, Jekyll and Bundler on Ubuntu.
A complete Ruby installation (including RubyGem) can be done by installing the ruby-full package, so I will do that:
sudo apt install ruby-fullBecause RubyGems packages (gems) should not be installed as the root user, I will add a couple of lines to my ~/.bashrc that will set the Gem installation path environment variables when the console is started:
# Install RubyGem packages to ~/gems
export GEM_HOME="$HOME/gems"
export PATH="$HOME/gems/bin:$PATH"
After adding the lines, I apply the changes by sourcing the file:
source ~/.bashrc
This way, RubyGem will install packages to a user-specific location without the need for root privileges. Now I can use the gem command to install Jekyll and Bundler:
gem install jekyll bundler
Creating a repository for the blog
GitHub Pages are published from a GitHub repository. To create a new repository, I go to GitHub and select New repository from the menu, marked with a plus sign. Since I wish the blog’s address to refer to my GitHub user profile, I use my GitHub username to name the new repository. This way, the blog will be given the address <username>.github.io. At this point, I will create only an empty repository without README.md or any other files. First, I will initialize the repository locally and then push it to the repository created on GitHub.
After creating a repository in GitHub, I create a new local Git repository with the same name as I used in GitHub and switch to it:
git init <repository_name>
cd <repository_name>
I also change the name of the master branch to main:
git branch -m main
There are a few options for configuring publishing source for the GitHub Pages site. I chose to publish my blog from the docs/ directory in the main branch. That’s why I also create that directory and switch into it:
mkdir docs
cd docs
After that, I initialize the site with Jekyll.
Initializing the blog site with Jekyll
The site can be initialized in the directory from where the site will be published with this command:
jekyll new --skip-bundle .
It creates a new site in the directory but skips the bundle install command that installs the bundle’s dependencies. Next, I will edit the Gemfile file according to GitHub’s directions. Since this site is published using GitHub Pages, I comment out the line starting with gem "jekyll":
# ...
# This will help ensure the proper Jekyll version is running.
# Happy Jekylling!
#gem "jekyll", "~> 4.3.2"
# ...
And uncomment the line starting with gem "github-pages" and supplement it with a version number retrieved from here:
# ...
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
gem "github-pages", "~> 228", group: :jekyll_plugins
# ...
After saving these changes, I install the dependencies:
bundle install
Since the Webrick package is not included in the newer versions (> 3.0) of Ruby, we have to also install that:
bundle add webrick
Now, the site can be tested locally with the following command:
bundle exec jekyll serve
If the command succeeds (as it now should), the site can be reached at localhost:4000.
The initial push to GitHub, build process, and site URL
To test that the site also works in GitHub, I commit the changes, add the repository I created in GitHub as the origin of the local one, and push the changes to the remote repository:
git add .
git commit -m 'Initial GitHub Pages site with Jekyll'
git remote add origin git@github.com:USER/REPOSITORY.git
git push -u origin main
Remember to change USER/REPOSITORY with the correct user and repository name.
Pushing commits to GitHub will start a GitHub Actions pipeline that builds the site. You can follow the build process, for example, by clicking a small orange circle next to the commit name on top of the file listing on the Code tab. This will open a view to the jobs in the pipeline. You can read the output from them by clicking on their names.
After a successful build, the site should be available at its URL, which in case of user or organization site is http(s)://<username>.github.io or http(s)://<organization>.github.io, and in case of repository site is http(s)://<username>.github.io/<repository> or http(s)://<organization>.github.io/<repository>.
However, in this case, the site isn’t available at the URL even though the build was successful. That’s because I haven’t set the publishing source in the GitHub repository settings yet.
Setting the publishing source
The publishing source can be set as a branch only after the initial commit since an empty repository doesn’t have any. It can be done on the Settings tab by selecting Pages from the Code and Automation section on the left-hand sidebar. To publish the site from the docs/ directory in the main branch, you must set Deploy from a branch in the Source section on the main view and main and /docs as selectors in the Branch section.
The setting of the publishing source will trigger the pipeline again, and the site can be reached at its URL after the pipeline finishes.
Changing the theme and customizing the site
GitHub provides directions on how to change the site’s theme here. Some of them are supported directly, and these can be used by typing the name after the theme selector on the _config.yml file in the form as described on the README.md file of the theme:
# ...
# Build settings
theme: minima
# ...
It is also possible to use any other theme hosted on GitHub with a remote_theme selector:
# ...
# Build settings
#theme: minima
remote_theme: "mmistakes/jekyll-theme-basically-basic@1.4.5"
# ...
You can also customize the CSS and HTML of the theme. GitHub provides some general advice on this (here and here), but more specific information can be found in README files in the theme repositories. There are also many kinds of plugins you can use with Jekyll. Themes might also come with pre-built support for some of these and features such as site-wide search. Take a look at, for example, the README of the Basically Basic theme.