Project: Publish a Portfolio Website with GitHub Pages

In this project you will publish a real website for free, and turn your GitHub profile into something a recruiter wants to read. If you have followed the HTML course, you already know enough to build the page.

Step 1: Create the project#

mkdir portfolio
cd portfolio
git init -q

Create index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Asha Rao | Developer</title>
    <style>
      body { font-family: system-ui, sans-serif; max-width: 640px; margin: 40px auto; padding: 0 16px; line-height: 1.6; }
    </style>
  </head>
  <body>
    <h1>Asha Rao</h1>
    <p>Student learning web development and data analysis.</p>
    <h2>Projects</h2>
    <ul>
      <li><a href="https://github.com/your-name/notes">Notes app</a>: a small app with search.</li>
    </ul>
  </body>
</html>

Use your own details, and list only real projects. Now add a README.

Step 2: Write a good README#

The README is the first thing people see. It should explain what the project is, show it working, and tell people how to run it.

# Portfolio

My personal website, built with plain HTML and CSS.

**Live site:** https://your-name.github.io/portfolio/

## Run it locally

Open `index.html` in a browser.

## What I learned

- Writing semantic HTML
- Publishing with GitHub Pages

For larger projects, also include a screenshot, the features, the technologies used, and setup steps.

Step 3: Commit in small steps#

git add index.html
git commit -q -m "Add portfolio page"
git add README.md
git commit -q -m "Add README"
git log --oneline

c79c7e9 Add README
3238338 Add portfolio page

Step 4: Push to GitHub#

Create a public repository called portfolio on GitHub, without a README. GitHub Pages is free for public repositories. Then push, as you learned in Pushing a Project to GitHub:

git remote add origin https://github.com/your-name/portfolio.git
git branch -M main
git push -u origin main

Step 5: Turn on GitHub Pages#

1. In the repository, open Settings, then Pages.
2. Under Build and deployment, set Source to Deploy from a branch.
3. Choose branch main, folder / (root), and click Save.

After a minute or two, the page shows your address:

https://your-name.github.io/portfolio/

Each time you push to main, the site updates. index.html must be at the root of the repository.

Step 6: Use your own domain (optional)#

If you own a domain, enter it under Settings, then Pages, then Custom domain. At your domain provider, add a CNAME record pointing www to your-name.github.io. Turn on Enforce HTTPS once it becomes available.

Step 7: Create a profile README#

GitHub shows a special README at the top of your profile page. Create a public repository with exactly your username as its name, and add a README.md:

# Hi, I'm Asha

I'm a student learning web development and data analysis.

- Building: a notes app with search
- Learning: React and SQL
- Portfolio: https://your-name.github.io/

Make your profile look professional#

• Pin your 3 to 6 best repositories on your profile.
• Give each pinned repository a description and a good README.
• Add a live link and a screenshot where you can.
• Use your real name and a clear photo.
• Quality beats quantity. Two finished projects are better than twenty tutorials.

Extend the project#

• Add a custom 404 page named 404.html.
• Add a GitHub Actions workflow that checks your links.
• Build the site with React, and publish it using a Pages workflow.

Key takeaway#

Next: Git interview questions.