Apariencia

AGENTS.md - Proyecto VitePress Blog Honesting ​

Descripción del Proyecto ​

Sitio web de blog corporativo para Honesting (empresa de hosting cloud) construido con VitePress. El proyecto contiene cientos de artículos en formato Markdown sobre hosting, dominios, desarrollo web y servicios relacionados.

Estructura del Proyecto ​

vitepress/
├── .vitepress/
│   ├── config.mts          # Configuración principal de VitePress
│   ├── theme/
│   │   ├── index.js        # Exporta tema personalizado
│   │   ├── Layout.vue      # Layout personalizado con sidebar de categorías
│   │   ├── BlogPage.vue    # Página principal del blog con paginación
│   │   ├── posts.data.mjs  # Data loader para posts del blog
│   │   ├── categories.data.mjs  # Data loader para categorías
│   │   ├── YouTubeEmbed.vue    # Componente para embed de videos
│   │   ├── PlanCards.vue      # Componente para mostrar planes de hosting
│   │   ├── StatusServices.vue  # Componente para estado de servicios
│   │   └── CategoryPage.vue   # Página de categoría
│   └── cache/              # Cache de VitePress (ignorar)
├── public/
│   ├── favicon.ico         # Favicon del sitio
│   └── images/             # Todas las imágenes del sitio (no en git)
├── scripts/
│   ├── deploy-ftp.js       # Script para despliegue por FTP
│   ├── analyze-images.js   # Script para analizar imágenes
│   ├── fix-links.js        # Script para corregir enlaces
│   └── fix-images.js       # Script para corregir rutas de imágenes
├── *.md                    # Cientos de artículos del blog
├── blog.md                 # Página principal del blog
├── package.json            # Dependencias del proyecto
└── node_modules/           # Dependencias instaladas

Tecnologías Utilizadas ​

  • VitePress: ^1.0.0 - Framework de documentación basado en Vite y Vue 3
  • Vue: ^3.4.0 - Framework JavaScript para UI reactiva
  • Node.js: Entorno de ejecución
  • fast-levenshtein: ^3.0.0 - Algoritmo de fuzzy matching para imágenes

Características Principales ​

1. Sistema de Blog ​

  • Página principal: blog.md con listado de posts paginado (10 posts por página)
  • Filtrado por categorías: Sistema de filtros interactivos con URLs amigables
  • Paginación avanzada: Con números de página, ellipsis y navegación prev/next
  • Metadata: Cada post incluye título, fecha, excerpt, categorías y featuredImage
  • URLs de categorías: /web/nombre-categoria/ con slug automático

2. Data Loaders ​

  • posts.data.mjs: Carga todos los archivos .md, filtra páginas especiales, extrae frontmatter, genera excerpt automáticamente si no existe, y ordena por fecha descendente
  • categories.data.mjs: Genera conteo de categorías automáticamente desde los posts

3. Layout Personalizado ​

  • Layout.vue: Extiende el tema por defecto de VitePress
  • Sidebar de categorías: Aparece solo en posts individuales (detecta si tiene categorías en frontmatter)
  • Imagen destacada: Muestra featuredImage antes del contenido del post
  • CTA en posts: Call-to-action al final de cada post del blog
  • Logo duplicado: El logo del navbar se muestra a 64px de altura
  • Copyright en sidebar: Texto de copyright personalizado en el sidebar

4. Configuración ​

  • cleanUrls: true (URLs sin .html)
  • ignoreDeadLinks: true (No muestra errores de enlaces muertos)
  • Navegación: Links al blog y "Mi cuenta" (panel.honesting.es) en navbar
  • Sidebar: Menú con secciones de Dominios, Hosting, Páginas web e Información
  • Footer: Navegación prev/next deshabilitada
  • Búsqueda: Búsqueda local con traducciones en español
  • Logo: SVG personalizado con variantes claro/oscuro

5. Componentes Personalizados ​

  • YouTubeEmbed: Componente para incrustar videos de YouTube
  • PlanCards: Componente para mostrar tarjetas de planes de hosting
  • StatusServices: Componente para mostrar estado de servicios

6. Assets y Medios ​

  • Directorio uploads: Referencias antiguas que necesitan corrección
  • Rutas de imágenes correctas: Usar /images/nombre.png (sin prefijo de dominio)
  • Imágenes rotas: Algunos archivos usan rutas de WordPress y necesitan corrección
  • Corrección automática: Script fix-images.js con fuzzy matching para encontrar imágenes similares

Comandos Disponibles ​

bash
# Desarrollo local
npm run dev
# o
npm run docs:dev

# Build para producción
npm run docs:build

# Preview del build
npm run docs:preview

Estructura de Frontmatter en Posts ​

yaml
---
title: "Título del post"
date: "YYYY-MM-DD"
author: "1"
excerpt: "Resumen breve del artículo"
categories:
  - "Categoría 1"
  - "Categoría 2"
featuredImage: "/images/ruta/a/imagen.jpg"  # Opcional
---

Convenciones del Código ​

Archivos de Configuración ​

  • Usar TypeScript para config: .mts
  • Usar ES Modules para data loaders: .mjs
  • Usar JavaScript estándar para scripts: .js

Componentes Vue ​

  • Composition API con <script setup> (Layout.vue) o Options API (BlogPage.vue)
  • Usar useData() de VitePress para acceder a frontmatter y page data
  • CSS scoped para estilos específicos de componentes
  • CSS global para estilos que afectan elementos fuera del componente
  • Variables CSS de VitePress para theming consistente

