GitHub Pages Reference

Overview

GitHub Pages is GitHub’s free static site hosting service, perfect for:

• 📄 Personal portfolios and resumes
• 📚 Project documentation with Jekyll
• 🎨 Demo sites and prototypes
• 📝 Blogs and simple websites

Domain Configuration

domains/username.json

{
  "owner": {
    "username": "username",
    "email": "user@example.com"
  },
  "records": {
    "CNAME": "username.github.io"
  }
}

Setup Process

1. Enable GitHub Pages

1. Go to repository Settings
2. Navigate to Pages section
3. Set Source to your branch (usually main)
4. Choose root directory: / (root) or /docs

2. Add Custom Domain

1. In Custom domain field: username.loves-to.dev
2. Click Save
3. Enable “Enforce HTTPS”
4. GitHub creates CNAME file automatically

3. Repository Structure

your-repo/
├── index.html          # Homepage (required)
├── _config.yml         # Jekyll config (optional)
├── CNAME              # Auto-generated, don't edit
├── assets/
│   ├── css/
│   └── images/
└── _posts/            # For Jekyll blogs
    └── 2024-01-01-hello.md

Jekyll Configuration

Basic _config.yml

_config.yml

title: Your Site Title
description: Site description for SEO
url: "https://username.loves-to.dev"
baseurl: ""

# Build settings
markdown: kramdown
theme: minima
plugins:
  - jekyll-feed
  - jekyll-sitemap
  - jekyll-seo-tag

# Social links
github_username: username
twitter_username: username

Supported Themes

• minima (default)
• jekyll-theme-cayman
• jekyll-theme-minimal
• jekyll-theme-modernist
• More themes →

Custom Domain Setup

DNS Verification

# Check if domain resolves
nslookup username.loves-to.dev

# Should return Cloudflare IPs:
# 104.16.132.229
# 104.16.133.229

SSL Certificate

• Automatic: GitHub provisions SSL within 24 hours
• Verification: Look for green padlock in browser
• Force HTTPS: Always enable this option

File Limits & Restrictions

Limit	Value
Repository size	1 GB recommended
File size	100 MB max
Monthly bandwidth	100 GB soft limit
Build time	10 minutes max

Jekyll Build Process

Automatic Builds

• Triggered on every push to source branch
• Build logs available in Actions tab
• Failed builds send email notifications

Local Development

# Install Jekyll
gem install bundler jekyll

# Create new site
jekyll new my-site

# Serve locally
bundle exec jekyll serve
# Visit http://localhost:4000

Common Issues

Build Failures

# Check _config.yml syntax
plugins:
  - jekyll-feed    # Correct
  - jekyl-feed     # Wrong - typo

CNAME File Conflicts

• Don’t manually edit CNAME file
• Let GitHub manage it automatically
• Conflicts cause domain verification to fail

404 Errors

• Ensure index.html or index.md exists
• Check file naming (case-sensitive)
• Verify Jekyll front matter syntax

Advanced Features

Custom 404 Page

404.html

---
layout: default
permalink: /404.html
---

<h1>Page Not Found</h1>
<p>Sorry, the page you're looking for doesn't exist.</p>

GitHub Actions Integration

.github/workflows/pages.yml

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm install
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist