Introduction

This guide is a written and extended version of the workshop I wrote for WebLabs, a student organization run by some of my friends at the University of Wisconsin-Madison.

Have you ever wanted your own website, but been put off by the limited customization options (and monthly prices) of Carrd, Wix, or Squarespace? Or maybe you've tried to set up a blog using WordPress, but found it too complicated? It's one thing to learn basic HTML/CSS, but another thing entirely to actually deploy your work somewhere where people can see it. This workshop will help you build your own portfolio (and blog) using Astro, GitHub, and Markdown, assuming that you've only worked with bare HTML/CSS and a bit of JS so far. You won't need anything besides a GitHub account and a browser to get started.

This guide is meant to be a starting point for you to build your own portfolio website and host it for free. By "your own portfolio," I mean a site that you can customize and make your own. You can add your own images, change the layout and colors, and add any pages you like. The goal is to give you the tools and knowledge to create a website that reflects your personal style and interests.

Why Even Bother?

Whether you're trying to land your first internship, link out from your socials, or just improve your skills, having a personal website that you own is incredibly valuable when everyone else is on centralized social platforms. Things like Carrd are fine, but they're limited and cost money if you want to customize them.
Beyond practical considerations, you learn a lot more by shipping stuff, rather than just reading about it or using it for homework. This guide will take you through a handful of free programs and websites that are used every day by developers in the real world, and will be invaluable for your growth as a developer. You can throw it on LinkedIn, your resume, your email signature, your cat's collar...

What You'll Need

• A GitHub account
• A browser
• ~1 hour (less if you type fast)

Outline

1. First, we'll develop the basic website design with CodePen.
2. Next, we'll set up the GitHub repository to host our portfolio.
3. Then, we'll port the CodePen code to Astro and add images.
4. After that, we'll deploy the site to GitHub Pages, which is free and easy to use.
5. Then we'll drop into GitHub Codespaces to add a blog to our portfolio using Astro's content collections.
6. Finally, I'll suggest some ways to improve your portfolio and blog, and give you some resources to learn more about Astro and web development in general.

Step 1: Mess Around on CodePen

go.weblabs.club/portfolio-js

Get a feel for how your portfolio might look:

• Don't worry about images yet.
• In the HTML panel, fill in your name, bio, links, skills, projects.
• Use the CSS variables to change colors and fonts, if you like.
• Once you're happy with it, we'll move onto the next step.

Step 2: Clone the GitHub Template

go.weblabs.club/portfolio-github

This template repository is essentially what you get by running npm create astro@latest and selecting the basic template, but I ripped out the parts that are unnecessary for this workshop. It doesn't include anything besides the bare minimum configuration, we'll be adding everything else as we go.

1. Sign in to GitHub.
2. Use the template to make a repo named ${your-username}.github.io.

This is where your site will live. Beyond storing code, GitHub offers several other useful services like GitHub Pages, GitHub Actions, and GitHub Codespaces. In this case, GitHub Pages will host your site at that URL later.

Step 3: CodePen, meet Astro

Astro is static site builder with zero JS by default, unless you opt in. It's perfect for beginners that want a little extra sauce out of their HTML. You'll get components (like React) but no runtime overhead, and you can do cool things like Markdown-based blogs without needing a CMS.

<!-- Example -->
---
import Layout from '../layouts/Layout.astro';
---

<Layout>
  <!-- Your HTML here -->
</Layout>

<style is:global>
  /* Your CSS here */
</style>

Step 4: Add Images

Let's add some photos while we're here. You can do this from the GitHub web interface as well.

• Upload your image files to /public.
• Refer to them like:

  <img src="/myimage.png" />

  No public/ prefix, just the slash.

Step 5: Add Blog with Content Collections

This part would have been a live demo in the in-person workshop, so it's a little more informal, and there unfortunately are no template repos for you to copy. Now that we've got a wonderful portfolio site with all our projects and images, let's add a blog to it. This is a great way to show off your skills and share resources (like this workshop) with the world.

