Complete Guide to GitHub Pages: Build Professional Static Websites from Scratch

by

🌏 閱讀中文版本

Table of Contents

Complete
Guide to GitHub Pages: Build Professional Static Websites from
Scratch

Table of Contents

Is GitHub Pages Right for Me?

Quick Self-Assessment

GitHub Pages is perfect for you if:

  • ✅ You want to build a personal portfolio to showcase projects
  • ✅ You need technical documentation or project landing pages
  • ✅ You want a technical blog without managing servers
  • ✅ You know basic HTML/CSS or are willing to learn Markdown
  • ✅ You need a completely free solution with no traffic worries

GitHub Pages might not be suitable if:

  • ❌ You need database functionality (user registration,
    comments)
  • ❌ You need backend processing (form submissions, real-time
    chat)
  • ❌ You need e-commerce features (shopping cart, payment
    processing)
  • ❌ You have 100+ articles and care about build speed

Three Approaches Compared

Approach Best For Pros Cons Rating
Pure HTML Complete beginners Simplest, instant deployment Hard to maintain, repetitive edits ⭐⭐
Jekyll Themes Frontend beginners Ready to use, easy maintenance Need to learn basic Markdown & YAML ⭐⭐⭐⭐⭐
Advanced Frameworks (Hugo/Astro) Experienced developers Fast builds, powerful features Steep learning curve, terminal required ⭐⭐⭐

Recommended Path: Beginners start with Jekyll
themes, consider advanced frameworks after gaining experience.

True Cost Analysis

Completely Free Includes:

  • ✅ Unlimited traffic (100GB/month soft limit)
  • ✅ Automatic HTTPS encryption
  • ✅ 1GB storage space
  • ✅ Custom domain support

When to Consider Alternatives:

Your Needs GitHub Pages Recommended Alternative
Portfolio showcase ✅ Perfect fit –
Tech blog (<100 posts) ✅ Suitable –
Tech blog (>100 posts) ⚠️ Works but slow Hugo + Netlify
Contact forms needed ⚠️ Needs external service Formspree (free)
User login needed ❌ Not supported Firebase + Netlify
E-commerce site ❌ Not supported Shopify / WooCommerce
CMS backend needed ⚠️ Can integrate Netlify CMS / Forestry

Legend:

  • ✅ = Works out of the box
  • ⚠️ = Possible with third-party integrations
  • ❌ = Not suitable, consider other solutions

10-Minute Quick Start

Option A: Deploy Static
HTML (Most Basic)

Suitable for: You have HTML files and just want them
online

Steps:

  1. Create Repository
    • Log in to GitHub
    • Click “+” in top-right → “New repository”
    • Repository name: your-username.github.io (e.g.,
      yourname.github.io)
    • Select “Public”
    • Check “Add a README file”
    • Click “Create repository”
  2. Upload Your HTML
    • Go to your repository page
    • Click “Add file” → “Upload files”
    • Drag your index.html and other files
    • Click “Commit changes”
  3. Done!
    • Wait 1-2 minutes
    • Visit https://your-username.github.io
    • Your site is live

Estimated Time: 5 minutes

Suitable for: You want professional design without
starting from scratch

Steps:

1. Choose a Theme

We recommend 3 excellent themes:

Option 1: Minimal Mistakes (Top Pick) – Best for:
Developer portfolios, technical blogs – Style: Modern, professional,
highly customizable – Demo: https://mmistakes.github.io/minimal-mistakes/
– Features: Responsive design, search support, social sharing

Option 2: al-folio (Academic Style) – Best for:
Researchers, PhD students, academic showcases – Style: Clean, academic,
multilingual – Demo: https://alshedivat.github.io/al-folio/
– Features: Publication lists, project showcases, CV support

Option 3: Beautiful Jekyll (Easiest) – Best for:
Complete beginners, personal blogs – Style: Clean, readable, simple
setup – Demo: https://beautifuljekyll.com/ –
Features: 5-minute setup, comprehensive docs

2. Fork the
Theme (Using Minimal Mistakes as Example)

  1. Open the theme’s GitHub page
  2. Click “Fork” in top-right
  3. Rename repository to your-username.github.io
  4. Click “Create fork”

3. Enable GitHub Pages

  1. Go to your forked repository
  2. Click “Settings” → “Pages”
  3. Under “Source”, select “Deploy from a branch”
  4. Choose “main” or “master” branch
  5. Click “Save”

