This Portfolio Website

Table of Contents

1. Overview
2. Role
3. The Problem
4. The Goal
5. The Solution
   • Technology Stack Selection
   • Content Management Strategy
   • Component Architecture
   • Visual Enhancements
6. Technical Implementation
7. Lessons Learned
   • What Went Well
   • What Could Be Improved
   • Key Takeaways

Overview

This portfolio website serves as a comprehensive showcase of my professional experience, technical projects, and skill set. Built with modern web technologies, it demonstrates practical application of static site generation, component-based architecture, and content-driven design principles.

The site was developed to provide a clean, performant, and easily maintainable platform for presenting my work to potential employers, collaborators, and the broader developer community.

Role

As the sole developer and designer of this project, I was responsible for all aspects of the site’s creation, including:

• Technology selection and architectural decisions
• UI/UX design and responsive layout implementation
• Content structure and organization
• Component development and integration
• Deployment and hosting configuration

The Problem

Before creating this portfolio, I faced several challenges in presenting my professional work:

1. Scattered Information: My work experience, projects, and skills were spread across various platforms (LinkedIn, GitHub, resume documents) without a unified presentation
2. Limited Customization: Existing portfolio templates were either too complex, too rigid, or didn’t align with my technical preferences
3. Content Updates: Traditional static sites made it difficult to add new projects or update existing information without editing HTML directly
4. Technical Showcase: I needed a platform that not only displayed my work but also demonstrated my technical capabilities through the site itself
5. Visual Communication: Complex technical projects needed better visualization tools (like diagrams) to effectively communicate architecture and workflows

The Goal

Create a modern, professional portfolio website that:

• Provides a single source of truth for my professional information
• Uses technologies I’m learning at work (Astro) to deepen my knowledge
• Supports easy content updates through markdown-based content management
• Demonstrates technical proficiency through the site’s architecture and implementation
• Delivers excellent performance with fast load times and smooth interactions
• Enables rich content including code snippets, diagrams, and interactive elements
• Maintains clean, professional design that puts content first

The Solution

Technology Stack Selection

Astro Framework At RSM, we had begun using Astro for some internal documentation projects, and I was intrigued by its islands architecture and performance-first philosophy. Astro’s ability to ship zero JavaScript by default while still supporting interactive components when needed made it ideal for a content-focused portfolio.

React for Interactivity For components requiring interactivity (tabs, navigation, dynamic content), I integrated React. Astro’s ability to selectively hydrate React components meant I could use the familiar React patterns I know from work while maintaining excellent performance.

TypeScript Type safety throughout the project reduces bugs and improves developer experience, especially when working with complex data structures for jobs, projects, and skills.

Tailwind CSS + shadcn/ui Tailwind’s utility-first approach paired with shadcn/ui’s beautiful component primitives provided the perfect balance of customization and consistency. The components.json configuration allowed me to maintain a cohesive design system.

Content Management Strategy

MDX for Project Pages Each project is a separate .mdx file in src/content/projects/, combining the simplicity of Markdown with the power of React components. This approach allows me to:

• Write content naturally in Markdown
• Embed interactive components where needed
• Include diagrams directly in content
• Maintain consistent frontmatter metadata

Structured Data Files Core data like work experience (Jobs.tsx), education, and skills are maintained as TypeScript files with strongly-typed interfaces. This provides:

• IntelliSense and autocomplete while editing
• Type checking to prevent errors
• Easy programmatic access for rendering components
• Clear documentation through TypeScript interfaces

Component Architecture

The site is built with a clear separation of concerns:

Layout Components

• Navbar.astro: Responsive navigation with mobile support
• Footer.astro: Consistent footer across all pages
• Layout components that provide consistent page structure

Content Components

• ProjectCard.astro: Displays project summaries with tags and dates
• JobDetails.astro: Renders detailed work experience entries
• SkillCard.astro: Showcases technical skills and proficiencies
• ProfileInfo.astro: About section with profile details

Interactive Components

• TabsButtons.tsx: React-based tab navigation for organizing content
• BackToTop.astro: Smooth scroll-to-top functionality

