Cómo Construí Mi Blog Personal con Django y React desde Cero
Este artículo describe el proceso de creación de un blog personal desde cero utilizando Django y React. El autor explica la motivación detrás de esta decisión, optando por una arquitectura desacoplada para tener control total sobre la experiencia del usuario y la escalabilidad. Se detalla la estructura del proyecto, la elección de tecnologías como Django REST Framework para el backend y React con Material UI para el frontend, y los trade-offs de esta arquitectura. El lector aprenderá sobre la configuración inicial del backend con Django, incluyendo la definición de modelos de datos y la creaci

La Motivación: ¿Por Qué Construir Tu Propio Blog?
A finales de noviembre de 2025 tomé una decisión que muchos desarrolladores considerarían irracional: en lugar de abrir una cuenta en Medium, WordPress o Substack, decidí construir mi blog desde cero. La razón era simple —y quizás un poco pretenciosa—: quería un espacio que fuera mío en todos los sentidos. No solo el contenido, sino la arquitectura, el diseño, la infraestructura, y hasta los errores.
Soy economista de formación y científico de datos por vocación. Llevo más de ocho años enseñando econometría y estadística en universidades, y siempre me ha frustrado que los contenidos técnicos en español estén fragmentados entre slides de PowerPoint, PDFs de cátedra y notebooks de Jupyter que nadie mantiene. Quería un lugar donde pudiera escribir artículos con fórmulas matemáticas, bloques de código, gráficos, y que todo se viera bien.
Pero además quería algo más ambicioso: un blog que pudiera conversar conmigo. Un chatbot que supiera qué he escrito, que respondiera preguntas sobre mis artículos, y que lo hiciera con mi estilo y mi voz. Eso sería el motor RAG, pero ya llegaremos ahí.
Este primer artículo cubre la fase fundacional: los primeros 15 commits en un solo día de noviembre donde nació la estructura base del proyecto.
Arquitectura: La Decisión de Separar Frontend y Backend
El primer commit (ba06f6c) contiene las dos carpetas que definirían toda la arquitectura:
blog_project/
├── blog_backend/ # Django 5 + Django REST Framework
└── blog_frontend/ # React 18 + Material UI
¿Por Qué No Django con Templates?
Django tiene un sistema de templates perfectamente funcional. Podrías construir un blog completo con {% extends "base.html" %} y formularios server-side. Muchos tutoriales lo enseñan así, y funciona.
Pero yo quería tres cosas que los templates de Django manejan mal:
1. Navegación sin recargas (SPA)
Cuando un usuario hace clic en un artículo, quiero que la transición sea instantánea. Sin el flash blanco del navegador recargando la página. Con React Router, el cambio de vista es un intercambio de componentes en el DOM que toma <50ms. Con Django templates, cada clic es un HTTP GET completo → render en servidor → envío de HTML → repintado del navegador. No es lento en absoluto, pero no se siente instantáneo.
2. Interactividad rica del chatbot RAG
El chatbot necesita: - Enviar queries por AJAX y recibir respuestas sin recargar. - Renderizar la respuesta con efecto typewriter (caracter por caracter). - Mostrar tarjetas de fuentes con links. - Manejar estados de carga, error y éxito.
Todo esto es estado local del navegador. En Django templates, necesitarías HTMX o JavaScript vanilla con mucha complejidad. En React, es un useState y un useEffect.
3. Despliegue independiente
En producción, el frontend corre como un archivo estático (index.html + bundle.js) servido por Nginx en su propio contenedor Cloud Run. El backend corre con Gunicorn en otro contenedor. Cada uno escala de forma independiente. Si el frontend recibe 10,000 visitas pero solo 100 usan el chatbot, puedo escalar el frontend sin tocar el backend.
El Trade-off
Nada es gratis. Separar frontend y backend introduce complejidad:
| Aspecto | Monolítico (Django templates) | Separado (Django + React) |
|---|---|---|
| Autenticación | Sesiones (automático) | JWT (manual) |
| CORS | No necesario | Configurar django-cors-headers |
| SEO | HTML renderizado en servidor | Necesita react-helmet-async |
| Deployment | 1 servicio | 2 servicios |
| Complejidad inicial | Baja | Media-alta |
| Escalabilidad | Acoplada | Independiente |
Para un blog personal, la complejidad adicional probablemente no se justifica en términos puramente prácticos. Pero yo quería aprender la arquitectura desacoplada, y mi blog era el proyecto perfecto para hacerlo.
El Backend: Django + DRF en 30 Minutos
Modelos de Datos
El modelo Post es el corazón del blog:
```python blog_backend/blog/models.py class Post(models.Model): STATUS_CHOICES = [ ('draft', 'Draft'), ('published', 'Published'), ]
title = models.CharField(max_length=200)
slug = models.SlugField(max_length=200, unique=True)
content = models.TextField() # Markdown
content_html = models.TextField(blank=True) # HTML renderizado
cover_image = models.ImageField(upload_to='covers/', blank=True)
excerpt = models.TextField(max_length=500, blank=True)
status = models.CharField(max_length=10, choices=STATUS_CHOICES, default='draft')
author = models.ForeignKey(User, on_delete=models.CASCADE)
tags = models.ManyToManyField('Tag', blank=True)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
> **Nota (estado actual):** El modelo evolucionó en iteraciones posteriores. El campo `status` se reemplazó por dos booleanos: `is_published` (visibilidad pública) e `is_internal` (acceso solo para empleados). La versión mostrada arriba refleja el estado del día 1.
Tres decisiones de diseño importantes:
**1. Slug como identificador público.** Las URLs usan `/post/mi-articulo-sobre-python` en lugar de `/post/42`. Esto es mejor para SEO y para legibilidad humana. Django genera el slug automáticamente desde el título con `slugify()`.
**2. Contenido duplicado: Markdown + HTML.** El campo `content` almacena Markdown puro (lo que el autor escribe). El campo `content_html` almacena la versión renderizada a HTML. ¿Por qué almacenar ambos? Porque renderizar Markdown a HTML no es trivial: incluye extensiones para syntax highlighting, KaTeX para ecuaciones matemáticas, y sanitización de seguridad. Hacerlo en cada request sería desperdiciar CPU. Lo hago una vez al guardar el post (en el método `save()`).
**3. Tags como modelo separado con M2M.** Un tag tiene nombre, slug y descripción. La relación Many-to-Many permite que un post tenga múltiples tags y que un tag agrupe múltiples posts. Django genera la tabla intermedia automáticamente.
### Serializers: La Capa de Traducción
Django REST Framework usa serializers para convertir objetos Python a JSON y viceversa:
```python
class PostSerializer(serializers.ModelSerializer):
author = UserBasicSerializer(read_only=True)
tags = TagSerializer(many=True, read_only=True)
reading_time = serializers.ReadOnlyField()
class Meta:
model = Post
fields = ['id', 'title', 'slug', 'content', 'content_html',
'cover_image', 'excerpt', 'status', 'author',
'tags', 'reading_time', 'created_at', 'updated_at']
El campo reading_time es una propiedad calculada del modelo:
@property
def reading_time(self):
word_count = len(self.content.split())
return max(1, round(word_count / 200)) # 200 palabras por minuto
ViewSets: CRUD en 10 Líneas
```python blog_backend/blog/views.py class PostViewSet(viewsets.ModelViewSet): queryset = Post.objects.filter(status='published').order_by('-created_at') serializer_class = PostSerializer permission_classes = [IsAuthenticatedOrReadOnly] lookup_field = 'slug' filterset_fields = ['tags__slug', 'status'] search_fields = ['title', 'content', 'tags__name']
Un `ModelViewSet` genera automáticamente los endpoints CRUD:
- `GET /api/blog/posts/` → Listar posts (con paginación, filtros, búsqueda)
- `GET /api/blog/posts/{slug}/` → Detalle de un post
- `POST /api/blog/posts/` → Crear post (requiere autenticación)
- `PUT /api/blog/posts/{slug}/` → Actualizar post
- `DELETE /api/blog/posts/{slug}/` → Eliminar post
> **Estado actual:** En la versión actual el prefijo de ruta es `/api/blog/posts/`, resultado de una refactorización de API (enero 2026) que estandarizó todas las colecciones en forma de sustantivos plurales explícitos.
10 líneas de código → 5 endpoints REST funcionales. Esto es lo que me encanta de DRF.
---
## El Frontend: React 18 + Material UI
### ¿Por Qué Material UI?
Hay decenas de librerías de componentes para React: Chakra UI, Ant Design, Tailwind, Shadcn. Elegí Material UI (MUI) por tres razones:
1. **Sistema de temas completo.** MUI tiene un sistema de theming que permite definir paletas de colores, tipografía, spacing y breakpoints en un solo objeto. Cambiar de modo claro a oscuro es un cambio de una línea.
2. **Componentes pre-armados.** Cards, grids, botones, modals, formularios, tablas, navegación. Todo con accesibilidad (ARIA) incluida.
3. **Familiaridad.** Es el framework de UI más usado en React. Hay miles de ejemplos y la documentación es excelente.
### El Sistema de Diseño
Diseñé un tema con inspiración académica:
```javascript blog_frontend/src/theme.js
export const getTheme = (mode) => createTheme({
palette: {
mode,
primary: { main: mode === 'light' ? '#1e293b' : '#e2e8f0' },
secondary: { main: mode === 'light' ? '#6366f1' : '#818cf8' },
background: {
default: mode === 'light' ? '#f8fafc' : '#0f172a',
paper: mode === 'light' ? '#ffffff' : '#1e293b',
},
},
typography: {
fontFamily: '"Lora", serif',
h1: { fontFamily: '"Montserrat", sans-serif', fontWeight: 700 },
h2: { fontFamily: '"Montserrat", sans-serif', fontWeight: 600 },
},
});
Tipografía dual: Montserrat para headings (sans-serif, moderna, con peso) y Lora para body text (serif, elegante, legible en bloques largos). Es un patrón que vi en revistas académicas online y me pareció perfecto para un blog técnico.
Modo oscuro/claro: Un toggle en el navbar que persiste en localStorage. Cuando el usuario vuelve al blog, se respeta su preferencia anterior.
SEO con react-helmet-async
El commit c2fa136 fue dedicado enteramente a SEO. El problema de las SPAs es que los bots de Google ven un <div id="root"></div> vacío. Para que cada página tenga su propio título, descripción y meta tags, usé react-helmet-async:
``jsx blog_frontend/src/pages/PostDetail.js
// En cada página
<Helmet>
<title>{post.title} | Héctor Garrido</title>
<meta name="description" content={post.excerpt} />
<meta property="og:title" content={post.title} />
<meta property="og:image" content={post.cover_image} />
<link rel="canonical" href={https://hectorgarrido.cl/post/${post.slug}`} />
También agregué Schema.org JSON-LD en la Home para que Google entienda que es un sitio personal con un autor real:
```javascript
<script type="application/ld+json">
{JSON.stringify({
"@context": "https://schema.org",
"@type": "WebSite",
"name": "Blog de Héctor Garrido",
"author": {
"@type": "Person",
"name": "Héctor Garrido Henríquez",
"jobTitle": "Economista y Científico de Datos"
}
})}
</script>
Autenticación: JWT en Lugar de Sesiones
En una arquitectura desacoplada, las sesiones de Django no funcionan directamente porque el frontend está en un dominio distinto (o al menos un puerto distinto). La solución estándar es JWT (JSON Web Tokens):
1. Usuario envía email + password → POST /api/auth/login/
2. Django valida credenciales → genera token firmado
3. Frontend guarda token en localStorage
4. Cada request incluye: Authorization: Bearer <token>
5. Django verifica la firma sin consultar la DB
Usé djangorestframework-simplejwt que maneja todo esto automáticamente. Configuración en settings.py:
SIMPLE_JWT = {
'ACCESS_TOKEN_LIFETIME': timedelta(hours=1),
'REFRESH_TOKEN_LIFETIME': timedelta(days=7),
'ROTATE_REFRESH_TOKENS': True,
}
El access token dura 1 hora. Después, el frontend usa el refresh token para obtener uno nuevo sin que el usuario tenga que loguearse de nuevo. Cada refresh rota ambos tokens (el viejo se invalida).
La decisión de usar email como identificador:
class CustomUser(AbstractBaseUser, PermissionsMixin):
email = models.EmailField(unique=True)
USERNAME_FIELD = 'email'
La mayoría de los usuarios recuerdan su email pero olvidan su username. Además, el email es naturalmente único. Me ahorré un campo (username) que nadie necesita en un blog personal.
El Primer Despliegue: Docker + WhiteNoise
Los commits f43697b y ac1734b prepararon el proyecto para correr en contenedores Docker:
Backend Dockerfile
FROM python:3.11-slim
WORKDIR /app
RUN apt-get update && apt-get install -y build-essential libpq-dev
COPY requirements.txt ./
RUN pip install -r requirements.txt
COPY . .
RUN SECRET_KEY=dummy python manage.py collectstatic --noinput
CMD ["sh", "-c", "python manage.py migrate --noinput && gunicorn blog_backend.wsgi:application --bind 0.0.0.0:$PORT"]
WhiteNoise permite que Gunicorn sirva archivos estáticos sin necesitar Nginx. Comprime automáticamente con gzip, añade hashes para cache-busting infinito (admin.abc123.css), y establece headers de caché agresivos. Para un blog con poco tráfico, es más simple que montar un reverse proxy.
CORS: El Dolor de Cabeza Inevitable
Con frontend y backend en dominios distintos, los navegadores bloquean las requests por la Same-Origin Policy. La solución:
CORS_ALLOWED_ORIGINS = os.getenv(
'CORS_ALLOWED_ORIGINS',
'http://localhost:3000,http://127.0.0.1:3000'
).split(',')
CORS_ALLOW_CREDENTIALS = True
En desarrollo: localhost:3000 (React dev server) → localhost:8000 (Django).
En producción: hectorgarrido.cl → api.hectorgarrido.cl.
Iteraciones Rápidas: Lo Que Aprendí en un Día
Los 15 commits restantes del 23 de noviembre fueron mejoras incrementales:
38eec31— Sección de videos de YouTube en la Home. Porque no todo es texto.5aecf5e— Navegación dinámica por tags conToggleButtonGroupde MUI.49f96ee— Eliminé el botón "Todo" del filtro de posts. Menos es más.673b688— Habilitiédjango-markdownxen el admin para subir imágenes con drag & drop directamente en el editor de Markdown.aaed9e1— Un bug donde los posts mostraban el email del autor en lugar de su nombre. El serializer leíauser.emailen lugar deuser.get_full_name().d598342— Script de seed (populate_posts.py) con 24 artículos sobre series de tiempo para tener contenido desde el día uno.
La Lección
15 commits en un día suena productivo, pero la realidad es que la mitad fueron fixes de bugs que introduje en la otra mitad. El ciclo fue:
Implementar feature → Testear → Encontrar bug → Fix → Commit → Repetir
Esto es desarrollo real. No es un tutorial limpio de YouTube donde todo funciona a la primera. Es iteración constante, y cada commit es una pequeña victoria (o al menos un "ya no está roto").
Reflexión: ¿Valió la Pena?
Al final del 23 de noviembre tenía: - ✅ Backend Django con CRUD completo para posts y tags - ✅ Frontend React con 7 páginas funcionales - ✅ Autenticación JWT - ✅ SEO completo con Schema.org - ✅ Modo claro/oscuro - ✅ Docker ready - ✅ 24 posts de ejemplo cargados
¿Podría haber hecho esto en WordPress? Sí, en 2 horas.
¿Tendría el mismo control sobre cada detalle? No.
¿Habría aprendido algo nuevo? Probablemente no.
La motivación correcta para construir algo desde cero no es la eficiencia. Es la comprensión. Cuando algo se rompe en producción a las 2 AM, quiero saber exactamente dónde buscar. Y eso solo se logra habiendo construido cada capa tú mismo.
En el próximo artículo, las cosas se ponen más interesantes: embeddings vectoriales, búsqueda semántica y el nacimiento del motor RAG.
Nota sobre la evolución del motor: La primera implementación del motor de búsqueda usó SBERT (Sentence-BERT) local. Esa arquitectura fue deprecada en favor de Vertex AI exclusivo (
text-embedding-005, embeddings de 768 dimensiones). El código de SBERT/Ollama vive enblog_backend/deprecated/como referencia histórica.
Siguiente: De Búsqueda por Keywords a RAG: Cómo le Enseñé a Mi Blog a Entender Preguntas
Este artículo es parte de la serie "Construyendo un Blog con IA". El código fuente está disponible en GitHub.