| 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:
Project Site
Requirements:
- Can use any repository
- Multiple project sites allowed
- URL includes repository name
Setup:
Publishing Sources
Option 1: Deploy from Branch
Best for: Jekyll sites, simple static sites
Configuration:
- Go to Settings > Pages
- Select "Deploy from a branch"
- Choose branch (main, gh-pages, etc.)
- 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:
- Go to Settings > Pages
- Select "GitHub Actions"
- 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
dig example.com +noall +answer -t A
dig example.com +noall +answer -t AAAA
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
- Verify custom domains - Prevents domain takeover attacks
- Avoid wildcard DNS -
*.example.com creates security risks
- Enable HTTPS - Always enforce HTTPS after certificate provisioning
- Don't expose secrets - Public sites accessible even from private repos
- 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
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.
