Setting up a Blog with Github Pages and Jekyll

Creating a blog using GitHub Pages and Jekyll is a fantastic way to share your thoughts, projects, and ideas with the world. Jekyll, a static site generator, allows you to create a blog with minimal setup, while GitHub Pages provides free hosting. In this guide, we’ll walk through the entire process, from setting up the repository to configuring the local development environment and deploying your blog using GitHub Actions.

1. Introduction

GitHub Pages is a free hosting service provided by GitHub that allows you to host static websites directly from a GitHub repository. Jekyll, on the other hand, is a static site generator that transforms your plain text into static websites and blogs. Together, they make a powerful combination for creating and hosting a blog with minimal effort.

In this blog post, we’ll cover:

The prerequisites for setting up a blog with GitHub Pages and Jekyll.
Steps to create a repository and configure GitHub Pages.
Setting up a local development environment with Ruby and Jekyll.
Structuring your Jekyll project for a blog.
Automating deployment using GitHub Actions.

2. Prerequisites

Before we dive into the setup, ensure you have the following:

A GitHub Account: If you don’t have one, sign up at GitHub.
Git Installed: Download and install Git from git-scm.com.
Ruby Installed: Jekyll is built on Ruby, so you’ll need to install Ruby. We’ll cover this in detail later.
A Text Editor: Use any text editor or IDE of your choice (e.g., Vim).

3. Steps to Set Up Your Blog

Step 1: Create a GitHub Repository

Log in to your GitHub account.
Click on the + icon in the top-right corner and select New repository.
Name your repository username.github.io, where username is your GitHub username. This naming convention is required for GitHub Pages to work.
Choose Public or Private:
- Public: Anyone can view your repository. Required if you want to use GitHub Pages for free without GitHub Pro.
- Private: Only you (and invited collaborators) can see it. You need GitHub Pro to enable GitHub Pages on a private repo.
Click Create repository.

If you plan to use a custom domain, you can set it up later in the GitHub Pages settings after deploying your site.

Step 2: Configure GitHub Pages Deployment

Go to your repository’s Settings.
Navigate to Pages in the left sidebar.
Under Build and deployment, select GitHub Actions as the source.
Choose the Jekyll workflow template. This will create a .github/workflows/jekyll.yml file in your repository, which automates the build and deployment process.

Step 3: Clone the Repository

Open your terminal or command prompt.

Run the following command to clone your repository:

 git clone https://github.com/username/username.github.io
 cd username.github.io

Step 4: Set Up the Local Development Environment

Install Ruby

Jekyll requires Ruby. To ensure compatibility with GitHub Pages, install the same Ruby version used by GitHub Pages.

Check the Ruby version used by GitHub Pages in the GitHub Pages documentation.
Install the correct Ruby version using a version manager like rbenv or rvm. For example:
```
 rbenv install 3.1.2
 rbenv global 3.1.2
```
Verify the installation:
```
 ruby -v
```

Install Bundler

Bundler is a Ruby gem that manages dependencies for your Jekyll project.

Install Bundler:
```
 gem install bundler
```

Install Jekyll

Create a Gemfile in your project directory with the following content:

 source "https://rubygems.org"
 gem "jekyll"
 gem "github-pages", group: :jekyll_plugins

Run the following command to install the dependencies:
```
 bundle install
```

Step 5: Configure Your Jekyll Project

`_config.yml`

This file contains the configuration for your Jekyll site. Create a _config.yml file with the following content:

title: Your Blog Title
description: A blog about your interests and projects.
baseurl: "" # Leave empty if hosting at username.github.io
url: "https://username.github.io" # Replace with your GitHub Pages URL
theme: minima # Default Jekyll theme
plugins:
    - jekyll-feed

`.gitignore`

Create a .gitignore file to exclude unnecessary files from version control:

_site
.sass-cache
.jekyll-cache
vendor

`Gemfile`

Your Gemfile should already exist from the previous step. Ensure it includes the github-pages gem for compatibility with GitHub Pages.

Favicon and Icons

Add a favicon to your site by placing a favicon.ico file in the root directory or the static folder.

`robots.txt`

Create a robots.txt file to control search engine indexing:

User-agent: *
Allow: /

Step 6: Create Entry Files and Folders

Entry Files

Create the following files in the root directory:

index.md: The homepage of your blog.
blog.md: A page listing your blog posts.
project.md: A page showcasing your projects.
404.md: A custom 404 page for handling not-found errors.

Example index.md:

---
layout: default
title: Home
---

# Welcome to My Blog

This is the homepage of my blog.

`_includes` Folder

This folder contains reusable components like headers, footers, and custom elements. For example, create a file _includes/image.html to display images at a specific ratio:

<div class="image-container" style="padding-bottom: ;">
    <img src="" alt="" />
</div>

`_layouts` Folder

This folder contains reusable layouts. For example:

default.html: The default layout for all pages.
post.html: A layout for blog posts.
redirect.html: A layout for handling redirects.

Example _layouts/default.html:

<!DOCTYPE html>
<html>
    <head>
        <title>{ { page.title } }</title>
    </head>
    <body>
        { { content } }
    </body>
</html>

`static` Folder

Store static files like images, videos, and CSS in the static folder. For example, place your images in static/images.

Step 7: Run Your Blog Locally

Start the Jekyll server:

 bundle exec jekyll serve -w --incremental

Open your browser and navigate to http://localhost:4000 to view your blog.

Step 8: Commit and Push Changes

Add your changes to Git:

 git add .
 git commit -m "Initial setup of Jekyll blog"

Push the changes to GitHub:
```
 git push origin main
```

Step 9: Automate Deployment with GitHub Actions

The Jekyll workflow template you selected earlier will automatically build and deploy your site whenever you push changes to the main branch. You can view the deployment status in the Actions tab of your repository.

4. Conclusion

Congratulations! You’ve successfully set up a blog using GitHub Pages and Jekyll. You now have a fully functional blog with a local development environment and automated deployment. From here, you can customize your blog further by adding themes, plugins, and more content.

Feel free to send me an email and share your feedback or ask questions. If you found this guide helpful, consider sharing it with others who might benefit from it.

Happy blogging! 🚀