Create a free static website using Github Pages and Jekyll
Tags: githubpages, jekyll, tutorial, github
Published: 2023-03-03 17:39:15

## TOC
  * [Why use GitHub Pages and Jekyll](#why)
  * [Prerequisites](#prereq)
  - [1: Dev Machine Setup](#setupdev)
  * [2: Use Chirpy Starter Template](#chirpystarter)
  * [3: Install dependencies](#installdepen)
  * [4: Modify config yaml and preview changes](#modifyconfig)
  * [5: Using GitHub Actions](#ghactions)
  * [6: Commit Changes to Repo](#committorepo)
  * [7: View the website](#finalwebsite)
  * [8: Personalize by Adding Avatar, favicon, sidebar link and create first post](#personalize)

## Why use GitHub Pages and Jekyll ? <a name="why"></a>

[GitHub Pages](https://pages.github.com/) allows us to host a static website(html, CSS, JavaScript) on GitHub repository for absolutely free which is ideal for personal websites. 

> _A repository with the naming convention of **{github-user-name}.github.io** makes that repository serve a static website with subdomain as {github-user-name} and domain name as github.io_ 

[Jekyll](https://jekyllrb.com/) (static site generator tool) is integrated with GitHub pages providing professional looking themes and many free templates for your website.
> When using Jekyll we do not have to code any HTML, CSS or JavaScript. Instead we only edit the markdown files to achieve the desired results in the templates.

## Prerequisites <a name="prereq"></a>
- Windows/Linux developer machine
- GitHub Account

##1: setup Ruby, Gem and Jekyll on developer machine <a name="setupdev"></a>

- If dev machine is windows, use Windows subsystem for Linux - which installs a ubuntu environment which is available from PowerShell terminal.
  * Open a PowerShell prompt as an Administrator and run:
    `wsl --install`
- Install Ruby and other prerequisites:
```
yash@LearningPC:~/github$ sudo apt-get install ruby-full build-essential zlib1g-dev
[sudo] password for yash:
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
build-essential is already the newest version (12.9ubuntu3).
zlib1g-dev is already the newest version (1:1.2.11.dfsg-2ubuntu9.2).
The following additional packages will be installed:
  ri
The following NEW packages will be installed:
  ri ruby-full
0 upgraded, 2 newly installed, 0 to remove and 4 not upgraded.
Need to get 6788 B of archives.
After this operation, 38.9 kB of additional disk space will be used.
Do you want to continue? [Y/n] Y
Get:1 http://archive.ubuntu.com/ubuntu jammy/universe amd64 ri all 1:3.0~exp1 [4206 B]
Get:2 http://archive.ubuntu.com/ubuntu jammy/universe amd64 ruby-full all 1:3.0~exp1 [2582 B]
Fetched 6788 B in 1s (4970 B/s)
Selecting previously unselected package ri.
(Reading database ... 47201 files and directories currently installed.)
Preparing to unpack .../ri_1%3a3.0~exp1_all.deb ...
Unpacking ri (1:3.0~exp1) ...
Selecting previously unselected package ruby-full.
Preparing to unpack .../ruby-full_1%3a3.0~exp1_all.deb ...
Unpacking ruby-full (1:3.0~exp1) ...
Setting up ri (1:3.0~exp1) ...
Setting up ruby-full (1:3.0~exp1) ...
```
- Add environment variables to your ~/.bashrc file
```
echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
- Install Jekyll and Bundler

```
yash@LearningPC:~/github$ gem install jekyll bundler
Fetching jekyll-4.3.2.gem
Successfully installed jekyll-4.3.2
Parsing documentation for jekyll-4.3.2
Installing ri documentation for jekyll-4.3.2
Done installing documentation for jekyll after 3 seconds
Fetching bundler-2.4.7.gem
Successfully installed bundler-2.4.7
Parsing documentation for bundler-2.4.7
Installing ri documentation for bundler-2.4.7
Done installing documentation for bundler after 0 seconds
2 gems installed
```
##2: Use chirpy-starter template to create new repo <a name="chirpystarter"></a>
- Sign in to GitHub.com with your account, and go to [chirpy-starter](https://github.com/cotes2020/chirpy-starter/), click the button Use this template > Create a new repository

![Use Chirpy Starter Template](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/fujl101qotj754h2761v.png)
- In the next window type the repository name to be the same as your GitHub user name appended with .github.io
`
<GitHub User Name>.githubpages.io
`
![Create New repository(with same name as GH user) from Template](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ql6tf9k43ov5ri57mz97.png)
This makes the repo. act as a source of static website, and the repo. name becomes the domain name website.
- Once this operation is complete all the contents of [chirpy-starter](https://github.com/cotes2020/chirpy-starter/) will be present in our new site: https://github.com/yash-nigam/yash-nigam.github.io

##3: Installing dependencies of chirpy-starter <a name="installdepen"></a>
- This site requires some GEM's to be installed before it can be used, the list of can be found in the Gemfile: https://github.com/cotes2020/chirpy-starter/blob/main/Gemfile
- On your local development machine, clone the new repo
`git clone https://github.com/yash-nigam/yash-nigam.github.io.git
`
- go to the repo root directory and run bundle command

`cd yash-nigam.github.io
`

```
yash@LearningPC:~/github/yash-nigam.github.io$ bundle
Fetching gem metadata from https://rubygems.org/...........
Resolving dependencies...
Using bundler 2.4.7
Using concurrent-ruby 1.2.2
Using rainbow 3.1.1
Using ffi 1.15.5
Using forwardable-extended 2.6.0
Using mercenary 0.4.0
Using parallel 1.22.1
Using rouge 4.1.0
Using eventmachine 1.2.7
Using unicode-display_width 2.4.2
Using racc 1.6.2
Using colorator 1.1.0
Using i18n 1.12.0
Using ethon 0.16.0
Using yell 2.2.2
Using pathutil 0.16.2
Using liquid 4.0.4
Using public_suffix 5.0.1
Using typhoeus 1.4.0
Using addressable 2.8.1
Using webrick 1.8.1
Using jekyll-paginate 1.1.0
Using http_parser.rb 0.8.0
Using rb-inotify 0.10.1
Using rb-fsevent 0.11.2
Using rexml 3.2.5
Using terminal-table 3.0.2
Using nokogiri 1.14.2 (x86_64-linux)
Using safe_yaml 1.0.5
Using google-protobuf 3.22.0 (x86_64-linux)
Using em-websocket 0.5.3
Using listen 3.8.0
Using sass-embedded 1.58.3 (x86_64-linux-gnu)
Using html-proofer 3.19.4
Using kramdown 2.4.0
Using jekyll-watch 2.2.1
Using jekyll-sass-converter 3.0.0
Using kramdown-parser-gfm 1.1.0
Using jekyll 4.3.2
Using jekyll-archives 2.2.1
Using jekyll-seo-tag 2.8.0
Using jekyll-redirect-from 0.16.0
Using jekyll-sitemap 1.4.0
Fetching jekyll-theme-chirpy 5.5.2
Installing jekyll-theme-chirpy 5.5.2
Bundle complete! 6 Gemfile dependencies, 44 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
1 installed gem you directly depend on is looking for funding.
  Run `bundle fund` for details
```
##4: Modify _config.yml and Preview the changes locally <a name="modifyconfig"></a>
- Open _config.yml and modify the title and url

```
title: Yash Nigam

url: 'https://yash-nigam.github.io'
```
- Preview the site contents locally:

```
yash@LearningPC:~/github/yash-nigam.github.io$ bundle exec jekyll s
Configuration file: /home/yash/github/yash-nigam.github.io/_config.yml
            Source: /home/yash/github/yash-nigam.github.io
       Destination: /home/yash/github/yash-nigam.github.io/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
                    done in 1.634 seconds.
 Auto-regeneration: enabled for '/home/yash/github/yash-nigam.github.io'
    Server address: http://127.0.0.1:4000/

```
- The local service will be published at http://127.0.0.1:4000.

![Local Preview](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/82ip5bw1u9dtuwftt9sd.png)

##5: Configure to Deploy the Website using GitHub Actions <a name="ghactions"></a>
- Browse to your repository on GitHub, Select Settings > Pages. Then in the Source section (under Build and deployment), select GitHub Actions from the dropdown menu.

![Select GitHub Actions](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1kpz6iqtvjf8bdvdewgv.png)

##6: Commit and push changes to repo<a name="committorepo"></a>
- Check git status 

```
yash@LearningPC:~/github/yash-nigam.github.io$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   _config.yml

no changes added to commit (use "git add" and/or "git commit -a")
```
- add, Commit and push the _config.yaml file to repo

```
yash@LearningPC:~/github/yash-nigam.github.io$ git add _config.yml
yash@LearningPC:~/github/yash-nigam.github.io$ git commit -m "updated"
[main c30df68] updated
 1 file changed, 2 insertions(+), 2 deletions(-)
yash@LearningPC:~/github/yash-nigam.github.io$ git push
Username for 'https://github.com': yash-nigam
Password for 'https://yash-nigam@github.com':
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 12 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 334 bytes | 334.00 KiB/s, done.
Total 3 (delta 2), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (2/2), completed with 2 local objects.
To https://github.com/yash-nigam/yash-nigam.github.io.git
   aae12d1..c30df68  main -> main
```
##7: Check the Actions Workflow and view the final website <a name="finalwebsite"></a>
- Once the changes are pushed to the repo, a build and deploy workflow should be automatically triggered.

![Build and Deploy Workflow](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/dv6tgd2lo23sia372ppc.png)
- View the final website
![Final Website](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/913hc7e0538rpk7izevi.png)

##8: Add Avatar, favicon, a new post and an sidebar tab.<a name="personalize"></a>
### Add Avatar and favicon images

1. Create a directory named img under assets in the root of repo
`yash-nigam.github.io/assets` and favicons under img.
2. Follow the steps to generate and add 
favicons[https://chirpy.cotes.page/posts/customize-the-favicon/](https://chirpy.cotes.page/posts/customize-the-favicon/)

```
yash@LearningPC:~/github/yash-nigam.github.io/assets$ ls -ltr img/
total 96
drwxr-xr-x 2 yash yash  4096 Mar  3 23:28 favicons
-rw-r--r-- 1 yash yash    90 Mar  4  2023 favicon.ico:Zone.Identifier
-rw-r--r-- 1 yash yash 27019 Mar  4  2023 yn_small.jpg
-rw-r--r-- 1 yash yash 53754 Mar  4  2023 sidebar_bg.jpg
yash@LearningPC:~/github/yash-nigam.github.io$ ls -ltr assets/img/favicons/
total 168
-rw-r--r-- 1 yash yash 15531 Mar  4  2023 android-chrome-192x192.png
-rw-r--r-- 1 yash yash  8930 Mar  4  2023 mstile-150x150.png
-rw-r--r-- 1 yash yash   923 Mar  4  2023 favicon-16x16.png
-rw-r--r-- 1 yash yash   608 Mar  4  2023 safari-pinned-tab.svg
-rw-r--r-- 1 yash yash 15086 Mar  4  2023 favicon.ico
-rw-r--r-- 1 yash yash 66336 Mar  4  2023 android-chrome-512x512.png
-rw-r--r-- 1 yash yash 13736 Mar  4  2023 apple-touch-icon.png
-rw-r--r-- 1 yash yash  1270 Mar  4  2023 favicon-32x32.png

```
- Also put your personal photo to be used as avatar in the img folder.
- In the _config.yml file make following changes

```
avatar: /assets/img/yn_small.jpg

github:
  username: yash-nigam
```
- Under the _posts folder create a file as follows:


```
yash@LearningPC:~/github/yash-nigam.github.io$ ls -ltr _posts/
total 4
-rw-r--r-- 1 yash yash 446 Mar  4 00:14 2023-03-04-FirstPage.md
yash@LearningPC:~/github/yash-nigam.github.io$ cat _posts/2023-03-04-FirstPage.md
---
title: First Post
date: 2023-03-03 12:00:00 +0530
categories: [TOP_CATEGORIE, SUB_CATEGORIE]
tags: [TAG]     # TAG names should always be lowercase
---

```
- Under the _tabs folder create another markdown file of your choice.

```
yash@LearningPC:~/github/yash-nigam.github.io$ ls -ltr _tabs/
total 20
-rw-r--r-- 1 yash yash  47 Mar  3 15:00 tags.md
-rw-r--r-- 1 yash yash  56 Mar  3 15:00 categories.md
-rw-r--r-- 1 yash yash  55 Mar  3 15:00 archives.md
-rw-r--r-- 1 yash yash 194 Mar  3 15:00 about.md
-rw-r--r-- 1 yash yash 284 Mar  4 01:25 devto.md
yash@LearningPC:~/github/yash-nigam.github.io$ cat _tabs/devto.md
---
layout: page
title: dev.to Blog Posts
icon: fas fa-flask
order: 1
---
-----------
> <a href="https://dev.to/yashnigam/create-a-free-static-website-using-github-pages-and-jekyll-41a9" target="_blank">create a personal website using Github Pages with the Jekyll Framework</a>

```
- Verify the site locally and view the changes in browser

```
bundle exec jekyll s

```

![changes](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/nbzpm3ooj4oaki0k4vri.png)
---

- Commit and push the changes

```
yash@LearningPC:~/github/yash-nigam.github.io$ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   _config.yml

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        _posts/2023-03-04-FirstPage.md
        _tabs/devto.md
        assets/css/
        assets/img/

no changes added to commit (use "git add" and/or "git commit -a")

```
Ignore any Zone.Identifier files as they are autogenerated

```
yash@LearningPC:~/github/yash-nigam.github.io$ git add --all
warning: CRLF will be replaced by LF in _tabs/devto.md.
The file will have its original line endings in your working directory

yash@LearningPC:~/github/yash-nigam.github.io$ git commit -m "Added changes"
[main 6eded15] Added changes
 24 files changed, 64 insertions(+), 8 deletions(-)
 create mode 100644 _posts/2023-03-04-FirstPage.md
 create mode 100644 _tabs/devto.md
 create mode 100644 assets/css/style.scss
 create mode 100644 assets/img/favicons/android-chrome-192x192.png
 create mode 100644 assets/img/favicons/android-chrome-512x512.png
 create mode 100644 assets/img/favicons/apple-touch-icon.png
 create mode 100644 assets/img/favicons/favicon-16x16.png
 create mode 100644 assets/img/favicons/favicon-32x32.png
 create mode 100644 assets/img/favicons/favicon.ico
 create mode 100644 assets/img/favicons/mstile-150x150.png
 create mode 100644 assets/img/favicons/safari-pinned-tab.svg
 create mode 100644 assets/img/sidebar_bg.jpg
 create mode 100644 assets/img/yn_small.jpg

yash@LearningPC:~/github/yash-nigam.github.io$ git push
remote: Resolving deltas: 100% (3/3), completed with 3 local objects.
To https://github.com/yash-nigam/yash-nigam.github.io.git
   c30df68..6eded15  main -> main
```
- Once changes are pushed, make sure GitHub build and deploy action is successful 

`https://github.com/yash-nigam/yash-nigam.github.io/actions`

Added changes
Build and Deploy #2: Commit 6eded15 pushed by yash-nigam

- Now in the actual deployed site we can see that favicon, avatar, side bar tab and a new blog post is created successfully.

![Final Site](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0r1j003fep6fyimi6rtl.png)

### References
- [https://chirpy.cotes.page/posts/getting-started/](https://chirpy.cotes.page/posts/getting-started/)
- [https://jekyllrb.com/docs/installation/](https://jekyllrb.com/docs/installation/)
- [Install Windows Subsystem for Linux](https://ubuntu.com/tutorials/install-ubuntu-on-wsl2-on-windows-11-with-gui-support#2-install-wsl)
- [Chirpy Starter](https://chirpy.cotes.page/posts/getting-started/#option-1-using-the-chirpy-starter)
- [Publishing with a custom GitHub Actions workflow
](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow)
- [https://chirpy.cotes.page/](https://chirpy.cotes.page/)

###chirpy implementations
- [https://jamstackthemes.dev/demo/theme/jekyll-theme-chirpy/](https://jamstackthemes.dev/demo/theme/jekyll-theme-chirpy/)
- [https://bpostance.github.io/](https://bpostance.github.io/)