github-pages

name	github-pages
description	Complete GitHub Pages deployment and management system. Static site hosting with Jekyll, custom domains, and GitHub Actions. USE WHEN user mentions 'github pages', 'deploy static site', 'host website on github', 'jekyll site', 'custom domain for github', OR wants to publish a website from a repository.

GitHub Pages Skill

Complete guide for deploying, configuring, and managing GitHub Pages sites.

Quick Reference

Site Type	Repository Name	URL Pattern
User/Org Site	<username>.github.io	https://<username>.github.io
Project Site	Any repository name	https://<username>.github.io/<repo>

Availability:

• Public repos: GitHub Free (all plans)
• Private repos: GitHub Pro, Team, Enterprise

---

Workflow Routing

When executing a workflow, output this notification directly:

Running the **WorkflowName** workflow from the **GithubPages** skill...

Workflow	Trigger	File
QuickStart	"setup github pages", "create pages site"	workflows/QuickStart.md
CustomDomain	"add custom domain", "configure domain"	workflows/CustomDomain.md
JekyllSetup	"setup jekyll", "add jekyll theme"	workflows/JekyllSetup.md
ActionsWorkflow	"custom build", "github actions for pages"	workflows/ActionsWorkflow.md
Troubleshoot	"pages not working", "fix github pages"	workflows/Troubleshoot.md
Deploy	"deploy to github pages", "publish site"	workflows/Deploy.md

---

Examples

Example 1: Create a new GitHub Pages site

User: "Setup GitHub Pages for my project"
→ Invokes QuickStart workflow
→ Checks if user/org or project site
→ Configures publishing source (branch or Actions)
→ Creates initial content structure
→ Verifies deployment

Example 2: Add custom domain

User: "Add my domain example.com to GitHub Pages"
→ Invokes CustomDomain workflow
→ Determines domain type (apex vs subdomain)
→ Provides DNS configuration instructions
→ Adds CNAME file or configures via Settings
→ Enables HTTPS enforcement

Example 3: Setup Jekyll theme

User: "Add a theme to my GitHub Pages site"
→ Invokes JekyllSetup workflow
→ Lists available supported themes
→ Configures _config.yml
→ Sets up custom CSS/layouts if needed

Example 4: Deploy with custom build

User: "Deploy my Next.js site to GitHub Pages"
→ Invokes ActionsWorkflow workflow
→ Creates custom GitHub Actions workflow
→ Configures build process
→ Sets up artifact deployment

---

Site Types

User/Organization Site

Requirements:

• Repository name MUST be <username>.github.io
• Only ONE per account
• Publishes from default branch

Setup:

# Create repository named exactly: username.github.io
# Enable Pages in Settings > Pages
# Select source branch

Project Site

Requirements:

• Can use any repository
• Multiple project sites allowed
• URL includes repository name

Setup:

# Any repository works
# Enable Pages in Settings > Pages
# Choose: branch (root or /docs) OR GitHub Actions

---

Publishing Sources

Option 1: Deploy from Branch

Best for: Jekyll sites, simple static sites

Configuration:

1. Go to Settings > Pages
2. Select "Deploy from a branch"
3. Choose branch (main, gh-pages, etc.)
4. Choose folder: / (root) or /docs

Behavior:

• Pushes to branch trigger automatic builds
• Jekyll processes Markdown by default
• CNAME file auto-created for custom domains

Option 2: GitHub Actions Workflow

Best for: Custom builds, non-Jekyll generators

Configuration:

1. Go to Settings > Pages
2. Select "GitHub Actions"
3. Create workflow file in .github/workflows/

Behavior:

• Full control over build process
• Works with Hugo, Gatsby, Next.js, etc.
• Artifacts uploaded and deployed

---

Jekyll Integration

Auto-Enabled Plugins

These plugins work automatically on GitHub Pages:

