I did not rebuild my portfolio with Astro because I needed another JavaScript framework. I chose it because the site mostly needed to present information well: projects, experience, case studies, an about page, and a blog.
Most of that content does not need to become a client-side application after the page loads. It needs to be fast, easy to maintain, and structured well enough that adding a project does not mean rebuilding the same card by hand in several places.
That made Astro a much better fit than I first understood.
The portfolio did not need to behave like an app
My first useful decision was accepting that the portfolio is a content site. There are interactive details, but the main job of every page is still to explain what I worked on.
Astro lets me render that content as normal HTML and add browser-side JavaScript only where it has an actual purpose. The cursor trail and project inquiry message need scripts. A project description does not.
That separation keeps the site lighter and also makes the code easier to reason about. I do not have to think about client state just to render a list of technologies or a case-study section.
I separated the content from the page layouts
The most useful part of the current structure is that project and experience content lives in TypeScript data files instead of being copied directly into the page markup.
Each project has the same basic shape:
- title and description
- role, year, and project type
- technologies
- image
- relevant links
The Projects page maps over that data and handles the presentation. Case studies work in a similar way: one dynamic Astro route reads a case-study object and builds the correct page for Skill Arena, DxD, Potato, or anything I add later.
This matters more to me than saving a few lines of code. It keeps the wording, metadata, links, and visual hierarchy consistent. If I change how a project card works, every project receives the same improvement.
Content collections made the blog predictable
Blog posts live as Markdown files inside an Astro content collection. A small schema checks that every post has the fields the site expects, such as a title, description, publication date, and tags.
From there, Astro handles the repetitive parts:
- generating a route for every post
- sorting posts by publication date
- rendering Markdown through the same article layout
- creating page metadata from the post data
- including posts in the sitemap
Writing in Markdown is convenient, but the real benefit is predictability. The article page does not need to know which post it is rendering. It only needs valid content.
The difficult part was consistency, not setup
Creating an Astro page is easy. Making every type of content feel like part of the same site took more work.
Markdown brings its own headings, lists, links, quotes, code blocks, and images. I had to style all of those states instead of only designing the blog index. Projects and case studies needed shared panels, buttons, metadata rows, technology chips, responsive spacing, and focus states.
SEO also required deliberate work. The site now builds canonical links, Open Graph data, structured data, a sitemap, and article-specific metadata from the same content used on the page. Astro provides the pieces, but it does not decide what a project page should say about itself.
That was a useful lesson: choosing a static-site framework removes unnecessary runtime work, but it does not replace a content model or a design system.
What I would do differently now
If I started the portfolio again, I would define the shared content shapes and design tokens earlier.
The first version grew one page at a time. That worked, but it meant I later had to standardize buttons, cards, borders, colors, spacing, project metadata, and article typography. The current structure is much cleaner because those decisions now live in shared components and global UI styles.
I would also write project descriptions with the case study in mind from the beginning. It is much easier to expand a project when I already know its problem, my contribution, the systems I built, and the result.
Why I still use Astro for this site
Astro fits this portfolio because it stays out of the way. It gives me reusable layouts, typed content, dynamic routes, optimized images, and small interactive scripts without forcing the whole site to run as an application.
More importantly, it lets the content remain the main thing. The portfolio can grow with more projects and articles while the underlying structure stays simple enough that I can still understand and change it myself.
That is the part I value most now. Astro did not make the portfolio good automatically. It gave me a clean foundation where the writing, project details, and design decisions can do their jobs without unnecessary complexity around them.