Estilos ​

  • Usar variables CSS de VitePress:
    • --vp-c-brand-1: Color principal
    • --vp-c-brand-2: Color secundario
    • --vp-c-brand-soft: Versión suave del color principal
    • --vp-c-bg-soft: Fondos suaves
    • --vp-c-bg-mute: Fondos neutros
    • --vp-c-text-1, --vp-c-text-2, --vp-c-text-3: Colores de texto
    • --vp-c-divider: Bordes y separadores

Data Loaders ​

  • Usar createContentLoader() de VitePress
  • Filtrar páginas especiales (index, blog, ejemplos, estado de servicios)
  • Transformar datos en formato consistente
  • Ordenar por fecha descendente
  • Extraer excerpt del contenido si no existe en frontmatter

Notas Importantes ​

  1. No hay git: El proyecto no está en un repositorio git (según env info)
  2. Contenido masivo: Hay cientos de archivos .md con posts del blog
  3. Categorías dinámicas: Se generan automáticamente desde el frontmatter de los posts
  4. URLs limpias: Sin extensión .html gracias a cleanUrls: true
  5. Tema extendido: Se usa el tema por defecto de VitePress con customizaciones
  6. Problemas de imágenes: Muchas imágenes usan rutas de WordPress y necesitan corrección
  7. Imágenes en gitignore: El directorio public/images/ está en .gitignore debido al tamaño
  8. Slug automático: Los nombres de categoría se convierten a slugs automáticamente para URLs

Tareas Comunes ​

Añadir un nuevo post ​

  1. Crear archivo .md en la raíz con el slug como nombre (ej: mi-nuevo-post.md)
  2. Añadir frontmatter completo con título, fecha, categorías, excerpt y featuredImage
  3. El post aparecerá automáticamente en el blog ordenado por fecha
  4. Las categorías se actualizarán automáticamente

Corregir enlaces de imágenes ​

  1. Ejecutar el script de corrección:
    bash
    node scripts/fix-images.js
  2. El script:
    • Busca referencias de imágenes en archivos markdown
    • Usa fuzzy matching (distancia Levenshtein) para encontrar imágenes similares en public/images/
    • Reemplaza con sintaxis markdown pura ![](/images/nombre.png)
    • Maneja etiquetas <figure> convirtiéndolas a imágenes simples
    • Remueve prefijos de fecha (ej. 2024-01-) para mejor matching

Mejoras aplicadas en fix-images.js:

  • Umbral de similitud ajustable (75% de la longitud por defecto)
  • Elimina tags HTML de galerías y convierte a imágenes markdown
  • Procesa todos los archivos .md en el directorio raíz automáticamente

Casos especiales:

  • Galerías de WordPress: Convertir a listas de imágenes markdown
  • Imágenes con links: Mantener solo la imagen, quitar links si no son necesarios

Verificación: Revisar en localhost que las imágenes se muestren correctamente.

Modificar el layout ​

  • Editar .vitepress/theme/Layout.vue
  • Usar slots de VitePress: #doc-before, #doc-after, #aside, #sidebar-nav-after, etc.
  • Mantener estilos CSS separados en <style> (global) y <style scoped> (componente)

Cambiar configuración del sitio ​

  • Editar .vitepress/config.mts
  • Modificar título, descripción, navegación, sidebar, logo, etc.

Personalizar estilos globales ​

  • Añadir estilos globales en Layout.vue sin scoped
  • Usar variables CSS de VitePress para consistencia

Añadir nuevo componente ​

  1. Crear archivo .vue en .vitepress/theme/
  2. Importar y registrar en .vitepress/theme/index.js
  3. Usar app.component() para registro global

Manejo de Imágenes ​

Referencias de Imágenes ​

  • Incorrectas (WordPress): /uploads/2024/01/imagen.png, https://www.honesting.es/wp-content/uploads/...
  • Correctas: /images/imagen.png (archivo en public/images/)

Script de Reparación: fix-images.js ​

  • Busca referencias rotas en archivos markdown
  • Usa fuzzy matching (distancia Levenshtein) para encontrar imágenes similares
  • Reemplaza con sintaxis markdown pura
  • Convierte <figure> tags a ![]() markdown
  • Procesa todos los archivos .md en la raíz

Ejecutar:

bash
node scripts/fix-images.js

Script de Análisis: analyze-images.js ​

Analiza todas las referencias de imágenes en el proyecto para identificar problemas.

Corrige enlaces rotos o incorrectos en el contenido.

Recursos ​

Despliegue ​

El proyecto incluye un script deploy-ftp.js para despliegue vía FTP. Requiere configuración de credenciales en el script o archivo .env (no incluido en el repositorio).

Debugging ​

Si las imágenes no se muestran:

  1. Verificar que la ruta sea /images/nombre.png (sin prefijo de dominio)
  2. Verificar que el archivo exista en public/images/
  3. Ejecutar npm run dev para verificar en localhost
  4. Usar scripts/fix-images.js para corregir rutas automáticamente

Si los posts no aparecen en el blog:

  1. Verificar que el archivo .md tenga el frontmatter correcto
  2. Verificar que tenga al menos title y date
  3. Revisar que la fecha esté en formato YYYY-MM-DD
  4. Verificar que no esté filtrado en posts.data.mjs (lista de exclusiones)