Portfolio

The Predecessors

To start off, I wanted these baseline features in my website:

1. A blog. Somewhere I could write about my thoughts and whatever new JS frontend framework was being released this month.
2. Project showcase. A place to review some of the sites that I was the proudest of.
3. About. A summary of my character.
4. A contact page. Not really sure how I would implement this but perhaps it could be a few external profile links like Twitter, LinkedIn, etc…

This site is not the first edition that came about. I had already built multiple webapps with React + Vite and was well-settled into it, thus I immediately jumped into using it for my portfolio site. Regrettably, this ended up backfiring pretty badly as I didn’t consider some of the issues with building a portfolio as a SPA.

Some of these things were:

1. Blog population - how was I going to write my blog posts? I did not wish to type HTML or create components for everything!
2. Do I really need so much JS interactivity for a simple portfolio website?
3. Writing the entire site in Vite proved a little too barebones. I needed something that would be robust and help me develop quickly - not force me to develop my own workflow pipeline.

Overall, not the best-planned project…

So I went to do some research. Eventually, I came across MDX ; an upgraded form of Markdown, which allows you to use components from libraries/frameworks like Vue, React and Astro directly in your markdown content. This seemed incredibly fitting for me as I wanted a way to quickly write content but also give myself some freedom to create custom components.

I explored frameworks that supported MDX and landed on Astro. As luck would have it, 3.0 had recently released and I had heard a lot of exciting prospects about it. Here’s what it looked like:

It was certainly an improvement, but there were a number of problems. The code itself was super buggy because I had zero clue of what I was doing in the framework. I couldn’t get many things to work and managing Tailwind’s typography styles was a complete mess. Moreover, I actually disliked the website’s aesthetic; I thought it was too amateur-y and didn’t feel genuine enough. Combined with the inevitable piles of other schoolwork projects, I eventually lost motivation and ultimately abandoned it.

An Upgrade

Fast forward a few years, and I was ready to start building it again. There was a major design overhaul, coupled with the fact that I actually built a prototype in Figma instead of winging it. This site was built with the following tools:

1. Astro. This time, I was ready to take the time to understand the inner workings of the framework and would attempt to utilise it to its fullest potential.
2. TailwindCSS. Although I faced problems down the road for reasons explained later, I found Tailwind to be very fitting and Astro had already shown that they had immense first-class support for it, so I saw no reason to not take advantage of that.
3. Cloudflare. This project is deployed on Cloudflare Pages.
4. React. Astro’s ‘islands’ architecture would support React interchangeably. I saw an opportunity to use this.

Using Tailwind

Tailwind had already proven itself to be a great boon in my previous projects, making it enjoyable to style HTML. In this project, however, things change when it comes to markdown.

class:list={[
    // non-tailwind classes left for brevity
    "prose",
    "prose-h1:text-white prose-h1:text-5xl",
    "prose-h2:text-primary prose-h2:text-4xl",
    "prose-h3:text-primary prose-h3:text-xl prose-h3:font-bold prose-h3:tracking-widest prose-h3:mt-12",
    "prose-li:text-white prose-li:text-lg prose-li:font-body",
    "prose-strong:text-white prose-em:text-white",
    "prose-code:text-white prose-code:font-display prose-code:before:content-[''] prose-code:after:content-['']",
    "prose-figcaption:place-self-center prose-figcaption:font-body",
    "prose-headings:scroll-mt-32 prose-headings:relative",
    "prose-code:[&:not(pre_code)]:bg-white"
    // ...
]}

@reference "tailwindcss";

#alert {
  &[data-type="info"] pre {
    @apply bg-slate-900/80 border-l-2 border-l-blue-500;
  }
}

<aside id="alert" data-type="info" class:list={[
  "bg-blue-950/40 border-l-4 border-l-blue-300/60",
  "data-[type='info']:[pre]:bg-slate-900/80",
  "data-[type='info']:[pre]:border-l-2",
  "data-[type='info']:[pre]:border-l-blue-500",
]}>

#alert {
  &[data-type="info"] pre {
    background-color: --alpha(var(--color-slate-900) / 80%);
    border-style: var(--tw-border-style);
    border-width: 2px;
    border-left-color: var(--color-blue-500);
  }
}

Content Collections

The one core Astro feature that populates my website is content collections. They’re essentially just a set of data, like JSON files or entire blog posts, stored locally on the project.

Normally, how you’d define a collection goes as follows:

const projects = defineCollection({
  loader: glob({
    pattern: "**/*.{md,mdx}",
    base: "./src/content/projects",
  }),
  schema: z.object({
    name: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    githubUrl: z.string().optional(),
    url: z.string().optional(),
    draft: z.boolean().optional().default(false),
    tags: z.array(reference("tags")).optional(),
    related: z.array(reference("projects")).optional(),
  }),
});

defineCollection needs 2 props - loader & schema. loader specifies how Astro parses your media, with glob being file path matching, and file, which loads JSON files via an exact path.

schema is how you format your markdown. Astro uses Zod internally for you to streamline the creation of your frontmatter schema and provide generated Typescript types in the project. Pretty neat!

To demonstrate how the schema works, the frontmatter for this project looks like this:

