GitHub Pages

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files directly from a repository on GitHub, optionally runs the files through a build process, and publishes a website. It's a powerful way to showcase projects, documentation, or personal websites directly from your GitHub repositories.

Getting Started with GitHub Pages

Setting Up GitHub Pages

1. Create or navigate to your GitHub repository
2. Go to repository Settings
3. Scroll down to the "GitHub Pages" section
4. Select a source branch (usually main or gh-pages)
5. Choose a publishing folder (root / or /docs)
6. Click "Save"
7. Wait for your site to be published (URL will be displayed when ready)

Directory Structure

The content of your GitHub Pages site depends on how you configure it:

repository/
├── .github/         # GitHub-specific files
├── docs/            # If publishing from /docs
│   ├── index.html   # Main page
│   ├── css/         # Stylesheets
│   └── js/          # JavaScript files
├── index.html       # If publishing from root
└── README.md        # Repository information

Working with Themes

GitHub Pages provides built-in themes for quick setup:

1. Go to repository Settings
2. Scroll to the "GitHub Pages" section
3. Click "Choose a theme"
4. Select your preferred theme
5. Commit the changes

Using Jekyll with GitHub Pages

GitHub Pages has built-in support for Jekyll, a static site generator:

repository/
├── _config.yml           # Site configuration
├── _layouts/             # Page templates
│   └── default.html      # Default layout
├── _posts/               # Blog posts
│   └── 2023-01-01-post.md
├── _data/                # Data files
├── _includes/            # Reusable components
├── _sass/                # SCSS partials
├── assets/               # Static assets
└── index.md              # Home page

Advanced GitHub Pages Features

Custom Domains

1. Purchase a domain from a domain registrar
2. Go to your repository's Settings
3. In the "GitHub Pages" section, enter your custom domain
4. Configure your domain's DNS settings:
   • For apex domains: Create A records pointing to GitHub's IP addresses
   • For subdomains: Create a CNAME record pointing to username.github.io
5. Create a CNAME file in your repository with your domain name

Secure Your Site with HTTPS

GitHub Pages automatically secures custom domains with HTTPS:

1. Ensure your DNS is correctly configured
2. Check the "Enforce HTTPS" option in your GitHub Pages settings
3. Wait for the certificate to be provisioned (can take up to 24 hours)

Troubleshooting GitHub Pages

Common issues and solutions:

• 404 errors: Check if your repository is public and pages are enabled
• CSS not loading: Ensure paths are relative or use the {{ site.baseurl }} prefix
• Build failures: Review build logs in the Actions tab
• Custom domain not working: Verify DNS settings and CNAME file
• Content not updating: Check if you've pushed to the correct branch

Additional Resources