github-pages（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

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

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