Greetings, brave adventurer! Welcome to The GitHub Pages Portal: Forging Your Digital Realm - an epic journey that will transform your code into live web experiences. This quest will guide you through deploying your first website using GitHub Pages, the free hosting solution that turns your GitHub repositories into beautiful, accessible websites.
Whether you’re a novice developer seeking to showcase your first projects or an experienced coder looking to quickly deploy prototypes, this adventure will equip you with the fundamental skills of web deployment. No servers to manage, no hosting fees - just pure, magical web presence!
In the ancient scrolls of web development, there existed a mystical portal that could transform mere code repositories into living, breathing websites accessible to all corners of the realm. This portal, known as GitHub Pages, was forged by the great wizards of GitHub to democratize web hosting. No longer did developers need to bargain with hosting dragons or maintain server beasts - they could simply push their code and watch as the portal wove their creations into the very fabric of the web.
Today, you shall learn to harness this portal’s power, deploying your digital realms with the ease of a seasoned archmage. Master the incantations of repository settings, the rituals of Jekyll integration, and the secrets of custom domains. Your journey begins now!
By the time you complete this epic journey, you will have mastered:
You’ll know you’ve truly mastered this quest when you can:
This 🟢 Easy quest expects:
GitHub Pages works across all platforms! The core setup is identical, but here are platform-specific tips for your development environment.
# Ensure Git is installed
git --version
# Clone your repository (replace with your repo)
git clone https://github.com/yourusername/your-repo-name.git
cd your-repo-name
# Create a simple index.html
echo '<!DOCTYPE html>
<html>
<head><title>My GitHub Pages Site</title></head>
<body><h1>Hello from GitHub Pages!</h1></body>
</html>' > index.html
# Commit and push
git add index.html
git commit -m "Add basic HTML page"
git push origin main
macOS users can use Terminal for all Git operations. Consider installing GitHub Desktop for a GUI alternative.
# Check Git installation
git --version
# Clone repository
git clone https://github.com/yourusername/your-repo-name.git
cd your-repo-name
# Create index.html
@"
<!DOCTYPE html>
<html>
<head><title>My GitHub Pages Site</title></head>
<body><h1>Hello from GitHub Pages!</h1></body>
</html>
"@ | Out-File -FilePath index.html -Encoding UTF8
# Commit and push
git add index.html
git commit -m "Add basic HTML page"
git push origin main
Windows users can use Command Prompt, PowerShell, or Git Bash. GitHub Desktop provides an excellent GUI option.
# Verify Git installation
git --version
# Clone your repository
git clone https://github.com/yourusername/your-repo-name.git
cd your-repo-name
# Create a simple HTML page
cat > index.html << 'EOF'
<!DOCTYPE html>
<html>
<head><title>My GitHub Pages Site</title></head>
<body><h1>Hello from GitHub Pages!</h1></body>
</html>
EOF
# Commit and push changes
git add index.html
git commit -m "Add basic HTML page"
git push origin main
Linux users have native Git support. Use your preferred terminal emulator.
For cloud-based development (GitHub Codespaces, GitPod, etc.):
# The process is identical to local development
# Your cloud environment already has Git configured
git clone https://github.com/yourusername/your-repo-name.git
cd your-repo-name
# Create and edit files using the cloud IDE
# Commit and push as usual
git add .
git commit -m "Initial GitHub Pages setup"
git push origin main
Cloud environments provide the same GitHub Pages workflow with enhanced collaboration features.
In this foundational chapter, we’ll awaken the GitHub Pages portal by preparing your repository and creating the basic structure for your digital realm.
yourusername.github.io (for user/organization sites) OR any name (for project sites)git clone https://github.com/yourusername/your-repo-name.git
cd your-repo-name
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My GitHub Pages Site</title>
<style>
body {
font-family: Arial, sans-serif;
max-width: 800px;
margin: 0 auto;
padding: 20px;
background-color: #f5f5f5;
}
.hero {
text-align: center;
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: white;
padding: 50px 20px;
border-radius: 10px;
margin: 20px 0;
}
</style>
</head>
<body>
<div class="hero">
<h1>🌟 Welcome to My Digital Realm!</h1>
<p>Deployed with GitHub Pages - The Magic Portal</p>
</div>
<h2>About This Quest</h2>
<p>This website was created as part of the IT-Journey GitHub Pages quest.
Here you'll find information about my learning journey and projects.</p>
<h2>Projects</h2>
<ul>
<li><a href="#project1">Project 1: Coming Soon</a></li>
<li><a href="#project2">Project 2: Coming Soon</a></li>
</ul>
<footer style="text-align: center; margin-top: 50px; color: #666;">
<p>© 2025 My Digital Realm | Powered by GitHub Pages</p>
</footer>
</body>
</html>
git add index.html
git commit -m "Add initial GitHub Pages website"
git push origin main
Now that your repository is prepared, it’s time to activate the mystical portal that will make your website live!
https://yourusername.github.iohttps://yourusername.github.io/repository-nameTo truly master the portal, learn to wield Jekyll - the powerful static site generator that transforms markdown into magnificent websites!
# Install Ruby (if not already installed)
# macOS: brew install ruby
# Ubuntu: sudo apt-get install ruby-full
# Windows: Download from rubyinstaller.org
# Install Jekyll and Bundler
gem install jekyll bundler
# In your repository directory
jekyll new . --force # Force to avoid conflicts
Gemfile:
source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
group :jekyll_plugins do
gem 'jekyll-feed'
gem 'jekyll-sitemap'
gem 'jekyll-seo-tag'
end
title: My Digital Realm
description: A GitHub Pages site created during IT-Journey
url: "https://yourusername.github.io" # Update with your URL
baseurl: "" # Leave empty for user/org sites, or "/repo-name" for project sites
# Build settings
markdown: kramdown
highlander: true
plugins:
- jekyll-feed
- jekyll-sitemap
- jekyll-seo-tag
index.md:
---
layout: default
title: Home
---
# 🌟 Welcome to My Digital Realm!
This website was forged using **GitHub Pages** and **Jekyll** during the IT-Journey quest.
## About This Quest
Through this adventure, I've learned to:
- Deploy websites using GitHub Pages
- Use Jekyll for static site generation
- Configure custom domains
- Apply modern web development practices
## Projects
### Project 1: GitHub Pages Mastery
- **Status**: ✅ Completed
- **Technologies**: HTML, CSS, Jekyll
- **Live Demo**: [View Site](https://it-journey.dev)
### Project 2: Portfolio Foundation
- **Status**: 🚧 In Progress
- **Technologies**: Jekyll, Liquid templating
- **Features**: Responsive design, SEO optimization
bundle install
bundle exec jekyll serve
# Visit http://localhost:4000
git add .
git commit -m "Add Jekyll site with enhanced content"
git push origin main
Goal: Deploy a simple single-page website Time: 30 minutes Success Criteria:
Goal: Add CSS styling and multiple sections Time: 1 hour Success Criteria:
Goal: Implement full Jekyll site with themes Time: 2 hours Success Criteria:
Goal: Add custom domain and automated deployment Time: 3 hours Success Criteria:
graph TD
A[Level 001: GitHub Pages Portal] --> B[Level 010: Jekyll Mastery]
A --> C[Level 011: Static Site Generators]
A --> D[Level 001: HTML Basics]
A --> E[Level 001: CSS Fundamentals]
D --> A
E --> A
B --> F[Level 100: Advanced Web Development]
C --> F
style A fill:#e1f5fe
Quest Series: Web Development Fundamentals
Prerequisite Quests:
Recommended Background:
Follow-Up Quests:
Parallel Quests (can be completed in any order):
flowchart TD
A[Start Quest] --> B{Create Repository}
B --> C[Choose Repository Type]
C --> D[User/Org Site<br/>yourusername.github.io]
C --> E[Project Site<br/>yourusername.github.io/repo-name]
D --> F[Create index.html]
E --> F
F --> G[Commit & Push]
G --> H[Enable GitHub Pages<br/>in Settings]
H --> I[Configure Source Branch]
I --> J[Wait for Deployment<br/>1-3 minutes]
J --> K{Success?}
K --> L[Site Live!<br/>Access via GitHub URL]
K --> M[Troubleshoot Issues]
M --> N[Check Repository Settings]
N --> O[Verify Branch & Folder]
O --> P[Check Build Logs]
P --> J
L --> Q{Optional: Jekyll?}
Q --> R[Install Jekyll]
R --> S[Configure Gemfile<br/>& _config.yml]
S --> T[Create Jekyll Content]
T --> U[Test Locally]
U --> V[Deploy to GitHub Pages]
V --> W{Optional: Custom Domain?}
W --> X[Configure DNS]
X --> Y[Update GitHub Settings]
Y --> Z[Enable HTTPS]
Z --> AA[Quest Complete! 🎉]
V --> AA
L --> AA
Based on your performance in this quest:
If you excelled at basic deployment:
If you enjoyed styling and design:
If you want to explore alternatives:
If you’re ready for dynamic sites:
This quest was developed with AI assistance to ensure comprehensive coverage of GitHub Pages deployment, multi-platform compatibility, and educational best practices. AI helped generate code examples, validate technical accuracy, and enhance the fantasy narrative while maintaining educational integrity.
Human oversight ensured:
GitHub Pages represents the evolution of web hosting from complex server management to developer-friendly static site deployment. As part of the broader Jamstack movement, it enables:
Congratulations, Portal Master! You have successfully harnessed the power of GitHub Pages to create your digital realm. Your website now lives on the eternal web, accessible to adventurers across the globe. May your deployments be swift, your sites be fast, and your code be clean!
Ready for your next quest? The path of web development awaits… ⚔️✨
Quest Completed: Level 001 - The GitHub Pages Portal
Date Completed: 2025-11-16
Next Recommended Quest: Level 010: Jekyll Mastery