From zero to a live portfolio, listed here

Part 1 · Publish your portfolio on GitHub Pages

GitHub Pages hosts static websites straight from a repository, for free, with HTTPS. Everything in the gallery runs on it.

1. Pick a starting point

   Browse the gallery and open the source of a design you like. Check the repository's license before reusing it, and keep the credit the author asks for. You can also start from a single index.html.

2. Create your repository

   On the template's GitHub page click Use this template → Create a new repository, or Fork if there is no template button. The repository name decides the address:

   Repository name	Your site's URL
   <username>.github.io	https://<username>.github.io/
   anything else, e.g. portfolio	https://<username>.github.io/portfolio/

   Each account gets one <username>.github.io site and as many project sites as it likes. The repository must be public on a free plan.

3. Make it yours

   Replace the template's content with yours: name, bio, projects, links, photo. Most templates keep this in one file (config.js, _config.yml, data.json…), so read their README first.

   You can edit on GitHub directly (press . in the repository to open the web editor) or locally. Templates with a build step usually run with npm install then npm run dev.

4. Turn on GitHub Pages

   In your repository open Settings → Pages and under Build and deployment → Source choose:

   • Deploy from a branch for plain HTML/CSS/JS or Jekyll sites. Pick your branch (usually main) and the / (root) or /docs folder.
   • GitHub Actions for sites that need a build step (React, Vue, Astro, Next.js, Hugo…). GitHub suggests ready-made workflows for popular frameworks.

   A minute or two later the address of your site shows at the top of the Pages settings. GitHub docs

   Using a framework on a project site? Set its base path to /<repository>/ (base in Vite and Astro, basePath in Next.js), otherwise styles and scripts will not load.

5. Use your own domain optional

   Enter it in Settings → Pages → Custom domain, then add DNS records at your domain registrar:

   • Subdomain such as www.example.com: a CNAME record pointing to <username>.github.io.
   • Apex domain such as example.com: four A records pointing to 185.199.108.153, 185.199.109.153, 185.199.110.153 and 185.199.111.153.

   When the certificate is ready, tick Enforce HTTPS. GitHub docs

6. Final checks

   • It opens over https:// and looks right on a phone.
   • No leftover template text, placeholder names or broken links.
   • The page has a <title> and a meta description, so it previews well when shared.

Part 2 · Add it to this list

The list is generated from data: each portfolio is one small YAML file in data/portfolios/. You never edit the README. After your pull request is merged, automation regenerates it and redeploys this site.

name: Jane Doe
repo: janedoe/janedoe.github.io
demo: https://janedoe.github.io/
# optional
description: Minimal dark portfolio built with Astro.
tags: [astro, minimal, dark]

Option A · In your browser, no git needed

1. Open the pre-filled entry file . GitHub forks the repository for you if needed.
2. Rename your-name.yml to something unique, e.g. jane-doe.yml (lowercase, dashes).
3. Replace the placeholder values with yours.
4. Click Commit changes… → Propose changes → Create pull request.

Option B · From the command line

Fork the repository, then:

git clone https://github.com/<you>/awesome-github-pages-portfolios.git
cd awesome-github-pages-portfolios
npm install
npm run new        # asks a few questions and writes your file
npm run validate   # runs the same checks as CI
git switch -c add-jane-doe
git add data/portfolios/jane-doe.yml
git commit -m "Add Jane Doe's portfolio"
git push -u origin add-jane-doe

Then open a pull request from your fork.

The fields

Editors with the YAML extension autocomplete and check these fields thanks to the JSON schema.

What happens next

1. Automatic checks run on your pull request: format, duplicates, the site is online, the repository exists. Any problem is shown next to the exact line in the Files changed tab.
2. A maintainer reviews and merges. Please keep to one portfolio per pull request.
3. Automation takes over: the README is regenerated, a screenshot of your site is taken and the gallery is redeployed, usually within five minutes.

FAQ