What GitHub Pages Does and Why It Works for a Personal Site

GitHub Pages turns a GitHub repository into a live website without requiring you to rent server space or pay a hosting company. You write your HTML, CSS, and JavaScript files, push them to a repository, and GitHub automatically publishes them at a web address you own. The site updates whenever you push new code — no separate deployment step, no control panel to log into.

This works because GitHub already stores your code and watches for changes. When you push to a repository named in a specific way, GitHub detects that and builds your site from those files. For a personal portfolio or project showcase, this means you get a working website for the cost of nothing, and you learn how version control actually works in the process.

The trade-off is that GitHub Pages works best for static sites — HTML, CSS, and JavaScript that run in the browser. You cannot run a database or server-side code. For a resume site, portfolio, documentation, or blog, that is not a limitation. For anything that needs a login system or stores user data, you would need a different hosting approach.

Key Takeaways

  • GitHub Pages publishes a website directly from a repository, with no hosting fees or separate deployment tool.
  • You create an HTML file named index.html in the repository root, push it to GitHub, and the site goes live at username.github.io within minutes.
  • The site updates automatically whenever you push new code to the repository, so you never manually upload files.
  • GitHub Pages works for static sites only — HTML, CSS, and JavaScript in the browser — not for databases or server-side code.
  • Custom domain names are possible but require buying a domain separately and pointing it to GitHub's servers through DNS settings.

Setting Up Your GitHub Account and Creating the Repository

Start by creating a GitHub account at github.com if you do not have one. Use your real name or a professional username — this will appear in your site's web address. Once you are logged in, click the plus icon in the top right corner and select "New repository".

Name the repository exactly username.github.io, replacing "username" with your GitHub username. This naming convention is what tells GitHub to publish it as a website. Leave the repository public — GitHub Pages does not work on private repositories. Add a README file if you want, but it is not required for the site to work. Click "Create repository".

You now have an empty repository. GitHub will not publish anything until you add an index.html file, which is the file GitHub looks for first when someone visits your site.

Creating and Uploading Your First HTML File

You have two paths: edit files directly on GitHub's website, or clone the repository to your computer and push files from there. For a first site, the GitHub website is faster.

In your new repository, click "Add file" and select "Create new file". Name it index.html. In the editor, paste this starter HTML:

<!DOCTYPE html> <html> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Your Name</title> </head> <body> <h1>Hello, I'm Your Name</h1> <p>This is my personal website.</p> </body> </html>

Replace "Your Name" with your actual name. Scroll down and click "Commit changes". GitHub will ask for a commit message — type something like "Add index.html" and commit. Within two to three minutes, visit username.github.io in your browser. You should see your page live.

Styling Your Site With CSS

Once your basic HTML is live, you can add styling. The simplest approach is to write CSS directly inside the HTML file, in a <style> tag in the head section. This keeps everything in one file and works perfectly for a small personal site.

Edit your index.html file by clicking on it in the repository, then clicking the pencil icon to edit. Add this style block inside the <head> tag, after the title:

<style> body { font-family: Arial, sans-serif; line-height: 1.6; max-width: 800px; margin: 0 auto; padding: 20px; background-color: #f4f4f4; } h1 { color: #333; } </style>

Commit the change. Your site will update within a minute. The page now has a centered layout, readable font, and a light background. You can adjust colors, fonts, and spacing by editing the CSS values and committing again.

Adding More Pages and Navigation

A personal site usually needs more than one page — perhaps a portfolio page, an about page, or a contact section. Create new HTML files the same way you created index.html: click "Add file", name it something like portfolio.html or about.html, and write the HTML content.

Link between pages using anchor tags. In your index.html, add navigation links like this:

<nav> <a href="index.html">Home</a> <a href="about.html">About</a> <a href="portfolio.html">Portfolio</a> </nav>

Each new file you create becomes a page at username.github.io/filename.html. If you want the URL to be cleaner, create a folder by naming a file portfolio/index.html — then that page lives at username.github.io/portfolio instead.

Using a Custom Domain Name

Your site starts at username.github.io, but you can point a custom domain to it if you own one. First, buy a domain from a registrar like Namecheap, GoDaddy, or Google Domains. The domain costs money — usually five to fifteen dollars per year — but GitHub Pages itself remains free.

Once you own the domain, go to your repository settings, scroll to "Pages", and find the "Custom domain" field. Type your domain name and save. GitHub will create a file called CNAME in your repository that tells GitHub to serve your site at that domain.

Then log into your domain registrar and find the DNS settings. You need to point your domain to GitHub's servers. The exact steps vary by registrar, but you are looking for an option to edit DNS records or nameservers. GitHub's documentation at pages.github.com has instructions for the major registrars. Once DNS propagates — usually within a few hours — your site will be live at your custom domain.

Keeping Your Site Updated

Every time you edit a file in your repository and commit the change, GitHub rebuilds your site. There is no separate publish button or waiting period — just commit and refresh your browser in a minute or two.

If you are working on your computer instead of GitHub's website, the process is the same: edit your files locally, commit them with git, push to GitHub, and the site updates automatically. This is why GitHub Pages is useful for learning — you see version control and deployment happen in real time.

If something breaks, you can always see your commit history. Click the clock icon in your repository to view past commits, and you can revert to an earlier version if needed. This safety net makes it straightforward to experiment with new designs or layouts without fear of permanently breaking your site.

Frequently Asked Questions

How long does it take for my site to go live after I push code?

Usually two to three minutes. GitHub builds your site in the background. If it takes longer than five minutes, check that your repository is public and that the file is named index.html exactly. You can also check the "Pages" section in repository settings to see if there were any build errors.

Can I use a template or theme instead of writing HTML from scratch?

Yes. GitHub Pages supports Jekyll, a tool that lets you use pre-made themes. You can also read free HTML templates from sites like HTML5 UP or Templated, then upload the files to your repository. Both approaches skip the HTML writing step but still use GitHub Pages to publish.

What if I want to add a contact form to my site?

GitHub Pages cannot process form submissions because it does not run server-side code. You can create a form that looks like it works, but the data goes nowhere. For a real contact form, use a service like Formspree or Basin that handles submissions for you — they provide a code snippet you paste into your HTML.

Can I password-protect my site or make it private?

No. GitHub Pages publishes to the public internet. The repository itself can be private, but the published site is always public. If you need a private site, you would need different hosting.

What happens if I delete the repository?

Your site disappears when ready. GitHub Pages only publishes what is in the repository. If you want to keep a backup, clone the repository to your computer before deleting it.