Build a Fast Portfolio with Astro and GitHub Pages

A personal portfolio isn’t just a website—it’s your digital handshake with the world.
With Astro, you can build a blazing-fast site that looks professional, and with GitHub Pages, you can host it for free.

This tutorial will walk you through everything: scaffolding, styling, adding projects, and deploying to GitHub Pages. By the end, you’ll have a live portfolio you can share with anyone.

Why choose Astro for your portfolio?

Many people use React, Next.js, or even WordPress for their sites. Astro stands out because:

• ⚡ Performance-first → It ships almost zero JavaScript by default.
• 📄 Content-friendly → Write pages in Markdown or MDX.
• 🎨 Framework-agnostic → Drop in React, Svelte, Vue, or Solid components.
• 🚀 Easy deployment → Works seamlessly with GitHub Pages.

Think of Astro as the static site generator for the modern web—perfect for portfolios, blogs, and landing pages.

Step 1: Scaffold your Astro project

Open your terminal and run:

npm create astro@latest my-portfolio
cd my-portfolio
npm install
npm run dev

👉 This creates a fresh Astro project and runs a local server at http://localhost:4321.

💡 Pro tip: Don’t rename the src/pages folder—Astro uses this convention to generate routes automatically.

Step 2: Set up your portfolio structure

Inside src/pages, create:

• index.astro → Homepage
• about.astro → About you
• projects.astro → Showcase your best work
• contact.astro → Email + social links

Example homepage (index.astro):

---
import Layout from '../layouts/Layout.astro';
---

<Layout title="Home | Muhammad Fiaz">
  <h1 class="text-4xl font-bold">👋 Hi, I’m Muhammad Fiaz</h1>
  <p class="mt-2 text-gray-600">Frontend developer and open-source enthusiast.</p>
  <a href="/projects" class="text-indigo-600 underline">See my projects →</a>
</Layout>

👉 Now if you visit /about or /projects, Astro will auto-generate those routes.

Step 3: Add styling with Tailwind CSS

Astro works with any CSS approach, but Tailwind gives you fast, utility-first styling.

Install Tailwind:

npm install tailwindcss postcss autoprefixer
npx tailwindcss init

Update tailwind.config.cjs and add Tailwind to src/styles/global.css.

Now you can style elements directly:

<h2 class="text-2xl font-bold text-indigo-700">Featured Projects</h2>

💡 Best practice: Keep a components folder for reusable UI pieces like buttons and cards.

Step 4: Showcase your projects

A portfolio is only as strong as the projects you feature.

Create src/pages/projects.astro and add a grid of project cards:

---
import Layout from '../layouts/Layout.astro';
---

<Layout title="Projects | Muhammad Fiaz">
  <h1 class="text-3xl font-bold">Projects</h1>
  <div class="grid grid-cols-1 md:grid-cols-2 gap-6 mt-4">
    <div class="border p-4 rounded-lg shadow">
      <h2 class="font-semibold text-lg">DailyNest</h2>
      <p class="text-gray-600">An open-source publishing platform on GitHub Pages.</p>
      <a href="https://dailynest.github.io" class="text-indigo-600 underline">View project →</a>
    </div>
  </div>
</Layout>

Add screenshots of your work to the public/ folder for extra visual punch.

Step 5: Push your site to GitHub

1. Create a new repo on GitHub.
2. Push your code:

git init
git add .
git commit -m "Initial portfolio commit"
git remote add origin https://github.com/yourname/portfolio.git
git push -u origin main

💡 Pro tip: Add a .gitignore for node_modules/ before pushing.

Step 6: Deploy with GitHub Pages

Astro provides a GitHub Action for one-click deployment.

Create .github/workflows/deploy.yml:

name: Deploy Astro site to GitHub Pages
on:
  push:
    branches: ["main"]
jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: withastro/action@v1
        with:
          path: .
          node-version: 20
          deploy: true

Push again. Then in your repo: Settings → Pages → Branch: gh-pages

✅ Your portfolio will be live at: https://yourname.github.io/portfolio

Step 7: Extra polish

Now that your site is live, make it stand out:

• 📝 Add a blog section using Markdown files.
• 🔎 Improve SEO with <head> tags.
• 📈 Add analytics (Umami or Google Analytics).
• 📱 Test responsiveness on mobile.
• 🎨 Add a dark mode toggle for style points.

Final thoughts

Astro + GitHub Pages gives you:

• 🚀 Speed that impresses recruiters and clients.
• 💸 Free hosting with no hidden costs.
• 🛠️ Simple workflow with GitHub Actions.

Your portfolio isn’t a one-time project—it’s a living resume. Keep updating it with new skills, case studies, and blog posts.

👉 Start small today, and you’ll have a polished, fast, and professional site now.