Master Git & GitHub From Scratch

Clear, practical, and structured lessons designed to take you from Git fundamentals to real-world GitHub collaboration.

GitHub Pages

GitHub Pages is a static website hosting service that publishes website files directly from a GitHub repository.

It is useful for hosting developer portfolios, project documentation, landing pages, and personal blogs. GitHub Pages supports HTML, CSS, JavaScript, and static assets such as images.

Important: GitHub Pages does not run server-side application code or provide a database. Applications that require a backend API need to host that backend separately.

1. GitHub Pages URL Structure

GitHub Pages provides different URL formats depending on your website type.

Website Type URL Format Repository Name
Project Website https://username.github.io/repository-name/ Your project repository
User Website https://username.github.io/ username.github.io
Custom Domain https://www.example.com/ Your configured repository

Replace username and repository-name with your actual GitHub username and repository name.


2. Publish a Website Using GitHub Pages

Follow these steps to publish a basic HTML website.

  1. Create a repository: Sign in to GitHub and create a repository for your website.
  2. Add an HTML file: Select Add file → Create new file, name the file index.html, and add your HTML.
  3. Open repository settings: Navigate to Settings → Pages.
  4. Select the publishing source: Under Build and deployment, select Deploy from a branch, if available.
  5. Select the branch and folder: Choose your publishing branch, usually main, and select /(root) or /docs, depending on where your files are stored.
  6. Save and wait: Save the configuration and check the Pages section for the published website URL.
Example: index.html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My GitHub Website</title>
</head>
<body>
    <h1>Welcome to My Website</h1>
    <p>This website is hosted using GitHub Pages.</p>
</body>
</html>
Result: After GitHub finishes publishing, open the Pages URL to view your live website. The first deployment may take several minutes.

3. Common Publishing Methods

Method Best For How It Works
Root Folder Simple HTML, CSS, and JavaScript sites Publishes files from the selected branch's root directory.
/docs Folder Documentation stored alongside project code Publishes static files from the selected branch's docs directory.
GitHub Actions React, Vue, Angular, and static site generators Builds the project and deploys its generated static output.

Framework projects generally need a build step before deployment. The generated output directory depends on the framework and its configuration.


4. Using a Custom Domain

If you own a domain, you can configure GitHub Pages to publish your site through that domain.

  1. Open your repository's Settings → Pages section.
  2. Enter your domain under Custom domain.
  3. Configure the required DNS records with your domain provider.
  4. Wait for DNS verification and enable HTTPS when available.

5. GitHub Pages Limitations

  • Static hosting: It does not execute server-side code such as PHP or Python, or run an ASP.NET Core or Node.js backend.
  • No hosted database: A database-backed application needs a separately hosted backend and database.
  • Usage limits: GitHub Pages has published build, site-size, and bandwidth limits.
  • Commercial use: GitHub Pages is not intended to serve as free hosting for an online business, e-commerce site, or SaaS platform.
Tip: Before deploying a large website, review GitHub's current Pages limits and acceptable-use policies.

6. When Should You Use GitHub Pages?

  • Personal developer portfolios
  • Project documentation and tutorials
  • Static landing pages
  • Personal blogs generated as static websites
  • Frontend applications that can be built into static files
Key Takeaway
GitHub Pages makes it easy to publish static websites directly from a GitHub repository. For applications requiring server-side logic or a database, deploy the backend separately.