Stop 18 · DeploymentTopics · 4/9

GitHub Pages

In short

GitHub Pages is the easiest free way to put a portfolio online. Your code already lives on GitHub, so the site can live right next to it.

GitHub's free static site hosting, serving files directly from a repository — simple, but limited to fully static output with no server-side rendering.

The jaadu pins a colourful sheet to a college notice board as students look on.

Think of it like this

The college notice board

You pin a printed sheet and everyone can read it. You can't run anything on the board, it only shows what you pinned. GitHub Pages is the same: it serves ready-made HTML, CSS and JS, with no server code.

Watch it happen

Why the base path matters

Browser

GitHub Pages

GET /portfolio/

1/6A visitor opens username.github.io/portfolio/.

The big ideas

What you need to know

User and project sites

A repo named username.github.io is served at the root. Other repos are served at username.github.io/repo-name/.

Static files only

No server-side rendering, no API routes, no database. Only files you built beforehand.

Deploy with Actions

A GitHub Actions workflow can build your app and publish the output on every push.

Base path matters

Project sites live under /repo-name/, so your build tool must know that prefix for assets to load.

See it in code

Walk through the code

1// vite.config.ts for https://username.github.io/portfolio/2import { defineConfig } from "vite";3import react from "@vitejs/plugin-react";4 5export default defineConfig({6  plugins: [react()],7  base: "/portfolio/",8});

1/3Your site will live under /portfolio/, not the domain root.

Without base, the built HTML asks for /assets/index.js from the domain root, which doesn't exist on a project site. Result: a blank white page.

Save yourself the pain

Common mistakes

Oops

Getting a blank page after deploy and blaming React.

Do this instead

Open DevTools, Network tab. If JS files show 404, set the base path to your repo name and rebuild.

Oops

Expecting a Next.js app with API routes to work on GitHub Pages.

Do this instead

Use static export for fully static Next.js sites, or pick a host like Vercel when you need server code.

Your mission

Publish your portfolio for free

~30 min

Quick check

Your project site at username.github.io/todo/ loads a blank page and the JS file shows 404. What's the likely fix?

Go deeper

1Deploy a static portfolio site directly from a GitHub repo.
2Learn how to configure a custom domain for a GitHub Pages site.
3Understand its limitation: it only serves pre-built static files, no SSR.