TM
HomeAboutExperienceProjectsBlog
HomeAboutExperienceProjectsBlog
  1. Projects
  3. YAML-Driven Portfolio Builder

YAML-Driven Portfolio Builder

Modern portfolio template with YAML config and MDX content - update your info without touching code

Next.js 15
Vercel
TypeScript
Tailwind CSS 4
MDX
YAML
React 19
Accessibility
Open source

Overview

A modern, SEO-optimized portfolio template that separates content from code using YAML configuration and MDX content files. Developers can update their entire portfolio - personal info, projects, blog posts, and experiences - without touching a single line of code.

Built with Next.js 15 App Router, TypeScript, and Tailwind CSS 4, this template delivers fast, static-generated pages with perfect SEO scores while maintaining full type safety and developer experience.

Problems & Solutions

Problem One: Content Updates Require Code Changes

Pain Point

Most portfolio templates hardcode personal information directly into React components. Want to update your email? Edit a component. Add a new social link? Modify JSX. Write a blog post? Create a new React page. This tight coupling between content and code creates friction for non-technical updates and makes the codebase harder to maintain.

Existing Solutions

Traditional solutions use headless CMS platforms (Contentful, Sanity) which add complexity, require API keys, introduce runtime dependencies, and often come with usage limits or costs. They're overkill for a personal portfolio.

Solution One: YAML Configuration System

All site configuration lives in simple YAML files that anyone can edit with a text editor. Personal info, social links, SEO metadata, navigation menus - everything is declarative and type-safe.

Key Innovation: Build-time YAML parsing with TypeScript validation ensures configuration errors are caught during development, not in production. Zero runtime overhead, full type safety.

graph LR A[YAML Files] -->|js-yaml| B[TypeScript Types] B -->|Validation| C[Build Time] C -->|Static Generation| D[HTML Pages] style A fill:#e1f5ff style D fill:#d4edda

Impact

  • āš” Zero Runtime Cost: All YAML parsed at build time, no client-side processing
  • šŸŽÆ Type Safety: TypeScript interfaces validate YAML structure automatically
  • šŸš€ 5-Minute Updates: Change email, add social links, update bio - all without code

Problem Two: Blog Posts Require React Knowledge

Pain Point

Writing blog posts shouldn't require understanding React components, JSX syntax, or Next.js routing. Content creators want to write in Markdown, not wrestle with component imports and page structure.

Existing Solutions

Static site generators (Jekyll, Hugo) solve this but lack React's component ecosystem. React-based solutions (Gatsby, Docusaurus) require understanding their plugin systems and GraphQL queries.

Solution Two: MDX Content System

Write blog posts, project showcases, and experience entries in pure Markdown with optional React components. Frontmatter metadata (title, date, tags) is automatically parsed and validated.

Key Innovation: Automatic route generation from file structure. Drop an MDX file in src/content/blogs/my-post.mdx and it's instantly available at /blog/my-post with full SEO metadata.

graph TD A[Write MDX File] -->|gray-matter| B[Parse Frontmatter] B -->|Validate Types| C[TypeScript Check] A -->|next-mdx-remote| D[Render Content] C --> E[Generate Route] D --> E E -->|Static Export| F[SEO-Optimized Page] style A fill:#fff3cd style F fill:#d4edda

Impact

  • šŸ“ Markdown Simplicity: Write in familiar Markdown syntax with React superpowers
  • šŸ” Auto SEO: Sitemap, metadata, structured data generated automatically
  • āš” Static Generation: All pages pre-rendered at build time for instant loading

System Architecture