4. Modify Basic Information

Find and edit _config.yml (click filename → click pencil
icon to edit):

# Only modify these 5 fields
title: "Your Name"
name: "Your Full Name"
description: "One-sentence bio"
url: "https://your-username.github.io"
baseurl: ""

Click “Commit changes” to save.

5. Test Your Site

Wait 2-3 minutes, visit https://your-username.github.io.
Your site is live!

Estimated Time: 15-20 minutes

Quick Start Checklist

Complete these steps and your site will be live!

Phase 1: Build Foundation (Est. 30 minutes)

Phase 2: Add Content (Est. 1-2 hours)

Phase 3: Optimize (Optional, Est. 2-4 hours)

Content Maintenance Guide

Three Ways to Add
Posts (From Easy to Advanced)

Suitable for: Don’t want to install software,
occasional content updates

Steps:

  1. Open GitHub repository
  2. Navigate to _posts folder
  3. Click “Add file” → “Create new file”
  4. Filename format: YYYY-MM-DD-title.md (e.g.,
    2025-01-15-my-first-post.md)
  5. Paste this content:
---
layout: post
title: "My First Post"
date: 2025-01-15
categories: blog
---

This is my first post content.

## Section Heading

You can write content using Markdown syntax.
  1. Click “Commit changes”
  2. Wait 1-2 minutes for auto-deployment

Pros: No software installation, edit anywhere
Cons: No live preview, need to wait for deployment

Method 2: GitHub Desktop
(Visual Tool)

Suitable for: Want local editing but unfamiliar with
Git commands

Steps:

  1. Download GitHub Desktop
  2. Clone Repository to Local
    • Open GitHub Desktop
    • File → Clone Repository
    • Select your username.github.io
    • Choose save location
    • Click “Clone”
  3. Edit Files
    • Use your favorite editor (VS Code, Sublime Text) to modify
      files
    • Add posts to _posts folder
  4. Commit Changes
    • Return to GitHub Desktop
    • Fill in commit message at bottom-left (e.g., “Add post: My Project
      Introduction”)
    • Click “Commit to main”
    • Click “Push origin”
  5. Done
    • Wait 1-2 minutes for auto-deployment

Pros: Local preview, batch edit multiple files
Cons: Need software installation

Method 3: Git Commands
(Advanced Users)

Suitable for: Comfortable with Terminal, want full
control

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

# Add post
nano _posts/2025-01-15-my-post.md

# Commit changes
git add .
git commit -m "Add post: My Project Introduction"
git push

Tip: Beginners should start with Method 1, move to
Method 2 after getting familiar.

Common Content Update
Scenarios

Scenario 1: Update Bio

File Location: _config.yml or
about.md (depends on theme)

Steps: 1. Find and edit the file 2. Modify
description or bio field 3. Save and
commit

**Example (_config.yml):**

author:
  name: "Your Name"
  bio: "Frontend Developer / Open Source Contributor / Tech Writer"
  location: "Taipei, Taiwan"
  links:
    - label: "GitHub"
      url: "https://github.com/your-username"

Scenario 2: Add Project
Showcase

File Location: Create _portfolio folder
or use _posts

**Example File (_portfolio/project-name.md):**

---
title: "Project Name"
excerpt: "Brief project description (one sentence)"
header:
  teaser: /assets/images/project-screenshot.png
tags:
  - React
  - TypeScript
  - Firebase
---

## Project Overview

This project solves...

## Tech Stack

- **Frontend:** React, TypeScript, Tailwind CSS
- **Backend:** Firebase Functions
- **Deployment:** Vercel

## Project Links