---
name: "Portfolio"
description: "This website you're viewing right now :)"
pubDate: "2025-06-01"
draft: false
tags:
    - "typescript"
    - "astro"
    - "tailwindcss"
    - "cloudflare"
---

Astro verifies the structure of the frontmatter props on every page load. For example, if name was omitted, Astro would complain and throw an error, and fail to render the markdown file.

As you’ve seen above, there are a quite a number of data types that are available for use in the schema. However, there is a special type created by Astro that’s not natively in Zod - reference. It essentially allows you to refer to another collection entry via its slug. A collection can even reference itself!

For instance, the projects collection references the tags and projects collections:

const projects = defineCollection({
4 collapsed lines
  loader: glob({
    pattern: "**/*.{md,mdx}",
    base: "./src/content/projects",
  }),
  schema: z.object({
    name: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    githubUrl: z.string().optional(),
    url: z.string().optional(),
    draft: z.boolean().optional().default(false),
    tags: z.array(reference("tags")).optional(),
    related: z.array(reference("projects")).optional(),
  }),
});

This is the way that it had been working for a while now. But a peculiar issue came up one day when I added those 2 types and ran the project:

Cannot destructure property 'type' of 'lookupMap[collection]' as it is undefined

This was odd to me. I was sure that I had typed the schema correctly, as per the docs . So why wasn’t it working?

Turns out, it was a bug on Astro’s side. The GitHub issue itself has since been fixed and closed, but essentially, a race condition would occur where Astro would try to assign the record to a collection without the collection actually existing in the first place. This mismatch causes the project to stop building and fail. This was a very frustrating error as it was difficult to pinpoint exactly how it went wrong. It took a lot of research and time for it to get fixed!

In the meantime, I did discover a workaround involving the .astro folder. This is what it looks like, with other files omitted for brevity:

The collections folder is where Astro stores the parsed content schemas. I suspected the problem was the definitions themselves, so I deleted the folder and regenerated it, which actually fixed the problem. Not the best solution, but it allowed me to work on other things in the project.

Creating the layout

If you inspect this page with dev tools, you’ll see that I use CSS grid. Initially, I used flexbox to create the layout for the page, but it just didn’t feel right.

I’ve prepared a rough demo below. If you’re on mobile, you may have to switch to a bigger device to see the full layout. Adjust the slider to change the width of the viewport:

So, how was this accomplished?

On mobile devices, there is only 1 column in the diagram, holding only the article content. But as we increase the viewport size, we gradually add more columns to the container. ToCs (Table-of-Contents) are not space-efficient on smaller screens, so we remove that functionality entirely. Once we pass the xs threshold, we add back the ToC column!

When we have a big enough viewport, we don’t want the content to reach the ends of the screen. This can make reading feel clunky and difficult to digest, as the content is spread over a large area. To prevent this, we have to introduce some sort of padding on the horizontal axis of the page. We have two solutions: either use padding, or grid columns. We’ll pick the latter option, for reasons I’ll explain soon.

To add padding, we insert divs at both ends that are 1fr in width at the sm threshold, while the middle two have their own fixed width. 1fr is a grid-exclusive unit that simply means; “occupy the remaining space”.

We can achieve all these through the use of grid-template-columns:

#container {
  display: grid;
  grid-template-columns: 1fr 24rem 12rem 1fr;
}

<div
  id="container"
  class:list={[
    "grid-cols-1",
    "@xs:grid-cols-[3fr_1fr]",
    "@md:grid-cols-[1fr_16rem_8rem_1fr]",
    "@[39rem]:grid-cols-[1fr_24rem_12rem_1fr]",
    "justify-center relative gap-2"
  ]}
>
</div>

So why exactly did we choose these boxes over using the reliable padding property? It’s kind of a personal preference. Let’s consider how our layout stretches/shrinks with padding implemented:

As you can see, it’s quite similar. Our content still conforms to the viewport as we originally want. But obviously the glaring difference is the padding’s lack of care for the viewport, stretching past it. While this doesn’t really matter much as these empty divs don’t contain anything, I still find it a little unrefined in its implementation, hence I prefer using fr.

Interactive sections

You may be wondering how components like the filetree and grid layout example exist. After all, aren’t I just using markdown to write these pages? Well, thanks to the combined power of Astro, React, & MDX, this is possible and it’s so cool to be able to create these mini interactable sections while still writing plain text.

<HelloWorld client:load />

Hosting

I’m glad I haven’t found a need to opt for full SSR on Astro yet. With islands, this is essentially isn’t an issue, and I’m able to deploy on Cloudflare Pages for free!. The workflow was pretty easy, to be honest - just connect Cloudflare Pages to a repo and wait for it to finish building. I had already set up a CNAME record prior to this, so I could just use it straight away. The whole process took something like 10 minutes.

Originally, I bought my domain on Namecheap. It was relatively inexpensive; I pay 15 SGD a year for it. I’ve since moved it to Cloudflare as it’ll be easier to work with in the future.

Closing words

I’ve come a long way since writing my first line of Java code in my polytechnic years. This portfolio website is only the beginning to my journey as a software developer! There’ll be many ups and downs along the way, but they’ll all be learning experiences :)