graph TB subgraph "Content Layer" A[YAML Config Files] B[MDX Content Files] end subgraph "Build Process" C[js-yaml Parser] D[gray-matter Parser] E[TypeScript Validation] F[Next.js Build] end subgraph "Output" G[Static HTML Pages] H[SEO Metadata] I[Sitemap & JSON-LD] end A -->|Parse| C B -->|Parse| D C --> E D --> E E --> F F --> G F --> H F --> I style A fill:#e1f5ff style B fill:#fff3cd style G fill:#d4edda
šŸ“ View Detailed Architecture
graph TB subgraph "Configuration System" A1[site.yaml] A2[personal.yaml] A3[home.yaml] A4[about.yaml] A5[navigation.yaml] end subgraph "Content System" B1[blogs/*.mdx] B2[projects/*.mdx] B3[experiences/*.mdx] end subgraph "Type System" C1[config.ts Types] C2[content.ts Types] end subgraph "Loaders" D1[config.ts Loader] D2[blog.ts Loader] D3[project.ts Loader] D4[experience.ts Loader] end subgraph "Pages" E1[Home Page] E2[About Page] E3[Blog Pages] E4[Project Pages] E5[Experience Pages] end subgraph "SEO Layer" F1[generateMetadata] F2[sitemap.ts] F3[JSON-LD Components] end A1 & A2 & A3 & A4 & A5 --> D1 B1 --> D2 B2 --> D3 B3 --> D4 D1 --> C1 D2 & D3 & D4 --> C2 C1 --> E1 & E2 C2 --> E3 & E4 & E5 E1 & E2 & E3 & E4 & E5 --> F1 D2 & D3 & D4 --> F2 D1 --> F3 style A1 fill:#e1f5ff style B1 fill:#fff3cd style E1 fill:#d4edda

Architecture Decisions:

  1. YAML over JSON: Human-readable, supports comments, cleaner syntax for configuration
  2. Build-time parsing: Zero runtime overhead, catch errors early, better performance
  3. Type-first approach: TypeScript interfaces drive validation, preventing configuration errors
  4. File-based routing: Intuitive content organization, automatic route generation
  5. Static generation: Maximum performance, perfect SEO, works without JavaScript

Key Features

šŸš€ YAML Configuration - Update personal info, social links, and settings without code
āš” MDX Content System - Write blog posts and projects in Markdown with React components
šŸŽÆ Type-Safe Everything - Full TypeScript validation for configs and content
šŸ” SEO Optimized - Auto-generated sitemap, metadata, and structured data
šŸ“± Mobile-First Design - Fully responsive with dark/light mode support
šŸš€ Static Generation - Pre-rendered pages for instant loading and perfect SEO

Technical Challenges

Challenge One: Type-Safe YAML Validation - Ensuring YAML files match TypeScript interfaces at build time

šŸ” Deep Dive: Type-Safe YAML Validation

Problem: YAML files are untyped by nature. A typo in a field name or wrong data type would only be discovered at runtime, potentially breaking the entire site.

Solution: Created a loader system that parses YAML files using js-yaml and validates them against TypeScript interfaces during the build process. If the YAML structure doesn't match the expected types, the build fails with clear error messages pointing to the exact issue.

Impact: Caught 100% of configuration errors at build time, preventing production issues. Developers get IDE autocomplete and type checking when working with config data.

Challenge Two: Automatic Route Generation from MDX - Creating dynamic routes for all content files without manual configuration

šŸ” Deep Dive: Automatic Route Generation

Problem: Next.js requires explicit route definitions. Manually creating a route for each blog post or project would be tedious and error-prone.

Solution: Implemented a file-system-based content loader that scans the src/content/ directory at build time, parses all MDX files, extracts frontmatter metadata, and generates static routes automatically. Used Next.js 15's generateStaticParams to pre-render all pages.

Impact: Zero-config content management. Drop an MDX file in the right folder and it's instantly live with full SEO metadata, no routing code needed.

Challenge Three: SEO Metadata Generation - Automatically generating comprehensive SEO data for all pages

šŸ” Deep Dive: SEO Metadata Generation

Problem: Each page needs unique metadata (title, description, Open Graph tags, Twitter Cards, canonical URLs) and structured data (JSON-LD). Manually maintaining this for every page is error-prone.

Solution: Built a metadata generation system that combines YAML config with MDX frontmatter to automatically create complete SEO metadata for every page. Implemented JSON-LD structured data components for Person, BlogPosting, and SoftwareSourceCode schemas.

Impact: Perfect SEO scores out of the box. Every page has complete metadata, social media previews work correctly, and search engines can properly index all content.

Tech Stack

CategoryTechnologies
FrameworkNext.js 15 (App Router), React 19
LanguageTypeScript 5
StylingTailwind CSS 4, shadcn/ui components
ContentMDX (next-mdx-remote), gray-matter, remark-gfm
ConfigurationYAML (js-yaml)
SEOnext-sitemap, JSON-LD structured data
DevOpsStatic export, Vercel/Netlify deployment

Impact & Results

  • āš” 5-Minute Updates: Change any site content in under 5 minutes without touching code
  • šŸŽÆ 100% Type Safety: Zero runtime configuration errors with build-time validation
  • šŸš€ Perfect SEO Scores: Automatic sitemap, metadata, and structured data generation
  • šŸ“ Zero-Config Content: Drop MDX files and they're instantly live with full SEO
  • šŸ”§ Developer Experience: Full TypeScript support with IDE autocomplete for all configs

Comments