How to Build a Portfolio Website Using HTML, CSS, and GitHub Pages

Published On - September 27, 2025

ivan Blogging

In today’s digital age, having a personal portfolio website is a powerful way to showcase your skills, projects, and experiences to the world. Whether you’re a web developer, graphic designer, writer, or any creative professional, your online presence speaks volumes. This article will walk you through the process of building a clean and effective portfolio website using only HTML, CSS, and GitHub Pages. Best of all, it’s free!

Why Build a Portfolio Website?

Before diving into the how-to, it’s worth exploring the why. A portfolio website not only showcases your talents but also demonstrates your initiative and commitment to your craft. It’s often the first impression you make on recruiters, clients, and collaborators.

Here are some key benefits:

  • Professional Visibility: It gives you a dedicated space to present your work.
  • Control Over Your Brand: You decide how you’re represented online.
  • Accessibility: Anyone with your URL can see your work anytime—from anywhere.

What You’ll Need

To get started, you’ll need just a few tools and resources:

  • A text editor like VS Code, Sublime, or Atom
  • A GitHub account (sign up at GitHub)
  • Basic understanding of HTML and CSS

Step 1: Plan Your Website

Before writing any code, take some time to plan your site. Decide on the core pages you’ll need. For a basic portfolio, these typically include:

  • Home: A brief introduction and call to action
  • About: Who you are and what you do
  • Projects: A gallery or list of your best work
  • Contact: A way for visitors to reach you

Sketch the layout on paper or a design tool. Think about colors, typography, and overall user experience.

portfolio wireframe sketch layout

Step 2: Write the HTML

Now let’s build the structure of your website using HTML. Create a new folder on your computer for your project. Inside, create a file named index.html. This will be your homepage.

Here’s a simple HTML boilerplate to get you started:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Portfolio</title>
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <header>
      <h1>John Doe</h1>
      <nav>
        <a href="#about">About</a>
        <a href="#projects">Projects</a>
        <a href="#contact">Contact</a>
      </nav>
    </header>

    <section id="about">
      <h2>About Me</h2>
      <p>Short bio goes here.</p>
    </section>

    <section id="projects">
      <h2>My Projects</h2>
      <!-- Add your project details here -->
    </section>

    <section id="contact">
      <h2>Contact Me</h2>
      <p>Email: your.email@example.com</p>
    </section>

    <footer>
      <p>© 2024 John Doe</p>
    </footer>
  </body>
</html>

Step 3: Style with CSS

Now that the structure is in place, let’s bring your site to life visually using CSS. Create a file named style.css in the same folder and link it to your HTML as shown above.

Here are a few CSS basics you might start with:

body {
  font-family: Arial, sans-serif;
  margin: 0;
  padding: 0;
  background-color: #f4f4f4;
  color: #333;
}

header {
  background: #333;
  color: #fff;
  padding: 20px;
  text-align: center;
}

nav a {
  margin: 0 15px;
  color: #fff;
  text-decoration: none;
}

Styling is where your creativity shines. Explore Google Fonts, CSS grid, and media queries for responsive design.

Step 4: Add Your Projects

Your projects section is the heart of your portfolio. Include details like:

  • Title of the project
  • Description
  • Tools used or technologies involved
  • Live link and/or GitHub repo link

Here’s a simple example:

<div class="project">
  <h3>Weather App</h3>
  <p>A web app that shows real-time weather for any city.</p>
  <p>Built with HTML, CSS, and JavaScript.</p>
  <a href="https://github.com/username/weather-app">View on GitHub</a>
</div>

weather app interface web screenshot

Step 5: Push Your Code to GitHub

Once your site is ready, it’s time to publish it! GitHub Pages lets you host websites directly from a GitHub repository.

Follow these steps:

  1. Create a new repository on GitHub. Name it something like portfolio.
  2. Initialize it with a README file (optional).
  3. On your computer’s terminal or command prompt:
    • Navigate to your project folder
    • Run the following commands:
    git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/portfolio.git
git push -u origin master

Step 6: Deploy with GitHub Pages

Now that your code is on GitHub, you can deploy your site using GitHub Pages:

  • Go to your repository on GitHub
  • Click on Settings > Pages
  • Under Source, select main branch
  • Click Save

After a few seconds, your site will be live at https://yourusername.github.io/portfolio. Share this URL with potential employers, add it to your resume, and post it on LinkedIn!

Bonus Tips

Want to take your portfolio to the next level? Consider the following enhancements:

  • Responsive Design: Use media queries to make your site look great on mobile devices
  • Animations: Add subtle animations using CSS transitions or libraries like Animate.css
  • Custom Domain: You can even add a custom domain name for a more professional look

Common Mistakes to Avoid

While building your portfolio can be exciting, be aware of common pitfalls:

  • Too Much Flash: Avoid overuse of animations or heavy graphics
  • Missing Contact Info: Always include a way for visitors to reach you
  • Poor Mobile Experience: Test your site on phones and tablets

Wrapping Up

Building a portfolio website