De GitHub Pages a Vercel: Modernizando un portfolio académico con Next.js y Fumadocs

Guía completa del proceso de deployment y configuración del portfolio usando Next.js, Fumadocs y Vercel en lugar del stack tradicional de GitHub Pages y MkDocs.

Tecnologías Utilizadas

En lugar de usar GitHub Pages con MkDocs, este portfolio está desarrollado con:

Next.js 15.5.2: Framework de React para aplicaciones web modernas
Fumadocs: Sistema de documentación especializado para crear portafolios técnicos
Vercel: Plataforma de deployment optimizada para Next.js
TypeScript: Para mayor robustez del código
Tailwind CSS: Framework de CSS para estilos responsivos

Resultado Obtenido

Al completar esta práctica logré:

Un repositorio personal creado y configurado con fumadocs
Deployment automático configurado con Vercel
Sitio online en: https://portfolio-ia-joaquin.vercel.app
Estructura de documentación organizada por secciones
Sistema de navegación automático entre prácticas

Arquitectura del Proyecto

Estructura de Archivos

portfolio-ia/
├── app/                    # Aplicación Next.js
│   ├── (home)/            # Página principal
│   ├── docs/              # Layout de documentación
│   └── api/search/        # API de búsqueda
├── content/docs/          # Contenido en MDX
│   ├── EDA y Fuentes/     # Prácticas de análisis
│   └── Calidad y Etica/   # Prácticas de calidad
├── components/            # Componentes React
├── lib/                   # Configuración y utilidades
└── public/images/         # Recursos estáticos

Ventajas de Fumadocs vs MkDocs

Característica	Fumadocs	MkDocs
Framework Base	Next.js + React	Python + Jinja2
Interactividad	Componentes React nativos	Limitada
Performance	SSG + ISR optimizado	Generación estática básica
Búsqueda	API integrada con Next.js	Plugin externo requerido
Deployment	Vercel (automático)	GitHub Pages (manual)
Customización	JSX/TSX completo	Templates limitados

Proceso de Deployment

1. Configuración del Repositorio

# Crear proyecto desde template de fumadocs
npx create-fumadocs-app@latest portfolio-ia

# Configurar dependencias
npm install

2. Configuración de Vercel

En lugar de GitHub Actions, Vercel maneja el deployment automáticamente:

Conectar repositorio: Vincular GitHub repo con Vercel
Auto-deploy: Cada push a main despliega automáticamente
Preview deployments: Cada PR genera un preview único
Domain management: URL personalizada disponible

3. Configuración de Contenido

El archivo source.config.ts define la estructura:

export const source = loader({
  baseUrl: '/docs',
  rootDir: 'content/docs',
  source: {
    files: 'content/docs/**/*.mdx'
  }
});

Contenido del Portfolio

A. Portada Personalizada

Información personal: Joaquín Batser - Estudiante de IA
Objetivo del curso: Desarrollo de habilidades en análisis de datos y machine learning
Links profesionales: GitHub, LinkedIn

B. Secciones Principales

Calidad y Ética

Prácticas de validación de datos
Consideraciones éticas en IA

C. Características Técnicas

Navegación Automática: Fumadocs genera automáticamente:

Sidebar con estructura jerárquica
Breadcrumbs de navegación
Links entre secciones relacionadas
Búsqueda full-text integrada

Componentes Interactivos:

Tabs para organizar contenido
Code blocks con syntax highlighting
Imágenes optimizadas con Next.js Image

Workflow de Actualización

Proceso de Contenido

Editar: Modificar archivos .mdx en content/docs/
Preview: npm run dev para vista previa local
Commit: Push a GitHub
Deploy: Vercel despliega automáticamente

Ventajas del Workflow

Tiempo de deploy: ~30 segundos vs ~2-3 minutos de GitHub Actions
Preview automático: URL única para cada PR
Rollback instantáneo: Revertir a cualquier deployment anterior
Analytics integradas: Métricas de performance y usuarios

Métricas de Performance

Vercel proporciona analytics detalladas:

Core Web Vitals: LCP, FID, CLS optimizados
Loading Speed: ~200ms tiempo de respuesta
SEO Score: 95+ en Lighthouse
Accessibility: Cumple WCAG 2.1 AA

Enlaces Importantes

Sitio en producción: https://portfolio-ia-joaquin.vercel.app
Repositorio: GitHub - portfolio-ia
Dashboard Vercel: Panel de control para deployments

La migración de GitHub Pages a Vercel con Next.js y Fumadocs representa un salto cualitativo en la infraestructura del portfolio. El nuevo stack ofrece tiempos de deployment significativamente más rápidos (~30 segundos vs 2-3 minutos), mejor performance (SSG + ISR), y capacidades de interactividad superiores gracias a React. La automatización completa del workflow de deployment elimina pasos manuales y reduce la fricción para actualizar contenido.

Próximos pasos: Implementar búsqueda full-text avanzada con Algolia para mejorar la navegabilidad del portfolio. Configurar analytics detalladas con Vercel Analytics para entender qué prácticas reciben más visitas. Explorar la integración de componentes interactivos React en las prácticas (ej. visualizaciones D3.js embebidas). Optimizar las imágenes del portfolio usando Next.js Image con lazy loading automático. Configurar un dominio personalizado para profesionalizar la URL del portfolio.

Última actualización: 13 de septiembre de 2025