Astro's content collections allow you to create a blog with Markdown files. You can write your posts in (effectively) plain text, and Astro will take care of the rest. We'll also be using something called "frontmatter" to add metadata to your posts, like the title, date, and image.

import { defineCollection, z } from 'astro:content';

const blogCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    date: z.date(),
    excerpt: z.string(),
    image: z.string().optional(),
  }),
});

export const collections = {
  'blog': blogCollection,
};

---
title: "First Blog Post"
date: 2025-04-16
excerpt: "A quick dive into making your first blog post in Astro."
---

Here's your actual blog content. Markdown works here!

---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog');
const sortedPosts = posts.sort((a, b) => b.data.date.getTime() - a.data.date.getTime()); // sorts by date, if you like
---

<section id="blog" class="blog">
  <div class="container">
    <h2>Blog</h2>
    <p>Thoughts, tutorials, and insights</p>
    <div class="blog-grid">
      {sortedPosts.map(post => (
        <div class="blog-card">
          <div class="blog-date">
            {post.data.date.toLocaleDateString('en-US')}
          </div>
          <h3>{post.data.title}</h3>
          <p>{post.data.excerpt}</p>
          <a href={`/blog/${post.slug}`}>Read More <i class="fa-solid fa-arrow-right"></i></a>
        </div>
      ))}
    </div>
  </div>
</section>

---
import { getCollection } from 'astro:content';
import Layout from '../../layouts/Layout.astro';

// Generate paths for all blog posts
export async function getStaticPaths() {
  const blogEntries = await getCollection('blog');
  return blogEntries.map(entry => ({
    params: { slug: entry.slug },
    props: { entry },
  }));
}

// Get the blog post content
const { entry } = Astro.props;
// Markdown is text, so we need to "render" it to transform it into HTML
const { Content } = await entry.render();
---

<Layout>
  <article class="blog-post container">
    <h1>{entry.data.title}</h1>
    <time datetime={entry.data.date.toISOString()}>
      {entry.data.date.toLocaleDateString('en-US', {
        year: 'numeric', month: 'long', day: 'numeric'
      })}
    </time>
    <div class="blog-content">
      <Content />
    </div>
    <a href="/#blog">← Back to Blog</a>
  </article>
</Layout>

You're Done (But You Should Totally Keep Going)

This is a great start, but there's so much more you can do with Astro. Here are some ideas and links to get you started:

• The blog post page is... lightly themed, to say the least. You could totally spruce it up a bit.
• Maybe you don't want all your posts on the home page. You can add another page that just lists your blog posts!
• Tailwind is a common way to add some styling to sites in a more terse form than straight CSS. You can add Tailwind to Astro in just a few minutes, and it makes it super easy to add responsive styles and custom themes.
• If you want to add reactivity, you can add frontend frameworks like React and Svelte to Astro with just a few commands. Astro is designed to work with these frameworks, so you can use them to build interactive components without needing to set up a whole React or Svelte app. You can also use MDX to write your blog posts in Markdown and include React components inside them.
• You could set up Giscus for a free commenting system on your blog posts. You can see an example of it on this very page! Giscus is a free, open-source commenting system that uses GitHub Discussions to store comments. It's a great way to add comments to your blog posts without needing to set up a whole backend or database. You can also use it to get feedback on your posts and engage with your readers.
• Having the username.github.io URL is a bit lame. You can set up a custom domain, but you'll have to pay for one. They're usually less than $15/year, though, so it's worth it if you want to continue doing things on the web. tld-list.com is a good way to search for domains that aren't already registered!
• If you use Discord, you might consider setting up my Discord GitHub Preview project :). It'll show your Discord activity in an SVG that you can place in an <img> tag. This is a great way to show off your activity and make your site more dynamic.
• If you plan to post a lot on your blog, you might set up an RSS feed so people can subscribe to it. This is a great way to keep your readers updated on your latest posts, and it's a good way to learn about RSS feeds and XML. Astro also makes this dead simple.