GitHub Pages lets you host a professional website for free — forever, with a custom domain, with no hosting bill. Here’s the complete tutorial from zero to live site, written for students who have never used Git before.
What You’ll Need
- A GitHub account (free at github.com)
- Git installed on your computer (git-scm.com)
- A text editor (VS Code is free and recommended)
- Basic HTML file (or a template — covered below)
Step 1: Create Your GitHub Account and Repository
- Go to github.com → Sign up
- Verify your email address
- Click «New repository» (the green button on your dashboard)
- Critical step: Name the repository exactly
yourusername.github.io— replace «yourusername» with your actual GitHub username - Set it to Public
- Check «Add a README file»
- Click «Create repository»
Step 2: Get a Free Portfolio Template
Instead of building from scratch, use a free template. The best free GitHub Pages portfolio templates:
- minimal-mistakes — Clean, professional Jekyll theme. Popular for academic/developer portfolios.
- al-folio — Designed for academics. Includes publications, CV, and projects sections.
- Cayman theme — Built into GitHub Pages. Activate in Settings → Pages → Theme Chooser (zero setup required).
- Start Bootstrap Resume template — Search GitHub for «startbootstrap-resume» — one-page resume site.
Fastest path: In your repository Settings → Pages → Theme Chooser → select Cayman. Your site is live in under 5 minutes with no code.
Step 3: Edit Your Content
The main file to edit is index.html (or index.md for Markdown-based themes). Open it in VS Code and replace the placeholder content: your name, title, About section, links to projects (GitHub repos, Figma files, live sites), contact email, and LinkedIn URL.
Step 4: Push Your Changes to GitHub
Open Terminal (Mac) or Command Prompt (Windows) in your project folder and run:
git init
git add .
git commit -m "Initial portfolio"
git branch -M main
git remote add origin https://github.com/yourusername/yourusername.github.io.git
git push -u origin mainYour site is now live at https://yourusername.github.io — usually within 60 seconds.
Step 5: Add a Custom Domain (Optional, Also Free)
- Register a domain name (Namecheap, Porkbun — roughly $10–$15/year)
- In your domain registrar’s DNS settings, add a CNAME record pointing to
yourusername.github.io - In your GitHub repository: Settings → Pages → Custom domain → enter your domain
- Check «Enforce HTTPS»
GitHub Pages provides free HTTPS for custom domains automatically via Let’s Encrypt.
How to Update Your Portfolio
Every time you add a new project or update your resume:
git add .
git commit -m "Added [project name]"
git pushChanges are live within 30–60 seconds. No FTP, no file manager, no hosting dashboard. This is also excellent practice for the Git workflow used by every software team.
Common Errors and How to Fix Them
The most common issue first-timers run into is the repository naming error. Your repository must be named exactly yourusername.github.io — with your actual GitHub username, lowercase, no spaces. If the name is off by one character, GitHub Pages won’t activate and your site won’t publish. Go to your repository settings and check the repository name under «General» if your site isn’t showing up after five minutes.
The second most common problem is the branch setting. GitHub defaults to deploying from the main branch, but older tutorials and some templates reference the master branch. Go to Settings → Pages and verify that the source branch matches the branch where your index.html file actually lives. If your files are on main but Pages is set to deploy from master, the site will show a 404 error indefinitely.
Why GitHub Pages Specifically Signals Competency to Tech Recruiters
A portfolio at username.github.io communicates something that a Wix or Squarespace URL doesn’t: you know how version control works and you’re comfortable with a command-line workflow. These are baseline expectations for software engineering internships and entry-level developer roles. Even if your site’s code is entirely borrowed from a template, the fact that you forked a repository, customized it, and deployed it through Git shows you can follow a technical workflow — which is exactly what the first few weeks of a software job require.
GitHub itself is also a portfolio platform. Recruiters at tech companies regularly browse a candidate’s GitHub profile before or after looking at their resume. A public repository with clean commit history, a descriptive README, and actual project code is more convincing than a list of projects on a PDF. The GitHub Pages portfolio ties directly into this — your website lives alongside your code, both visible from the same GitHub account, presenting a complete picture of your technical work.
If you’re a non-CS student who still wants to learn Git basics, this tutorial is one of the most practical ways to do it. The Git commands you use to deploy a GitHub Pages site — git add, git commit, git push — are the same three commands used in professional development teams every day. Marketing analysts, data scientists, product managers at tech companies, and UX researchers all benefit from basic Git fluency. The portfolio is the deliverable; the workflow knowledge is the lasting skill.
👉 See also: How to Make a Portfolio Website for Free — comparison of all no-code options.