Home Blog Tutorial 1 - Setup Jekyll
Post
Cancel

Blog Tutorial 1 - Setup Jekyll

Posted Dec 27, 2022
By Pemd-sys
8 min read

Introduction

In this multi-part tutorial I will be walking you through setting up your own blog using github pages and the Jekyll static website generator. There are a few important concepts that I will show you which hopefully will give you a good start to continue your journey into blogging. This is in no means a comprehensive tutorial on either of the tools but rather a concise presentation of work and will focus on a few customisations which I found rather useful. Where-ever needed I will provide links to in other tutorials/blogs/wikis.

Git-Hub Pages

Github as you maybe familiar with is a website that lets you post your code so you can keep it organized and share it with other people for software development and version control using Git. Version control allows developers to keep track of their changes, (ie version) in a way that allows developers to make changes to code without fearing that their changes might break their entire code-base. When it does developers can roll back their changes and rework the issue till it is resolved. It allows multiple people to work on different parts of the code allowing for a truely collaborative code creation and maintainance.

Now along with source control GitHub Pages lets you take a GitHub repository and turn it into a webpage. In other words, you can use a GitHub repository to host your HTML, CSS, and JavaScript files. If you register for free in github you can host you own website using the same username, i.e., your website will be hosted at <USERNAME>.github.io. For example, my username is pemd-sys so my website is pemd-sys.github.io.

Setup Github account

So, the first thing to do is to create a github account. You can create a free account by registering though this link. Click on the free account page and then choose a name you like provide your email address and go though a standard verification process. For the purpose of this blog we shall assume that your username chosen is USERNAME.

Once that is done follow the steps in this link to create a blank github page.

Overall structure

Before we go any further we first need to discuss the structure of the repositories we are going to follow. This is similar to how I have setup and its fairly complicated to given an overview first.

One of the requirements I had was that I wanted to keep markdown texts private, ie the post*.md files stay safe and hidden in a private repository and only the final generated website is uploaded to the github page account. So, the plan was to keep my source repository private which github allows even for free users and only have the generated static site pages to be uploaded into the public <USERNAME>.github.io repository. This would create a nice opportunity for me to play with the github CI/CD tools as well since I would use the CI/CD tool to upload a new copy of the static web-pages to the public repository every time I did a git push on my source ‘private’ repository.

So with that in mind the first thing to do is to go to the github site and create a private repository. My private repository for this tutorial is going to be ‘pemd-sys/ test-privaterepo’. Create it blank without readme.md.

Jekyll

There are many static site generators that are available. A few popular ones are below:

I prefer Jekyll since reading on it website it looked easy and I liked their templates, so that’s what I chose, but my choice does not mean that Jekyll is the best for you. Feel free to look around and see what works best for you. For now I will discuss how to setup Jekyll for github page.

Installing Jekyll

The install page for jekyll has the instructions needed to install jekyll on your computer. The summary of the install steps for ubuntu 22.04 is given below.

1
2
3
4
5
6
7
8

sudo apt-get install ruby-full build-essential zlib1g-dev
echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
gem install jekyll bundler

Installing Jekyll Theme

I found chirpy very good in terms of its blog structure and it is quite simple to use. So I went with that. The easiest method to go about using the theme for your own use is to just create a copy of the chirpy theme and use it as a starting point for your own repository. The steps are as follows

1
2
3
4
5
6
7

git clone --bare --single-branch --no-tags --branch master git@github.com:cotes2020/jekyll-theme-chirpy.git
cd jekyll-theme-chirpy.git/
git push --mirror git@github.com:pemd-sys/test-privaterepo.git
cd ..
rm -rf jekyll-theme-chirpy.git/
git clone git@github.com:pemd-sys/test-privaterepo.git

To explain briefly what I am doing is basically in the first step I clone the master branch of the chirpy theme, second I push the checked out theme into my own repository ‘test-privaterepo’ which was created blank in github. Finally I delete the original chirpy folder and clone my private repository to my local disk. To read more about the details of cloning and copying a repo for you own use there are some excellent resources. [1 2 3 4 5 6, 7, 8].

