TOC
- Why use GitHub Pages and Jekyll
- Prerequisites
- 1: Dev Machine Setup
- 2: Use Chirpy Starter Template
- 3: Install dependencies
- 4: Modify config yaml and preview changes
- 5: Using GitHub Actions
- 6: Commit Changes to Repo
- 7: View the website
- 8: Personalize by Adding Avatar, favicon, sidebar link and create first post
Why use GitHub Pages and Jekyll ?
GitHub Pages 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 (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
- Windows/Linux developer machine
- GitHub Account
1: setup Ruby, Gem and Jekyll on developer machine
- 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
- Open a PowerShell prompt as an Administrator and run:
- 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
- Sign in to GitHub.com with your account, and go to chirpy-starter, click the button Use this template > Create a new repository
- 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
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 will be present in our new site: https://github.com/yash-nigam/yash-nigam.github.io
3: Installing dependencies of chirpy-starter
- 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
- 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.
5: Configure to Deploy the Website using GitHub Actions
- 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.
6: Commit and push changes to repo
- 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
- Once the changes are pushed to the repo, a build and deploy workflow should be automatically triggered.
- View the final website
8: Add Avatar, favicon, a new post and an sidebar tab.
Add Avatar and favicon images
- Create a directory named img under assets in the root of repo
yash-nigam.github.io/assets
and favicons under img. - Follow the steps to generate and add faviconshttps://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
- 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.
References
- https://chirpy.cotes.page/posts/getting-started/
- https://jekyllrb.com/docs/installation/
- Install Windows Subsystem for Linux
- Chirpy Starter
- Publishing with a custom GitHub Actions workflow
- https://chirpy.cotes.page/
Top comments (0)