Contents

What is GitHub Pages

GitHub Pages takes the files from your repository and serves them as a static site. Works with HTML, CSS, JavaScript. Free, the default domain is username.github.io.

Perfect for: portfolios, documentation, blogs, landing pages. (This blog lives on Pages too — deployed via GitHub Actions.)

Step 1 — Create a repository

The repository name must be exactly username.github.io, where username is your GitHub login.

💡 For a project (not a personal site) the name can be anything — it'll be served at username.github.io/repo-name.

Step 2 — Add index.html

GitHub Pages looks for the entry point — an index.html file at the root of the repository. Here's the minimum file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>My site</title>
</head>
<body>
  <h1>Hello, world!</h1>
</body>
</html>

Step 3 — Enable Pages in settings

  1. Open the repository's Settings
  2. In the left sidebar find Pages
  3. Source: Deploy from branch
  4. Pick the branch — main or master, folder — / (root)
  5. Click Save

GitHub will start the deploy — usually 1-2 minutes.

Step 4 — Open your site

After the deploy finishes, the address shows up in the Pages section: https://username.github.io.

Custom domain

To hook up your own domain:

  1. In the Pages settings enter the domain in the Custom domain field
  2. At your registrar add a DNS record: CNAME @ username.github.io
  3. Wait for DNS to propagate — anywhere from 5 minutes to a few hours

✅ HTTPS turns on automatically via Let's Encrypt — nothing to configure.

Common issues

Site doesn't update after push — check that you're pushing to the branch you set in settings. If it's correct — wait a few minutes, the CDN caches.

404 page — make sure the file is named exactly index.html (lowercase) and lives at the root, not in a subfolder.

⚠️ GitHub Pages doesn't support server-side logic (Node.js, PHP, Python). Static only: HTML, CSS, JS. If you need a backend, see deploying to a VPS.

Share: