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.
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.
- Create a repository: Sign in to GitHub and create a repository for your website.
-
Add an HTML file:
Select Add file → Create new file,
name the file
index.html, and add your HTML. - Open repository settings: Navigate to Settings → Pages.
- Select the publishing source: Under Build and deployment, select Deploy from a branch, if available.
-
Select the branch and folder:
Choose your publishing branch, usually
main, and select/(root)or/docs, depending on where your files are stored. - 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>
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.
- Open your repository's Settings → Pages section.
- Enter your domain under Custom domain.
- Configure the required DNS records with your domain provider.
- 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.
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