enuno/github-pages

GitHub Pages Skill

Use when working with GitHub Pages static site hosting, generated from official GitHub documentation.

When to Use This Skill

This skill should be triggered when:

• Creating or configuring a GitHub Pages site
• Setting up custom domains for GitHub Pages
• Configuring publishing sources (branch, folder, or GitHub Actions)
• Working with Jekyll themes and plugins
• Troubleshooting GitHub Pages deployment issues
• Setting up HTTPS for GitHub Pages sites
• Understanding GitHub Pages limitations and features

Quick Reference

Site Types

| Type | Repository Name | URL | |------|-----------------|-----| | User site | <username>.github.io | https://<username>.github.io | | Organization site | <org>.github.io | https://<org>.github.io | | Project site | Any name | https://<username>.github.io/<repo> |

Publishing Sources

1. Branch publishing - Deploy from a specific branch (e.g., main, gh-pages)
2. Folder publishing - Deploy from / (root) or /docs folder
3. GitHub Actions - Custom workflow for building and deploying

Common Patterns

Create a GitHub Pages site

# Create repository named <username>.github.io for user site
# Or any name for project site

# Add index.html or index.md
echo "# Hello World" > index.md
git add index.md
git commit -m "Initial GitHub Pages site"
git push

Configure publishing source

1. Go to repository Settings > Pages
2. Under "Build and deployment", select source:
   • "Deploy from a branch" for static files
   • "GitHub Actions" for custom builds
3. Select branch and folder if using branch deployment

Set up custom domain

# Add CNAME file to repository root
echo "example.com" > CNAME
git add CNAME && git commit -m "Add custom domain" && git push

DNS Configuration:

• Apex domain (example.com): Add A records pointing to GitHub IPs
• Subdomain (www.example.com): Add CNAME record pointing to <username>.github.io

GitHub IP addresses for A records:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Jekyll configuration

# _config.yml
title: My Site
description: A GitHub Pages site
theme: minima
plugins:
  - jekyll-feed
  - jekyll-seo-tag

Custom GitHub Actions workflow

# .github/workflows/pages.yml
name: Deploy to GitHub Pages

on:
  push:
    branches: ["main"]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: |
          # Your build commands here
          npm run build
      - uses: actions/upload-pages-artifact@v3
        with:
          path: ./dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment

Disable Jekyll processing

# Add .nojekyll file for non-Jekyll static sites
touch .nojekyll
git add .nojekyll && git commit -m "Disable Jekyll" && git push

Supported Static Site Generators

GitHub provides workflow templates for:

• Jekyll (default)
• Next.js
• Nuxt.js
• Gatsby
• Hugo
• Astro
• Eleventy (11ty)
• And more...

Limitations

• No server-side languages (PHP, Ruby, Python)
• Repository size limits apply
• Bandwidth and build time limits for free tier
• Private repos require GitHub Pro/Team/Enterprise

Reference Files

This skill includes comprehensive documentation in references/:

• getting_started.md - Site creation, publishing sources, workflows, HTTPS (5 articles)
• custom_domains.md - Domain setup, DNS configuration (2 articles)
• jekyll.md - Jekyll integration, themes, plugins (2 articles)
• troubleshooting.md - 404 errors and common issues (1 article)

Use view to read specific reference files when detailed information is needed.

Working with This Skill

For Beginners

Start with references/getting_started.md for foundational concepts on creating your first GitHub Pages site.

For Custom Domains

See references/custom_domains.md for DNS configuration and HTTPS setup.

For Jekyll Users

Check references/jekyll.md for theme customization and Jekyll-specific features.

For Debugging

Review references/troubleshooting.md for common issues like 404 errors.

Common Issues

404 Error

• Check repository visibility (must be public for free accounts)
• Verify publishing source is configured correctly
• Ensure index.html or index.md exists
• Wait up to 10 minutes for changes to propagate

Build Failures

• Check Jekyll syntax in _config.yml
• Verify Gemfile dependencies are compatible
• Review GitHub Actions logs for errors

Custom Domain Not Working

• Verify DNS records are correct
• Check CNAME file is in repository root
• Ensure HTTPS is enforced in repository settings
• DNS propagation can take up to 24 hours

Notes

• This skill was generated from official GitHub documentation
• Reference files preserve the structure and examples from source docs
• Content fetched via GitHub's Article API for accuracy
• Last updated: January 2026

Updating

To refresh this skill with updated documentation:

1. Re-run the scraper using GitHub's Article API
2. The skill will be rebuilt with the latest information

Resources

• GitHub Pages Documentation
• Jekyll Documentation
• GitHub Actions for Pages