GitHub Pages: Hosting Static Sites From a Repo (User, Org, and Project Pages)
So far, this course has treated GitHub purely as a place to host and collaborate on source code. GitHub Pages extends that same repository into something more: a free, live, publicly hosted website, generated directly from files in your repository — no separate hosting provider or deployment pipeline required for a simple static site.
Learning Objectives
- Explain what GitHub Pages does and what kinds of sites it can host.
- Enable GitHub Pages for a repository and choose a source branch/folder.
- Distinguish between user/organization pages and project pages.
- Understand the resulting URL structure for each type of GitHub Pages site.
Key Terms to Know Before Using GitHub Pages
- GitHub Pages: A free static site hosting service built into GitHub, publishing HTML, CSS, and JavaScript files directly from a repository.
- Static site: A website made of pre-built HTML, CSS, and JavaScript files, served as-is without server-side processing, as opposed to a dynamic site requiring a backend.
- User/organization page: A GitHub Pages site tied to a special repository named exactly username.github.io (or org-name.github.io), served at the root of that URL.
- Project page: A GitHub Pages site tied to any other repository, served at a URL nested under the owner's GitHub Pages domain, in the form username.github.io/repository-name.
How GitHub Pages Actually Works
GitHub Pages takes files already sitting in a repository — HTML, CSS, JavaScript, and any assets — and serves them as a real, publicly accessible website, entirely free, with no separate hosting account or deployment pipeline needed for the basic case. It's specifically built for **static sites**: content that's pre-built and served as-is, making it ideal for portfolios, documentation sites, project landing pages, and blogs (especially when combined with a static site generator), but not suited for sites requiring server-side processing like a database-backed application or user authentication handled server-side.
GitHub Pages supports two distinct types of sites, distinguished by which repository they're tied to and the resulting URL structure:
**User or organization pages** are tied to one special repository per account, which must be named *exactly* `username.github.io` (for a personal account) or `org-name.github.io` (for an organization). Content from this repository's designated branch is served at the root of that domain: `https://username.github.io`. Each GitHub account (personal or organizational) can only have exactly one user/organization page, making it a natural fit for a primary personal or company website.
**Project pages** are tied to any *other* repository — you can have as many of these as you have repositories. Content is served at a URL nested under your GitHub Pages domain, in the form `https://username.github.io/repository-name`. This is the more common case for hosting documentation, a demo, or a landing page for one specific project, separate from your primary user/org site.
Enabling GitHub Pages for a repository (of either type) is done through Settings > Pages, where you choose a **source**: which branch (commonly `main` or a dedicated `gh-pages` branch) and which folder within that branch (commonly the repository root, or a `/docs` folder) GitHub should build the site from. Once configured, GitHub automatically builds and deploys the site whenever that source branch/folder receives new commits, typically live within a minute or two — no manual deployment step required, in contrast to many other static hosting workflows that require explicitly triggering a build and deploy.
A useful mental model: a user/org page is your one 'home base' site, while project pages let every individual repository optionally have its own dedicated, nested site — both powered by the exact same underlying GitHub Pages feature, just configured on different repositories with different naming conventions.
GitHub Pages Site Types: Visual Walkthrough
Draw a GitHub account icon labeled 'username'. Draw two branches from it. LEFT branch labeled 'User/Org Page': repository named exactly 'username.github.io' → arrow to a URL box 'https://username.github.io' (root domain, only ONE per account). RIGHT branch labeled 'Project Pages': multiple repository icons ('portfolio-site', 'docs-project', 'demo-app') each with an arrow to a nested URL box: 'https://username.github.io/portfolio-site', 'https://username.github.io/docs-project', etc. — captioned 'Unlimited project pages, one per repository.'
User/Org Pages vs Project Pages: Key Differences
| Aspect | User/Organization Page | Project Page |
|---|---|---|
| Required repository name | Exactly username.github.io (or org-name.github.io) | Any repository name |
| Resulting URL | https://username.github.io (root) | https://username.github.io/repository-name (nested) |
| How many per account? | Exactly one | One per repository — unlimited |
| Typical use case | Primary personal or company website | Documentation, demo, or landing page for one specific project |
Enabling GitHub Pages: Configuration and Examples
# Project page: enable GitHub Pages for an existing repository
# (Settings > Pages, on GitHub's website — not a Git command)
# Source: Branch = main, Folder = / (root)
# Resulting URL: https://your-username.github.io/your-repo-name
# User page: create the special repository (via git, then push)
git clone https://github.com/your-username/your-username.github.io.git
cd your-username.github.io
echo '<h1>Hello, I am your-username</h1>' > index.html
git add index.html
git commit -m "feat: initial user page content"
git push origin main
# Resulting URL (live within a minute or two, no separate deploy step): https://your-username.github.ioBreaking Down the GitHub Pages Setup Example
The project page example shows enabling Pages through repository settings for an ordinary repository, resulting in a nested URL. The user page example demonstrates the special naming requirement in action: cloning (or creating) a repository named exactly `your-username.github.io`, adding a basic `index.html`, and pushing — GitHub Pages automatically recognizes this special repository name and serves its content at the account's root domain, with no separate 'enable Pages' setting even required for this specific repository, since the naming convention itself signals GitHub Pages what to do.
How GitHub Pages Is Used on Real Projects
- Countless developers use a GitHub user page (username.github.io) as their primary online portfolio, since it's free, directly tied to their GitHub identity, and trivially updated with a simple git push.
- Open-source projects extremely commonly use a project page for hosting their documentation site, often built with a static site generator, kept automatically in sync with the project's actual repository.
- Companies and open-source organizations frequently use their organization's user page (org-name.github.io) as a lightweight marketing or landing site, especially for developer-tool companies whose audience is already comfortable on GitHub.
- Academic researchers and students commonly use project pages to host interactive demos or visualizations accompanying a specific research repository, without needing separate hosting infrastructure.
GitHub Pages Interview Questions and Answers
Q1. What is the difference between a GitHub user/organization page and a project page?
A user/organization page is tied to one special repository per account, named exactly username.github.io, served at the root of that domain, and limited to exactly one per account. A project page is tied to any other repository, served at a nested URL like username.github.io/repository-name, with one available per repository.
Q2. What kind of website is GitHub Pages designed to host, and what is it not suited for?
GitHub Pages is designed for static sites — pre-built HTML, CSS, and JavaScript served as-is, ideal for portfolios, documentation, and project landing pages. It's not suited for sites requiring server-side processing, such as a database-backed application or server-managed user authentication.
Q3. How do you configure which content GitHub Pages actually serves for a given repository?
Through the repository's Settings > Pages, choosing a source branch (commonly main or a dedicated gh-pages branch) and a folder within that branch (commonly the repository root or a /docs folder). GitHub automatically rebuilds and redeploys the site whenever that source location receives new commits.
GitHub Pages Quiz: Test Your Understanding
1. What must a repository be named for GitHub to serve it as a user/organization page?
- Any name is acceptable
- Exactly username.github.io (or org-name.github.io)
- index.html
- pages-repo
Answer: B. Exactly username.github.io (or org-name.github.io)
Explanation: GitHub specifically recognizes a repository named exactly like the account's GitHub Pages domain and serves its content at the root of that domain, distinct from any other repository.
2. How many user/organization pages can a single GitHub account have?
- Unlimited
- Exactly one
- Up to five
- Zero — only project pages are allowed
Answer: B. Exactly one
Explanation: Since a user/organization page requires the special username.github.io repository name, and only one repository can have that exact name, each account can have only one such page.
3. What type of website is GitHub Pages best suited for hosting?
- A database-backed web application requiring server-side processing
- A static site made of pre-built HTML, CSS, and JavaScript
- A site requiring server-managed user authentication
- None of the above
Answer: B. A static site made of pre-built HTML, CSS, and JavaScript
Explanation: GitHub Pages serves static content as-is, making it ideal for portfolios, documentation, and landing pages, but unsuited for sites requiring server-side processing or a backend.
Common Mistakes When Setting Up GitHub Pages
- Naming the user/organization page repository incorrectly (any deviation from the exact username.github.io format prevents it from working as a root-domain user page).
- Expecting GitHub Pages to support server-side processing or a database, when it only serves pre-built static files.
- Forgetting to configure the correct source branch/folder in Settings > Pages, resulting in a 404 even though the repository has the right content.
- Confusing a project page's nested URL structure with a user page's root domain, leading to broken links when sharing a site's address.
GitHub Pages: Exam-Ready Quick Notes
- GitHub Pages: free static site hosting built directly into GitHub repositories.
- User/org page: repository named exactly username.github.io, served at root domain, ONE per account.
- Project page: any other repository, served at username.github.io/repo-name, UNLIMITED (one per repo).
- Enable via Settings > Pages, choosing a source branch and folder; auto-rebuilds on new commits.
GitHub Pages: Key Takeaways
- GitHub Pages turns any repository's static files into a free, live, publicly hosted website with no separate deployment pipeline required.
- User/organization pages provide one root-domain site per account, while project pages let every repository optionally have its own nested site.
- GitHub Pages is purpose-built for static content — it doesn't support server-side processing or database-backed applications.
Frequently Asked Questions About GitHub Pages
Q1. What is GitHub Pages?
It's a free hosting service built into GitHub that publishes static websites — HTML, CSS, and JavaScript files — directly from a repository, without needing a separate hosting provider or deployment setup.
Q2. What is the difference between a user page and a project page on GitHub Pages?
A user page is tied to one special repository per account, named exactly username.github.io, served at the root of that domain. A project page is tied to any other repository, served at a nested URL like username.github.io/repository-name, and you can have as many project pages as you have repositories.
Q3. How do I enable GitHub Pages for my repository?
Go to the repository's Settings, then Pages, and choose a source branch (like main) and a folder (like the root or /docs) that GitHub should build the site from. The site becomes live at the appropriate URL shortly after.
Q4. Can GitHub Pages host a website with a database or user login system?
No. GitHub Pages only serves static, pre-built files — it doesn't support server-side processing, so it's not suited for sites that require a database or server-managed authentication.
Q5. How many websites can I host with GitHub Pages?
You can have exactly one user/organization page (tied to your special username.github.io repository) and an unlimited number of project pages, one for each of your other repositories that has Pages enabled.
Summary
GitHub Pages hosts static websites — pre-built HTML, CSS, and JavaScript — directly from a repository, entirely free, with no separate hosting provider needed. User or organization pages are tied to one special repository per account, named exactly `username.github.io`, served at the root of that domain, with only one allowed per account. Project pages are tied to any other repository, served at a nested URL like `username.github.io/repository-name`, with one available per repository. Enabling Pages for a repository involves choosing a source branch and folder under Settings > Pages, after which GitHub automatically rebuilds and redeploys the site whenever that source location receives new commits. GitHub Pages is best suited for static content like portfolios, documentation, and project landing pages, not sites requiring server-side processing.