Your simple guide to web hosting.

A Noob's Guide to Hosting a Static Site on GitHub Pages

Introduction

GitHub Pages is a fantastic free service provided by GitHub that lets you host a static website directly from a GitHub repository. If your website is built with just HTML, CSS, and JavaScript (no server-side code like PHP or Python), GitHub Pages is an excellent and cost-effective option for noobs.

This guide will cover: * What a static site is. * How to prepare your files for GitHub Pages. * Creating a GitHub repository. * Enabling GitHub Pages for your site. * Using a custom domain (optional).

Disclaimer: GitHub's interface can change. Always refer to the official GitHub Pages documentation for the most up-to-date instructions.

What is a Static Site?

A static site consists of files like HTML, CSS, JavaScript, images, and other assets that don't change unless you manually update them. There's no database or server-side processing involved in displaying the content to the user. The server simply sends the files as they are to the visitor's browser. Many simple portfolio sites, landing pages, blogs (if built with a static site generator), and documentation sites are static.

Preparing Your Files

  1. Organize Your Site: Make sure all your website files (HTML, CSS, JS, images, etc.) are in a single folder on your computer.
  2. Homepage Name: Your main homepage file must be named index.html (all lowercase) and it must be in the root of this folder.
  3. Relative Links: Ensure all links within your site (to other pages, CSS files, images) use relative paths (e.g., about.html, css/style.css, images/photo.jpg). Absolute local paths (like C:\Users\...) will not work.

Creating a GitHub Repository

If you don't have a GitHub account, you'll need to sign up for a free one at github.com.

  1. Create a New Repository:
    • Once logged in to GitHub, click the "+" icon in the top-right corner and select "New repository."
    • Repository Name:
      • For a user/organization site: If you want your site to be at yourusername.github.io, the repository must be named yourusername.github.io (replace yourusername with your actual GitHub username).
      • For a project site: If you want your site to be at yourusername.github.io/myproject/, you can name the repository anything you like (e.g., myproject).
    • Description (Optional): Add a brief description.
    • Public/Private: For GitHub Pages with a free account, the repository usually needs to be Public.
    • Initialize this repository with a README (Optional but Recommended): Check this box.
    • Click "Create repository."

Uploading Your Site Files to GitHub

You can upload files directly through the GitHub website (easiest for noobs for a small site) or use Git commands (more advanced, but better for larger projects or frequent updates).

Method 1: Uploading via GitHub Website

  1. Go to your newly created repository on GitHub.
  2. Click the "Add file" button and choose "Upload files."
  3. Drag and drop your website files and folders from your computer into the upload area. Alternatively, click "choose your files" to select them.
    • Important: Make sure you upload the contents of your main website folder, not the folder itself, unless your index.html is inside it at the top level. Your index.html needs to be at the root of the repository for a user/organization site, or at the root of the publishing source for a project site.
  4. Once all files are selected/dragged, add a commit message (e.g., "Initial site upload").
  5. Click "Commit changes."

Enabling GitHub Pages

  1. In your repository on GitHub, click the "Settings" tab.
  2. In the left sidebar, scroll down and click on "Pages" (under "Code and automation").
  3. Source:
    • Under "Build and deployment," for "Source," select "Deploy from a branch."
  4. Branch:
    • Select the branch you want to publish from. Typically, this will be main (or master for older repositories).
    • For the folder, usually select /(root).
    • Click "Save."
  5. Wait a Few Minutes: GitHub Pages will now build and deploy your site. This might take a minute or two.
  6. Access Your Site: Once deployed, the "Pages" settings screen will show a green bar with the URL of your live site (e.g., https://yourusername.github.io/myproject/ or https://yourusername.github.io/). Click the link to visit your site!

Using a Custom Domain (Optional)

If you own a domain name (e.g., www.yourcoolsite.com) and want to use it for your GitHub Pages site:

  1. In GitHub Pages Settings:
    • Go back to the "Pages" settings for your repository.
    • Under "Custom domain," type your custom domain (e.g., www.yourcoolsite.com) and click "Save."
    • GitHub might show you DNS records you need to configure (usually A records or a CNAME record).
  2. At Your Domain Registrar:
    • Log in to where you bought your domain (e.g., GoDaddy, Namecheap).
    • Go to the DNS management section for your domain.
    • Add the DNS records provided by GitHub. This usually involves:
      • Creating A records pointing to specific IP addresses provided by GitHub (for apex domains like yourcoolsite.com).
      • Or creating a CNAME record for a subdomain (like www) pointing to yourusername.github.io.
    • Refer to GitHub's official documentation on "Configuring a custom domain for your GitHub Pages site" for the exact records and steps, as these can change.
  3. Wait for DNS Propagation: Changes to DNS records can take some time to update across the internet (from a few minutes to 48 hours).
  4. Enforce HTTPS: Once your custom domain is working, ensure "Enforce HTTPS" is checked in your GitHub Pages settings.

Pros & Cons of GitHub Pages (for Noobs)

Pros: * Free: For public repositories, it's completely free. * Simple for Static Sites: If your site is just HTML, CSS, and JS, it's very straightforward. * Version Control: Your website is backed by Git, so you have a history of all changes. * Good for Portfolios & Project Sites: Excellent for showcasing personal projects or open-source documentation. * Custom Domains: Supports using your own domain name.

Cons: * Static Sites Only: Cannot run server-side code (PHP, Python, Node.js backends, databases). * Public Repositories (for free tier): Your website's code will be publicly visible. * Build Process for Some: If you use static site generators (like Jekyll, Hugo), there's a build step involved, which adds a bit of complexity (though GitHub Actions can automate this). For simple HTML/CSS/JS, this isn't an issue. * Limited Support: While GitHub has excellent documentation, direct customer support for Pages issues might be limited compared to paid hosting.

Where to Get Help

  • Official GitHub Pages Documentation: docs.github.com/en/pages is your best resource.
  • Community Forums: Many online communities discuss GitHub Pages.

GitHub Pages is a powerful and free way for noobs to host their static websites, especially if they are already familiar with or learning GitHub.