How GitHub Pages Works

GitHub provides a web page service linked to your account username. Pretty neat, right?

For example, my GitHub User ID is jayleekr. If I create a new blog repository at https://github.com/jayleekr/jayleekr.github.io, then GitHub automatically creates a website at https://jayleekr.github.io/ that’s connected to that repository.

This means GitHub (on the remote side) automatically generates a backend web server for you following this naming convention. It’s like getting free hosting! 🎉

Let’s build the front-end!

Front-end Framework

There are tons of front-end frameworks out there, but to get up and running quickly, I’ll use the most popular method: Jekyll.

Jekyll was created by Tom Preston-Werner (GitHub co-founder) using Ruby-on-Rails, and it’s an MIT-licensed static site generator.

(Makes sense that the GitHub co-founder’s tool integrates seamlessly with GitHub, right?)

Step 1: Create Repository

1. Go to GitHub and create a new repository
2. Important: Name it [your-username].github.io
   • For example: jayleekr.github.io
3. Make it public (required for free GitHub Pages)
4. Initialize with a README

Step 2: Choose a Jekyll Theme

Instead of building from scratch, let’s use a pre-made theme:

Option A: Fork a Theme

1. Browse Jekyll Themes
2. Find one you like
3. Fork it to your account
4. Rename the repository to [username].github.io

Option B: Start from Scratch

# Clone your repository
git clone https://github.com/[username]/[username].github.io.git
cd [username].github.io

# Create a basic Jekyll site
echo "Hello World" > index.html

# Commit and push
git add .
git commit -m "Initial commit"
git push origin main

Step 3: Local Development Setup

To test locally before publishing:

Install Jekyll

# On macOS (using Homebrew)
brew install ruby
gem install jekyll bundler

# On Ubuntu/Debian
sudo apt-get install ruby-dev
gem install jekyll bundler

# On Windows
# Download Ruby installer from rubyinstaller.org
gem install jekyll bundler

Run Locally

# In your repository directory
jekyll serve

# or if you have a Gemfile
bundle exec jekyll serve

Visit http://localhost:4000 to see your site!

Step 4: Customize Your Blog

Basic Configuration (_config.yml)

title: Your Blog Title
description: A cool description of your blog
baseurl: ""
url: "https://[username].github.io"

# Build settings
markdown: kramdown
highlighter: rouge
theme: minima

# Social links
github_username: your-github-username
twitter_username: your-twitter-username

Create Your First Post

Create a file: _posts/2020-09-11-my-first-post.md

---
layout: post
title:  "My First Blog Post!"
date:   2020-09-11 14:10:00 +0900
categories: general
---

# Hello World!

This is my first blog post on GitHub Pages. 
Pretty exciting stuff! 🚀

## What I'll Write About

- Technology stuff
- Coding adventures
- Random thoughts

Stay tuned for more content!

Add Pages

Create about.md:

---
layout: page
title: About
permalink: /about/
---

Hi there! I'm [Your Name], and this is my blog where I write about...

Step 5: Deploy

The beauty of GitHub Pages is that deployment is automatic:

git add .
git commit -m "Add first post and about page"
git push origin main

Within a few minutes, your changes will be live at https://[username].github.io!

Pro Tips

1. Use a Custom Domain (Optional)

Create a CNAME file with your domain:

myblog.com

Then configure your DNS settings to point to GitHub Pages.

2. SEO Optimization

Add to your _config.yml:

plugins:
  - jekyll-sitemap
  - jekyll-seo-tag

3. Comments with Disqus

Add to your _config.yml:

disqus:
  shortname: your-disqus-shortname

4. Google Analytics

google_analytics: UA-XXXXXXXX-X

Troubleshooting

Build Failures

• Check your _config.yml syntax
• Make sure all posts have proper front matter
• Verify image paths are correct

Local vs Production Differences

• Use bundle exec jekyll serve locally
• Check that your baseurl is set correctly
• Ensure all links use site.baseurl prefix

Slow Build Times

• Minimize plugins
• Optimize images
• Use incremental: true in development

Advanced Features

Custom Themes

# Add to Gemfile
gem "theme-name"

# Install
bundle install

# Update _config.yml
theme: theme-name

Collections

Perfect for portfolios or project showcases:

collections:
  projects:
    output: true
    permalink: /:collection/:name/

What’s Next?

Now that you have a blog:

1. Write consistently - Even short posts are valuable
2. Engage with community - Comment on other blogs
3. Share your knowledge - Teach what you learn
4. Customize gradually - Improve the design over time

Remember: The best blog is one that exists and gets updated regularly! 🚀