MyBrain - Guía Completa de Funcionalidades

Tabla de Contenidos

Sistema Multi-Blog
Conversión Automática de Imágenes a WebP
URLs Amigables (Slugify)
Estructura de Archivos
Configuración

Sistema Multi-Blog

¿Cómo Funciona?

El sistema permite organizar tus posts en diferentes blogs/categorías de forma automática. Cada categoría se convierte en una página independiente con su propia URL.

Estructura de Categorías

Las categorías se definen en el frontmatter de cada post Markdown:

---
title: "Mi Post sobre Tecnología"
slug: mi-post-tecnologia
categories:
  - tecnología
  - tutoriales
tags:
  - astro
  - web
---

URLs Generadas

El sistema genera automáticamente URLs limpias y amigables:

Categoría en frontmatter: tecnología
URL generada: /posts/tecnologia/ (sin tildes)
Display en UI: “Tecnología” (con tilde)

Navegación

El menú principal incluye un desplegable “Blogs” con:

Todos los posts - Muestra todos los posts sin filtrar
Biodanza - Filtra por categoría “biodanza”
Literatura - Filtra por categoría “literatura”
Tecnología - Filtra por categoría “tecnologia”
Bienestar - Filtra por categoría “bienestar”

Añadir Nuevas Categorías

Simplemente añade la categoría en el frontmatter de un post:
```
categories:
  - nueva-categoria
```
El sistema automáticamente:
- Genera la ruta /posts/nueva-categoria/
- Añade la categoría al selector de blogs
- Crea la página de filtrado

Opcional: Añádela al menú principal en src/config.ts:

{ title: "Nueva Categoría", url: "/posts/nueva-categoria/" }

Conversión Automática de Imágenes a WebP

¿Qué Hace?

El sistema convierte automáticamente todas las imágenes subidas a formato WebP, optimizando el rendimiento de tu sitio.

Proceso de Conversión

Subes una imagen a cualquier carpeta src/content/**/attachments/
- Formatos soportados: PNG, JPG, JPEG, GIF, BMP, TIFF
El watcher detecta el archivo (en tiempo real durante el desarrollo)
Conversión automática:
- Crea una versión WebP optimizada (calidad 85%)
- Elimina el archivo original automáticamente
- Mantiene el mismo nombre de archivo

Resultado:

Antes: src/content/posts/attachments/mi-imagen.png
Después: src/content/posts/attachments/mi-imagen.webp

Script de Conversión

Ubicación: scripts/watch-and-convert.js

Características:

✅ Conversión en tiempo real durante npm run dev
✅ Procesa imágenes existentes al iniciar el servidor
✅ Vigila recursivamente todas las subcarpetas de src/content
✅ Ignora archivos que ya son WebP
✅ Manejo de errores robusto

Uso en Posts

En tus posts Markdown, referencia las imágenes así:

---
title: "Mi Post"
image: '/attachments/mi-imagen.webp'
---

![Descripción](/attachments/mi-imagen.webp)

Nota: Aunque subas mi-imagen.png, el sistema la convertirá a mi-imagen.webp automáticamente.

Componente ImageWrapper

El componente src/components/ImageWrapper.astro:

Busca automáticamente imágenes en src/content/**/attachments/
Usa import.meta.glob para importar imágenes dinámicamente
Optimiza las imágenes con Astro Image API
Soporta lazy loading y decoding asíncrono

URLs Amigables (Slugify)

¿Por Qué Slugify?

Las URLs nunca deben tener tildes ni caracteres especiales por:

✅ Mejor SEO (Google prefiere URLs limpias)
✅ Compatibilidad universal (todos los navegadores/servidores)
✅ URLs más cortas y legibles
✅ Evita problemas de codificación (%C3%AD en lugar de í)

Implementación

Utilidad: src/utils/slugify.js

Conversión:

"Tecnología"      → "tecnologia"
"Ciencia Ficción" → "ciencia-ficcion"
"AI & ML"         → "ai-ml"

Características:

Elimina acentos y diacríticos
Convierte a minúsculas
Reemplaza espacios con guiones
Elimina caracteres especiales
Normaliza múltiples guiones

Uso en el Sistema

Categorías de posts:
- Frontmatter: categories: [Tecnología]
- URL: /posts/tecnologia/
- UI: “Tecnología”
Tags:
- Frontmatter: tags: [Inteligencia Artificial]
- URL: /posts/tag/inteligencia-artificial
- UI: “Inteligencia Artificial”

Estructura de Archivos

Directorios Principales