I have realised it a bit late, but this method above fixes the version to whatever the master is currently at. That is not good for future, so in a future post I will show how to do it such that changes to the chirpy repository can be pulled into our own.

Once the repository has been cloned we need to run the following steps to install the requirements of the theme.

1
2

cd test-privaterepo
bundle install

This should finish without errors.

Initial configuration

The original jekyll repository has some default values that needs to be changed to customise it for yourself. 7. Within the Jekyll configuration file (_config.yml), we will need to change the following settings:

  • name - This is the “title” of your website. (for example, “pemd-sys”).
  • description - This is a short tagline describing the contents of your website or blog or yourself.
  • avatar - I have put my head shot. I created a sub-folder in the /assets/img directory called avatar and placed my image avatar.jpeg in it. The relative link has to be provided properly for jekyll to find it.
  • baseurl - This is the name of your GitHub repository prepended by a backslash (/). This ensures GitHub Pages publishes your website using the correct subdirectory.

An example of these edited settings is below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# Change to your timezone › http://www.timezoneconverter.com/cgi-bin/findzone/findzone
timezone: Europe/London

title: pemd-sys                          # the main title

tagline: Wonder, Think, Invent, Engineer   # it will display as the sub-title

description: >-                        # used by seo meta and the atom feed
  A Technical Blog by pemd-sys.

# the avatar on sidebar, support local or CORS resources
avatar: /assets/img/avatar/avatar.jpeg

github:
  username: pemd-sys             # change to your github username

twitter:
  username: twitter_username            # change to your twitter 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: pemd-sys
  email: me@gmail.com            # change to your email address
  links:
    # The first element serves as the copyright owner's link
    - https://twitter.com/username      # change to your twitter homepage
    - https://github.com/pemd-sys      # change to your github homepage
    # Uncomment below to add more social links
    # - https://www.facebook.com/username
    # - https://www.linkedin.com/in/username

Run Jekyll

To run the website locally to check everything is working as expected run the following command in the same repository directory

1

bundle exec jekyll serve

This should then generate a few lines in the terminal with the last two lines being something like this

1
2

  Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

If you click on the server address it should open in your web-browser and you should see the chirpy frontpage. Check your avatar should have changed to the image you provided.

Write a new Post

Writing a new post is basically creating a new markdown file in the _posts folder and following the naming convention and markdown tags. The chirpy ‘Writing a New Post’ is an excellent guide to follow. Once you are happy with the changes push your changes to github using the following in the repository folder.

1
2
3

git add .
git commit -m "First commit"
git push

Conclusion

If everything went well, congratulations you have setup jekyll. In the next post I will show how to setup customisation for the posts to display maths and text justification.

References

  1. https://gist.github.com/pemd-sys/db8dc36f6ce089f1c98c4b990fcc4a16 ↩

  2. https://www.freecodecamp.org/news/git-clone-branch-how-to-clone-a-specific-branch/ ↩

  3. https://stackoverflow.com/questions/14040754/deleting-remote-master-branch-refused-due-to-being-the-current-branch ↩

  4. https://stackoverflow.com/questions/38027834/git-mirror-a-repo-to-specific-branch ↩

  5. https://stackoverflow.com/questions/24917489/cloning-a-repo-without-tags ↩

  6. https://www.earthdatascience.org/workshops/intro-version-control-git/basic-git-commands/ ↩

  7. https://chrisjhart.com/Creating-a-Simple-Free-Blog/ ↩ ↩2

  8. https://phi-jkim.github.io/posts/Creating-Jekyll-Website/ ↩

Jekyll, Jekyll-Tutorial
Installation
This post is licensed under CC BY 4.0 by the author.
Contents

Why Write a Technical Blog

Blog Tutorial 2 - Customise Chirpy Theme