Deploying a Free Static Website with Jekyll and GitHub Pages (WIP)

Jump to bottom

Suhas Kadhane edited this page Sep 2, 2025 · 1 revision

Introduction

What is Jekyll

Brief overview: What Jekyll is, what GitHub Pages is, and why this combo matters.
Who it’s for: beginners, bloggers, or devs looking for free hosting.
End goal: user will have a live website at username.github.io.

Prerequisites

GitHub account
Git installed locally
Basic terminal knowledge (optional but helpful)
(Optional) Ruby installed if customizing Jekyll locally

Step-by-Step Walkthrough

Step-by-Step Walkthrough

Set up GitHub Repo
- Create a repo named username.github.io
- Initialize with README
Install Jekyll (optional for local testing)

Instructions for installing Ruby + Jekyll (with links to official docs)

Choose a Jekyll Theme

Easiest: pick a prebuilt theme from GitHub Pages themes
Alternative: clone a theme repo

Push Files to GitHub

Add theme files to repo
Commit and push

Enable GitHub Pages

Settings → Pages → Select branch
Site goes live at username.github.io

Verify Site

Visit link and check output

(Optional) Add Custom Domain

Steps for domain setup + DNS changes

Troubleshooting

Common issues (e.g., theme not rendering, 404 error, Ruby install issues).

Conclusion

What user has achieved
Benefits of static site hosting
Next steps: customizing theme, adding blog posts