MyBrain/
├── src/
│   ├── content/
│   │   ├── posts/
│   │   │   ├── attachments/        # Imágenes (auto-convertidas a WebP)
│   │   │   ├── post-1.md
│   │   │   └── post-2.md
│   │   ├── projects/
│   │   └── docs/
│   ├── components/
│   │   ├── BlogSelector.astro      # Selector de categorías
│   │   ├── ImageWrapper.astro      # Wrapper de imágenes optimizadas
│   │   ├── PostCard.astro          # Tarjeta de post
│   │   └── ...
│   ├── pages/
│   │   ├── posts/
│   │   │   ├── index.astro         # Lista todos los posts
│   │   │   ├── [categoria].astro   # Filtra por categoría
│   │   │   ├── [page].astro        # Paginación
│   │   │   └── [...slug].astro     # Post individual
│   │   └── ...
│   ├── utils/
│   │   ├── slugify.js              # Utilidad de slugificación
│   │   ├── markdown.js             # Funciones de Markdown
│   │   └── images.js               # Optimización de imágenes
│   └── config.ts                   # Configuración del sitio
├── scripts/
│   ├── watch-and-convert.js        # Conversor WebP automático
│   └── ...
└── MULTIBLOG_GUIDE.md              # Esta documentación

Flujo de Trabajo

Creas un post en src/content/posts/mi-post.md
Subes imágenes a src/content/posts/attachments/
El watcher convierte las imágenes a WebP automáticamente
Astro genera las rutas estáticas con slugs limpios
El usuario navega por categorías y tags

Configuración

Configuración de Navegación

Archivo: src/config.ts

Menú Principal:

navigation: {
  pages: [
    { title: "Blogs", url: "/posts/",
      children: [
        { title: "Todos los posts", url: "/posts/" },
        { title: "Biodanza", url: "/posts/biodanza/" },
        { title: "Literatura", url: "/posts/literatura/" },
        { title: "Tecnología", url: "/posts/tecnologia/" },
        { title: "Bienestar", url: "/posts/bienestar/" }
      ]
    },
    { title: "Documentación", url: "/docs/" },
    { title: "Acerca de", url: "/about/" }
  ]
}

Configuración de Posts

postOptions: {
  postsPerPage: 10,           // Posts por página
  tags: true,                 // Mostrar tags
  categories: true,           // Mostrar categorías
  readingTime: true,          // Mostrar tiempo de lectura
  wordCount: true,            // Mostrar conteo de palabras
}

Configuración de Imágenes

imageOptions: {
  quality: 85,                // Calidad WebP (0-100)
  format: 'webp',             // Formato preferido
  lazyLoading: true,          // Lazy loading activado
}

Comandos Útiles

Desarrollo

npm run dev                   # Iniciar servidor de desarrollo

Producción

npm run build                 # Construir sitio estático
npm run preview               # Previsualizar build

Limpieza

rm -rf .astro                 # Limpiar caché de Astro
rm -rf node_modules/.vite     # Limpiar caché de Vite

Traducciones

El sistema está completamente en español:

✅ ”+ X más” (en lugar de ”+ X more”)
✅ “más etiquetas disponibles”
✅ “min de lectura”
✅ “palabras”
✅ Todos los textos de UI en español

Mejores Prácticas

1. Nombres de Categorías

✅ Usa nombres descriptivos: tecnología, ciencia de datos
✅ El sistema se encarga de crear URLs limpias automáticamente
❌ No uses slugs manuales en el frontmatter

2. Imágenes

✅ Sube imágenes en cualquier formato (PNG, JPG, etc.)
✅ El sistema las convierte automáticamente a WebP
✅ Usa nombres descriptivos: mi-imagen-descriptiva.png
❌ No referencies imágenes con rutas absolutas de tu sistema

3. Posts

✅ Siempre incluye categories en el frontmatter
✅ Usa tags para filtrado adicional
✅ Añade image para la tarjeta social
✅ Escribe description para SEO

4. Rendimiento

✅ Las imágenes se optimizan automáticamente
✅ Uso de lazy loading en imágenes
✅ Generación estática (SSG) para máximo rendimiento
✅ Code splitting automático de Astro

Solución de Problemas

Las imágenes no se convierten

Verifica que el watcher esté corriendo: npm run dev
Revisa la consola del servidor por errores
Asegúrate de que las imágenes estén en src/content/**/attachments/

Las categorías no aparecen

Verifica que el frontmatter tenga categories: [nombre]
Reinicia el servidor: Ctrl+C → npm run dev
Limpia la caché: rm -rf .astro

URLs con 404

Verifica que estés usando slugs limpios (sin tildes)
Revisa que el archivo [categoria].astro exista
Reconstruye el sitio: npm run build

Créditos y Licencia

Sistema desarrollado para MyBrain - Second Brain con Astro
Basado en arquitectura modular y escalable

Última actualización: Junio 2026