Anup D'Souza

Mobile Application Developer

6 minute read

If you have a GitHub account, you can create a static website using the GitHub Pages feature. In this post I will guide you on how to create a website for yourself that you can use to showcase your work or if you like blogging, you will be able to do that as well using jekyll themes. This tutorial is geared towards MacOS users but the steps will be similar for Windows/Linux users. We will be using the Chirpy theme for our website, although you can also use any theme you like. Check out jekyllthemes.io or jekyllthemes.org for more options.

Install Ruby on your system.

You can check if you have Ruby installed already by running the following command in the terminal.

Mac-mini:Blog anupdsouza$ ruby -v

In my case, since I’m using a mid 2012 Mac mini, I had an incompatible version of Ruby installed.

Mac-mini:Blog anupdsouza$ ruby -v
ruby 2.3.7p456 (2018-03-28 revision 63024) [universal.x86_64-darwin17]

Since Jekyll requires a minimum Ruby version of 2.5.0, lets install an appropriate version. If you dont have Ruby installed I recommend using a Ruby package manager such as rbenv. I’m using Homebrew to install rbenv

Mac-mini:Blog anupdsouza$ brew install rbenv ruby-build

Run the following command to list the available stable Ruby versions.

Mac-mini:Blog anupdsouza$ rbenv install -l
2.7.7
3.0.5
3.1.3
3.2.1
jruby-9.4.2.0
mruby-3.2.0
picoruby-3.0.0
truffleruby-22.3.1
truffleruby+graalvm-22.3.1

Only latest stable releases for each Ruby implementation are shown.
Use 'rbenv install --list-all / -L' to show all local versions.

Since I am working on a mid-2012 Mac Mini running High Sierra, I decided to go with a slightly older release of Ruby v2.6.0. You should be able to install the latest stable release of Ruby without any issues.

Mac-mini:Blog anupdsouza$ rbenv install 2.6.0

Once installed, you can activate that version of Ruby as the default Ruby version on your machine.

Mac-mini:Blog anupdsouza$ rbenv global 2.6.0
Mac-mini:Blog anupdsouza$ rbenv version
2.6.0 (set by /Users/anupdsouza/.rbenv/version)

Kill terminal & restart. Check the installed Ruby version & you should see the version of Ruby you installed.

Mac-mini:Blog anupdsouza$ ruby -v

If you see any other(older) version of ruby, check your ~/.bash_profile file that it contains the following, if not then add the following to your ~/.bash_profile.

export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

Kill terminal & restart & check ruby version again to verify.

Setting up Chirpy

Next, head to the Chirpy GitHub repository & select the Use this template > Create a new repository option. image On the next page for the repository name, enter it in exactly the following format:

[your github username].github.io

Make sure repository visibility is Public, then select Create repository from template. Once your repository has been created, head over to Settings > [Code and automation] Pages > [Build and deployment] Source > select GitHub Actions image Clone the repository to your system & cd to the folder you cloned it to in terminal & enter the following commands to install dependencies:

Mac-mini:anupdsouza.github.io anupdsouza$ gem install bundler
Mac-mini:anupdsouza.github.io anupdsouza$ bundle

Open the cloned folder in your IDE of chouce & open the _config.yml file. This file contains all the site configuration for your jekyll website. Customise the following fields to get started:

# The language of the webpage › http://www.lingoes.net/en/translator/langcode.htm
# If it has the same name as one of the files in folder `_data/locales`, the layout language will also be changed,
# otherwise, the layout language will use the default value of 'en'.
lang: en

# Change to your timezone › http://www.timezoneconverter.com/cgi-bin/findzone/findzone
timezone: Example: Asia/Kolkata

# the avatar on sidebar, support local or CORS resources
avatar: # your image url

title: # the main title

tagline: # it will display as the sub-title

description: >- # used by seo meta and the atom feed

url: # "https://[your github username].github.io"

github:
 username: # change to your github username

social:
  # Change to your full name.
  # It will be displayed as the default author of the posts and the copyright owner in the Footer
  name: # your name
  email: # change to your email address

You can update any other fields if you like as well once you are comfortable with the structure. You can leave the baseurl field blank as this will be a static website. You are now ready to check your website locally, do that by running the following command:

Mac-mini:anupdsouza.github.io anupdsouza$ bundle exec jekyll s

If everything went fine, you will see the server address for your local website at http://127.0.0.1:4000/. Open the url in the browser & you should see your website with the details you entered in the _config.yml file. You will also notice a _site folder created by jekyll in the project structure which is basically the output of all the settings and content prepared for the Web. image There is nothing to show on the Home page yet, we will get to that in the next section.

Updating pages & creating posts

Expand the _tabs folder & open the about.md file. As you will have noticed, this is a markdown file which requires that you enter content in markdown format. Copy paste the following for the time being & update your name in the placeholder to get started:

---
# the default layout is 'page'
icon: fas fa-info-circle
order: 4
---

# Hello, my name is [your name]
Welcome to my website. This is my home on the internet, hope you have a pleasant stay!

Refresh the page in the browser & select the About section to see the new content we just entered. image Feel free to update this page with more of your details, portfolio & accomplishments. Creating posts with jekyll is similar to creating pages. Posts are markdown files as well with a pre-defined filename in the format YYYY-MM-DD-[post title]. Expand the _posts folder & create a new file with the following file name:

2023-03-23-hello-world.md

Open this file & paste the following content:

---
layout: post
title: "Hello World!"
---

A "Hello, World!" program is generally a computer program that ignores any input and outputs or displays a message similar to "Hello, World!"

![HelloWorldImage](https://www.udacity.com/blog/wp-content/uploads/2020/11/Hello-World_Blog-scaled.jpeg)
[Read more on Wikipedia](https://en.wikipedia.org/wiki/%22Hello,_World!%22_program)

Refresh your website in the browser & you should now see a brand new post on your homepage! image Click on the post to see it in full. image You have now created a blog post. To create a new post, follow the same steps above & add different content to it.

Deploying your website online

Commit your changes to your online GitHub repository. Since we selected GitHub Actions as the source for build & deployment & are using the Chirpy theme which has a deployment workflow configured (see .github/workflows folder), GitHub will automatically publish your website on every push to your GitHub repository. You can go to the Actions tab of your repository to check the status of the deployment. image In a new browser tab, enter https://[your github username].github.io/ to view your website online. Congratulations! You have successfully created a website for yourself using GitHub & Jekyll.

Tips

If you want to create a blog post but dont want to publish it online yet, you can create a folder at the root level with the name _drafts & add your temporary post in .md file format to it. Once you decide that you want to publish it, simply move the file from the _drafts folder to the _posts folder.

Issues & solutions

  • GitHub Actions build & deployment can fail if you created your repository with visibility set to Private in GitHub. In this case you will need to go to go to Settings > General > Danger zone > Change Repository visibility > Change to Public.
  • If after you have pushed your changes & deployed your website online, if you only see the following in the browser: --- layout: home # Index page ---

Run the following commands

bundle lock --add-platform x86_64-linux
bundle install

Push a commit & GitHub Actions should now succeed & your website should render correctly.

If you want to check out the code behind this website, you can do so here. And that’s it for this post! In the next post, we will see how to host our website using a custom doman, stay tuned.

References:

Leave a comment

You may also enjoy