Portfolio Website
Custom portfolio with MDX-powered project documentation and reusable components
Overview
Most developer portfolios are boring - just a list of projects with brief descriptions. I wanted something better. This portfolio turns project documentation into an experience with custom MDX components, interactive examples, and detailed technical breakdowns.
Why this approach? Most portfolios say "I built an e-commerce site with Next.js and Stripe." Cool, but how? This portfolio explains the technical challenges, architectural decisions, and interesting solutions. It's a portfolio that actually demonstrates technical depth.
Tech Stack
- Next.js 15 with App Router for static generation
- TypeScript for type safety
- Velite for MDX content management with type generation
- Tailwind CSS for styling with custom design system
- Custom MDX components for rich documentation
- rehype-pretty-code for syntax highlighting
- rehype-slug + rehype-autolink-headings for heading links
- React Server Components for optimal performance
Custom MDX Components
The real value of this portfolio is the component system. Instead of writing HTML or plain markdown, I built reusable components that make documentation beautiful and interactive.
Content Components
Callout - Highlight important information with 4 types (info, success, warning, tip) Collapse - Collapsible sections for long technical details Quote - Customer testimonials or impactful quotes Tabs - Organize tech stack or multiple code examples
Code & Technical
TechStack - Bulleted lists with proper formatting FileTree - Display project structure visually ProcessFlow - Show sequential steps (vertical or compact) UserFlow - Visual flowcharts with numbered steps UserFlowGrouped - Multi-phase workflows (this is new!)
Visual Components
Figure - Single image with caption and lightbox ImageGallery - Grid of images (2-4 columns) with lightbox ImageComparison - Before/after comparisons Stats - Key metrics display in grid StatCard - Individual metric with trend indicator
Project Documentation
Challenge - Problem/Solution/Result pattern for technical challenges Step - Step-by-step processes with numbered circles FeatureList + Feature - Detailed feature descriptions with icons FeatureGrid + FeatureCard - Grid layout for features
How It Works
Project Page Structure
Every project follows the same structure for consistency:
This structure tells a complete story: what it does, how it's built, what problems it solves, and what I learned.
Design Decisions
Velite over Contentlayer
Velite is lighter, faster, and actively maintained. Contentlayer was abandoned. Velite's API is cleaner and TypeScript support is better.
Custom Components over Templates
Building components once means every project page is consistent. Adding a new project is just writing MDX - no styling or layout decisions.
Static Generation
All projects are static HTML at build time. Fast page loads, great SEO, works with JavaScript disabled. Perfect for a portfolio.
One Dark Pro Theme
Developers recognize this theme from VS Code. Syntax highlighting feels familiar and professional.
No Database
Content is markdown files in git. Changes are tracked in version control. No CMS needed. Simpler deployment.
Server Components
Everything is a Server Component by default. Client components only for interactivity (modals, carousels). Better performance.
The UserFlowGrouped Story
What I Learned
Building this portfolio taught me:
- MDX is powerful for rich content - way better than plain markdown
- Component systems make documentation consistent and maintainable
- Velite's type generation catches content errors at build time
- Static generation is perfect for portfolios - fast and SEO-friendly
- Iterating on components based on usage improves the system
- Writing detailed project docs helps me understand my own work better
Why This Matters
Most portfolios are resumes with links. This portfolio is proof of technical depth. When I say "I built a Discord clone with a custom WebSocket server," you can read exactly how:
- Why I built my own instead of using Socket.io
- How I solved race conditions
- What the architecture looks like
- The actual code patterns I used
That's way more valuable than "Discord Clone - Next.js, WebSocket, MongoDB."
Conclusion
This portfolio is a template for technical documentation. The custom components make it easy to add new projects with consistent, high-quality documentation. Writing these detailed project pages also helps me understand my own work better - explaining something forces you to understand it deeply.
This very page you're reading was written using the same MDX components and Velite pipeline. The portfolio documents itself using its own system. That's pretty cool.
If you're building a portfolio, steal this approach. Build a component system, write detailed docs, show your technical depth. Way better than a list of project cards.