Visual Enhancements

D2 Diagram Integration Added astro-d2 integration to render D2 diagrams directly from MDX content. This enables creation of architecture diagrams, system flows, and technical visualizations using a simple declarative syntax. Perfect for documenting complex projects like the RSM integrations.

Mermaid Diagram Support Integrated astro-mermaid for additional diagramming capabilities with auto-theming support, providing flexibility in visual communication.

Syntax Highlighting Configured Shiki with the ‘plastic’ theme for beautiful code syntax highlighting in code blocks, making technical examples easy to read and understand.

Iconography Leveraged astro-icon with multiple icon sets (Hugeicons, Streamline) for consistent, scalable icons throughout the interface.

Technical Implementation

Project Structure

src/
├── content/
│   ├── projects/          # MDX files for each project
│   └── config.ts          # Content collections configuration
├── data/
│   └── Jobs.tsx           # Structured work experience data
├── components/
│   ├── *.astro            # Static Astro components
│   └── *.tsx              # Interactive React components
├── layouts/               # Page layout templates
├── pages/                 # Route definitions
└── styles/                # Global styles

Content Collections

Astro’s content collections provide type-safe content management:

// Automatic type generation from frontmatter
const projects = await getCollection('projects');

Responsive Design

Mobile-first approach using Tailwind’s responsive utilities ensures the site works seamlessly across all device sizes.

Performance Optimization

• Static site generation for fast load times
• Selective hydration of interactive components
• Optimized images and assets
• Minimal JavaScript payload

Deployment

Configured for easy deployment with:

• Dockerfile for containerized hosting
• nginx configuration for production serving
• Sitemap generation for SEO
• OG images for social sharing

Lessons Learned

What Went Well

Astro’s Developer Experience Astro’s file-based routing, content collections, and component islands made development intuitive and enjoyable. The hot module replacement during development was incredibly fast.

MDX for Project Content Using MDX for project pages was the right choice. It strikes the perfect balance between ease of writing (Markdown) and flexibility (embedded components). Adding new projects is as simple as creating a new .mdx file.

TypeScript Data Structures Defining work experience and other data in TypeScript files rather than JSON or YAML provided better developer experience with autocomplete, type checking, and inline documentation through interfaces.

Component Reusability Building small, focused components (like ProjectCard, SkillCard) made it easy to maintain consistency and quickly iterate on design changes.

Forking an Existing Template Starting from Victor Alvarado’s Astro Simple Portfolio template gave me a solid foundation while allowing extensive customization. This saved time on initial setup while still teaching me Astro’s patterns.

What Could Be Improved

Testing Strategy The site currently lacks automated tests. Adding tests for component rendering, link validity, and content structure would improve confidence when making changes.

Dark Mode While the site looks professional, adding a dark mode option would improve accessibility and user preference support. The Mermaid integration has auto-theming support, but the rest of the site doesn’t leverage it yet.

Performance Monitoring Implementing analytics and performance monitoring would provide insights into how users interact with the site and identify optimization opportunities.

Accessibility Audit A comprehensive accessibility audit would ensure the site is usable by everyone, including those using assistive technologies.

Build Optimization The current build process could be optimized with better caching strategies and incremental builds for faster deployment cycles.

Key Takeaways

Learn by Building Real Projects Working on this portfolio deepened my Astro knowledge far more than tutorials ever could. Real-world constraints and requirements drive better learning.

Content-First Architecture Pays Off Designing the site around content (MDX files, typed data structures) makes updates easy and reduces technical friction when adding new work.

Modern Tools Enable Better DX The combination of Astro, TypeScript, Tailwind, and MDX creates an excellent developer experience. Investing time in tooling setup pays dividends in long-term maintainability.

Documentation Through Code Using TypeScript interfaces as documentation (like the WorkExperience and Project interfaces) creates living documentation that can’t get out of sync with the code.

Progressive Enhancement Works Starting with static content and selectively adding interactivity (React components) results in a fast, resilient site that works well even if JavaScript fails to load.