julianobarbosa/claude-code-skills/github-pages

GitHub Pages Skill

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

Quick Reference

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...

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:

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

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

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

File References

Scripts

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.