Plugin	Purpose
jekyll-coffeescript	CoffeeScript support
jekyll-default-layout	Automatic layouts
jekyll-gist	GitHub Gist embedding
jekyll-github-metadata	Repository metadata
jekyll-optional-front-matter	Optional YAML front matter
jekyll-paginate	Pagination
jekyll-readme-index	README as index
jekyll-titles-from-headings	Auto-generate titles
jekyll-relative-links	Convert relative links

Supported Themes

Available without additional configuration:

• Architect
• Cayman
• Dinky
• Hacker
• Leap day
• Merlot
• Midnight
• Minima
• Minimal
• Modernist
• Slate
• Tactile
• Time machine

Usage in _config.yml:

theme: jekyll-theme-minimal
title: My Site
description: Site description

Remote Themes

Use any Jekyll theme from GitHub:

remote_theme: owner/repo-name

---

Custom Domains

Domain Types

Type	Example	DNS Record
Apex	example.com	A or ALIAS
WWW Subdomain	www.example.com	CNAME
Custom Subdomain	blog.example.com	CNAME

DNS Configuration

For Apex Domains (A Records):

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

For Apex Domains (AAAA Records - IPv6):

2606:50c0:8000::153
2606:50c0:8001::153
2606:50c0:8002::153
2606:50c0:8003::153

For Subdomains (CNAME Record):

www.example.com → username.github.io
blog.example.com → username.github.io

Verification Commands

# Check A records
dig example.com +noall +answer -t A

# Check AAAA records
dig example.com +noall +answer -t AAAA

# Check CNAME records
dig www.example.com +nostats +nocomments +nocmd

---

Usage Limits

Resource	Limit
Repository size	1 GB (recommended)
Published site size	1 GB (maximum)
Bandwidth	100 GB/month (soft)
Builds	10/hour (soft, branch only)
Deployment timeout	10 minutes

Restrictions:

• No server-side languages (PHP, Python, Ruby)
• No commercial transactions or e-commerce
• Must comply with GitHub Terms of Service

---

Security Best Practices

1. Verify custom domains - Prevents domain takeover attacks
2. Avoid wildcard DNS - *.example.com creates security risks
3. Enable HTTPS - Always enforce HTTPS after certificate provisioning
4. Don't expose secrets - Public sites accessible even from private repos
5. Update DNS promptly - If disabling site, update/remove DNS records

---

Common Issues & Solutions

Issue	Solution
Site not publishing	Check branch/folder settings, verify entry file exists
404 errors	Ensure index.html, index.md, or README.md at root
Custom domain not working	Wait 24h for DNS propagation, verify records with dig
HTTPS not available	Wait up to 1 hour after DNS verification
Mixed content warnings	Change http:// to https:// in all assets
Build failures	Check Actions tab for error logs

---

File References

Topic	Reference File
DNS Configuration	references/DnsConfiguration.md
Jekyll Configuration	references/JekyllConfiguration.md
Actions Workflows	references/ActionsWorkflows.md
Troubleshooting Guide	references/Troubleshooting.md
Best Practices	references/BestPractices.md

---

Scripts

Script	Purpose
scripts/verify-dns.sh	Verify DNS configuration for custom domains
scripts/check-site-status.sh	Check if GitHub Pages site is live

---

External Documentation

• GitHub Pages Quickstart
• Custom Domain Configuration
• Jekyll Documentation
• GitHub Actions for Pages

---

Gotchas

• GitHub Pages caches at the CDN level for ~10 minutes — recently-pushed changes may not appear immediately; check via ?nocache=$(date +%s) query param.
• Custom domain requires CNAME record AND a CNAME file in the repo — missing either breaks HTTPS cert generation, often silently.
• Jekyll plugins must be on GitHub's whitelist — Gemfile-only plugins fail build silently in some old configs.
• Branch-vs-folder source: gh-pages branch vs /docs folder on main vs / on main — switching sources requires an explicit redeploy to take effect.
• HTTPS enforcement is per-Page-property — switching from Settings UI doesn't revoke HTTP-only access immediately; old caches serve HTTP until they expire.
• Build error logs are in Actions UI, NOT in Pages settings — first-time users debug for hours in the wrong place.