- [Live Demo](https://your-project.com)
- [GitHub Repository](https://github.com/your-username/project-name)

## Screenshots

![Project Home](/assets/images/project-home.png)

## Challenges & Solutions

1. **Performance Optimization:** Used React.memo to reduce unnecessary re-renders
2. **State Management:** Adopted Zustand for simplified complex state logic

Scenario 3: Adjust Navigation
Menu

File Location: _config.yml or
_data/navigation.yml (depends on theme)

Example (navigation.yml):

main:
  - title: "About"
    url: /about/
  - title: "Portfolio"
    url: /portfolio/
  - title: "Blog"
    url: /blog/
  - title: "Contact"
    url: /contact/

Scenario 4: Change Theme
Style

File Location: _config.yml

Example:

# Minimal Mistakes theme offers multiple color schemes
minimal_mistakes_skin: "default" # Options: air, aqua, contrast, dark, dirt, neon, mint, plum, sunrise

Save the changes, wait for redeployment to see the new color
scheme.

Markdown Quick Guide
(Essential Only)

80% of needs covered by these syntaxes:

# Heading 1 (Largest)
## Heading 2
### Heading 3

**Bold text**
*Italic text*

[Link text](https://example.com)

![Image description](/assets/images/photo.jpg)

- Bullet point 1
- Bullet point 2

1. Numbered list 1
2. Numbered list 2

Code Blocks (Essential for Technical Blogs):

def hello_world():
    print("Hello, GitHub Pages!")

More Advanced Syntax: Markdown Guide

Real-World Case Studies

Case 1: Frontend Developer
Portfolio

Website: Brittany Chiang

Tech Stack: – GitHub Pages – Custom HTML/CSS (not
Jekyll) – Responsive design

Content Structure: – Homepage: Hero
Section + 3 featured projects – About: Bio + skill tags
(React, TypeScript, Node.js) – Projects: 6
representative projects, each includes: – Project screenshot – Tech
stack – GitHub repo link – Live demo link – Contact:
Email + LinkedIn + GitHub

What to Learn: – ✅ Minimalist design, focused on
content – ✅ Smooth interactions (hover effects) – ✅ Concise project
descriptions (3 sentences: problem → solution → result) – ✅ Excellent
mobile optimization

Build Time Estimate: Initial build 4 hours + content
6 hours

Case 2: Open Source
Project Documentation

Website: Vue.js
Documentation (early version used GitHub Pages)

Tech Stack: – VuePress (Vue.js-based static site
generator) – GitHub Pages deployment – Multilingual support

Content Structure: – Guide:
Step-by-step tutorials – API Reference: Complete API
documentation – Examples: Interactive examples –
Migration Guide: Version upgrade guides

What to Learn: – ✅ Clear left-side navigation
(essential for documentation) – ✅ Powerful search (using Algolia
DocSearch) – ✅ Copyable code examples – ✅ Dark mode support

Use Case: If your project needs comprehensive
documentation, VuePress or Docusaurus is better than Jekyll.

Case 3: Personal Tech Blog

Website: Dan
Abramov’s Overreacted

Tech Stack: – Gatsby (React static site generator) –
GitHub Pages deployment – Markdown writing

Content Structure: – Homepage: Post
list (chronological) – Post Pages: In-depth technical
articles (2000-5000 words) – About: Minimalist bio –
RSS Feed: Subscription support

What to Learn: – ✅ Content is king (no excessive
design elements) – ✅ Optimized reading experience (font size, line
spacing, width) – ✅ Clear article structure (headings, code,
conclusion) – ✅ Excellent SEO (every post has meta description)

Insight: Great technical blogs don’t need fancy
designs—focus on content quality.

Common Traits Across All
Three Cases

Trait Case 1 Portfolio Case 2 Docs Case 3 Blog
Load Speed < 1s < 2s < 1s
Mobile Optimization ✅ Perfect ✅ Perfect ✅ Perfect
SEO Setup ✅ Yes ✅ Complete ✅ Complete
Custom Domain ✅ Yes ✅ Yes ✅ Yes
Update Frequency Quarterly Weekly 2-4 posts/month

Conclusion: Successful GitHub Pages sites
prioritize: speed, mobile optimization, content quality.

Advanced Optimization
(Optional)

Custom Domain Setup

Change from username.github.io to
blog.yourname.com

Step 1: Purchase Domain

  • Recommended: Cloudflare
    Registrar     (transparent pricing, no hidden fees)
  • Alternatives: Namecheap, GoDaddy, Gandi

Step 2: Configure DNS

Add these records in your domain registrar’s DNS settings:

Type: A
Name: @
Value: 185.199.108.153

Type: A
Name: @
Value: 185.199.109.153

Type: A
Name: @
Value: 185.199.110.153

Type: A
Name: @
Value: 185.199.111.153

Type: CNAME
Name: www
Value: your-username.github.io

Step 3: GitHub Configuration

  1. Go to repository
  2. Settings → Pages
  3. Enter your domain in “Custom domain” (e.g.,
    blog.yourname.com)
  4. Click “Save”
  5. Check “Enforce HTTPS” (wait for DNS propagation, ~10-30
    minutes)

Common Issues

Error 1: DNS_PROBE_FINISHED_NXDOMAIN – Cause: DNS
not propagated yet – Solution: Wait 24-48 hours (usually works within 1
hour)

Error 2: HTTPS Cannot be Enabled – Cause: Incorrect
DNS records – Solution: Check A records are correct, verify CNAME points
to username.github.io

Basic SEO Optimization

1. Auto-Generate sitemap.xml

Jekyll generates this by default. Confirm _config.yml
has:

plugins:
  - jekyll-sitemap

Verify: visit https://your-site/sitemap.xml

2. Google Search Console Setup

  1. Go to Google
    Search Console
  2. Add property → enter your site URL
  3. Verify ownership (choose “HTML tag” for easiest method)
  4. Add verification code to _includes/head.html in
    <head> section
  5. Submit sitemap: https://your-site/sitemap.xml

3. Social Sharing Preview
(Open Graph)

Add to each post’s front matter:

---
title: "Post Title"
image: /assets/images/og-image.jpg
description: "Brief post description (120-160 characters)"
---

Ensure your theme’s _includes/head.html includes these
meta tags:

<meta property="og:title" content="{{ page.title }}" />
<meta property="og:description" content="{{ page.description }}" />
<meta property="og:image" content="{{ site.url }}{{ page.image }}" />
<meta property="og:url" content="{{ site.url }}{{ page.url }}" />

Performance Optimization

1. Image Compression Tips

Tools: – TinyPNG
(online compression) – ImageOptim
(Mac app) – Squoosh (Google
open-source tool)

Recommendations: – Project screenshots: 1200px
width, JPG quality 85% – Open Graph images: 1200x630px, < 200KB –
Profile photos: 400x400px, < 100KB

2. CDN Acceleration
(Cloudflare Free Plan)

  1. Sign up at Cloudflare
  2. Add your site
  3. Change domain DNS to Cloudflare-provided nameservers
  4. Enable features:
    • Auto Minify (auto-compress HTML/CSS/JS)
    • Brotli compression
    • Browser Cache TTL

Effect: 30-50% faster global load times

3. Lazy Loading

Add loading="lazy" to image tags:

<img src="/assets/images/photo.jpg" alt="description" loading="lazy">

In Markdown, use HTML syntax:

<img src="/assets/images/photo.jpg" alt="description" loading="lazy">

GitHub Actions Automation
(Advanced)

Auto-Deploy Workflow Example:

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
          bundler-cache: true

      - name: Build site
        run: bundle exec jekyll build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

Function: Auto-build and deploy on every push to
main branch.

Frequently Asked Questions

Q1: Changes Not Showing
Immediately?

Cause: Browser cache or GitHub Pages deployment
incomplete

Solutions: 1. Force refresh page (Ctrl+F5 or
Cmd+Shift+R) 2. Test in incognito window 3. Check repository’s “Actions”
tab to confirm deployment complete (green checkmark) 4. Deployment
usually takes 1-3 minutes

Q2: Getting 404 Not Found
Error?

Possible Causes & Solutions:

Cause 1: Repository Name Incorrect – Verify
repository name is your-username.github.io (all lowercase)
– Example: if username is JohnDoe, repository should be
johndoe.github.io

Cause 2: GitHub Pages Not Enabled – Go to Settings →
Pages – Confirm “Source” is set to correct branch (usually
main)

Cause 3: Filename Incorrect – Homepage file must be
named index.html or index.md – Post files must
follow format YYYY-MM-DD-title.md

Q3: How to Customize CSS
Styles?

Method: Create custom CSS file to override theme
styles

Steps:

  1. Create /assets/css/custom.css
  2. Add your custom styles:
/* Change heading color */
h1 {
  color: #2c3e50;
}

/* Change link color */
a {
  color: #3498db;
}

/* Change code block background */
pre {
  background-color: #f8f9fa;
  border-radius: 4px;
}
  1. Add to _includes/head-custom.html (or theme
    equivalent):
<link rel="stylesheet" href="{{ '/assets/css/custom.css' | relative_url }}">

Q4: Can I Use Google
Analytics?

Yes! Jekyll themes usually have built-in Google
Analytics support.

Setup:

  1. Get Google Analytics tracking ID (format: G-XXXXXXXXXX
    or UA-XXXXXXXXX-X)
  2. Add to _config.yml:
# Google Analytics
google_analytics: G-XXXXXXXXXX
  1. Redeploy and wait 24 hours to see data in Google Analytics

Q5: How to Add Comments?

GitHub Pages doesn’t support comments natively, but you can
integrate third-party services:

Option 1: Disqus (Easiest)

  1. Sign up at Disqus
  2. Create a site (get shortname)
  3. Add to _config.yml:
disqus:
  shortname: your-shortname
  1. Ensure theme has Disqus enabled (Minimal Mistakes supports by
    default)

Option 2: giscus (Open-source, Privacy-friendly)

Uses GitHub Discussions as comments:

  1. Visit giscus.app
  2. Follow setup steps
  3. Add generated code to _layouts/post.html

Option 3: Utterances (Minimalist)

Uses GitHub Issues as comments:

  1. Visit utteranc.es
  2. Follow setup steps
  3. Add generated script to post pages

Q6: How to Backup My Site?

GitHub itself is a version control system—all your content is
already backed up in the cloud!

Extra Insurance:

  1. Local Backup: Use Git clone to download
    locally

    git clone https://github.com/your-username/your-username.github.io.git

  2. Regular Exports: Quarterly export important
    content (posts, images) to external drive

  3. Multi-platform Backup: Use GitHub Desktop to
    sync, ensuring local and remote consistency

Q7: Can I
Use Custom CSS Frameworks (like Tailwind CSS)?

Yes! But requires build process setup.

Easy Method (Using CDN):

Add to _includes/head.html:

<script src="https://cdn.tailwindcss.com"></script>

Professional Method (Local Build):

  1. Install Tailwind CSS

    npm install -D tailwindcss
npx tailwindcss init

  2. Configure tailwind.config.js

    module.exports = {
  content: [
    './_layouts/**/*.html',
    './_includes/**/*.html',
    './_posts/*.md',
  ],
  theme: {},
  plugins: [],
}

  3. Create GitHub Actions workflow to auto-compile CSS

Q8: Site Speed is Slow?

Diagnostic Tools:

  1. PageSpeed Insights
  2. GTmetrix

Common Optimization Methods:

Issue Solution
Images too large Compress images, use WebP format
Loading too many resources Remove unnecessary JavaScript plugins
No caching Use Cloudflare CDN
CSS/JS not minified Enable GitHub Actions auto-minify
Custom fonts too large Use system fonts or load only needed weights

Goals: – PageSpeed Insights score > 90 – First
load time < 2s

Summary

Key Takeaways

  1. Who Should Use GitHub Pages: Frontend beginners,
    developers wanting portfolios, technical blogs
  2. Fastest Path: Use Jekyll themes (like Minimal
    Mistakes), complete basic setup in 30 minutes
  3. Content Maintenance: Beginners use GitHub web
    editor, advanced users use GitHub Desktop
  4. Advanced Optimization: Custom domains, SEO, CDN
    acceleration are optional—focus on content quality first

Next Steps Recommendations

Beginners (Weeks 1-2): 1. Complete quick start
checklist 2. Add 3-5 project showcases 3. Write About page 4. Test
mobile display

Intermediate (Month 1): 1. Custom domain (if needed)
2. Set up Google Analytics 3. Optimize SEO (sitemap, meta descriptions)
4. Learn advanced Markdown syntax

Long-term Maintenance (3+ months): 1. Regularly
update portfolio (at least quarterly) 2. Write technical articles (1-2
per month) 3. Monitor site traffic and optimize 4. Consider if more
advanced tools needed (Hugo, Gatsby)

Official Documentation: – GitHub Pages Official Docs –
Jekyll Official Docs – Markdown Guide

Theme Marketplaces: – Jekyll Themes – GitHub.com/topics/jekyll-theme

Community Support: – GitHub Community Forum – Stack
Overflow – GitHub Pages – Reddit – r/github

(This section will automatically include links to related technical
articles after publication)

Related posts:

  1. GitHub Pages 完整指南：從零建立專業靜態網站
  2. 在 Windows 建立 .gitignore（含安全與常見範本）
  3. Create a .gitignore on Windows (English)
  4. “深入解析 Git 隱藏檔案：.gitkeep、.gitignore、.gitattributes 的真正用途與最佳實踐”

Leave a Comment