Guías de CazaSubastas

Este directorio contiene todas las guías y tutoriales de CazaSubastas, gestionadas mediante Nuxt Content.

Estructura de Directorios

guides/
├── README.md                    # Este archivo
├── meta.json                    # Navegación raíz
├── getting-started/             # Primeros Pasos
│   ├── meta.json
│   ├── index.md                 # Página de categoría
│   └── *.md                     # Guías individuales
├── auctions/                    # Subastas
├── bidding/                     # Pujas
├── legal/                       # Legal
├── investment/                  # Inversión
└── tools/                       # Herramientas

Crear una Nueva Guía

1. Elige la categoría apropiada

getting-started: Guías para principiantes
auctions: Información sobre tipos de subastas
bidding: Estrategias y procedimientos de puja
legal: Aspectos legales, cargas y gravámenes
investment: Análisis financiero y estrategias de inversión
tools: Uso de herramientas de CazaSubastas

2. Crea el archivo markdown

Nombre del archivo: usa kebab-case (palabras-separadas-por-guiones)

Ejemplo: como-constituir-deposito.md

3. Añade el frontmatter

---
title: "Título de la Guía"
description: "Descripción breve para SEO y listados"
category: "getting-started"  # Una de las 6 categorías
difficulty: "beginner"        # beginner, intermediate, o advanced
readTime: 10                  # Minutos de lectura estimados
author: "Nombre del Autor"
authorRole: "Rol del Autor"
publishedAt: "2024-01-15"    # Fecha de publicación
updatedAt: "2024-01-15"      # Fecha de última actualización
featured: false               # true para aparecer en destacados
tags: ["tag1", "tag2"]       # Tags para guías relacionadas
---

4. Escribe el contenido

Usa markdown estándar:

## Título de Sección

Texto del párrafo...

### Subsección

- Lista de puntos
- Otro punto

**Negrita**, *cursiva*, `código`

::alert{type="info"}
Contenido de alerta informativa
::

::alert{type="warning"}
Contenido de advertencia
::

::alert{type="danger"}
Contenido de peligro
::

::alert{type="success"}
Contenido de éxito
::

5. Actualiza meta.json

Añade la nueva guía al archivo meta.json de la categoría:

{
  "items": {
    "index": "Introducción",
    "guia-existente": "Título de guía existente",
    "tu-nueva-guia": "Título de tu nueva guía"
  }
}

El orden en meta.json determina el orden en la navegación.

Frontmatter: Campos Disponibles

Campos Obligatorios

title: Título de la guía
description: Descripción breve (para SEO y cards)
category: Categoría de la guía
readTime: Minutos de lectura estimados
author: Nombre del autor
publishedAt: Fecha de publicación (formato ISO)

Campos Opcionales

authorRole: Rol o título del autor
difficulty: Nivel de dificultad (beginner, intermediate, advanced)
updatedAt: Fecha de última actualización
featured: Aparece en sección destacada (default: false)
tags: Array de tags para guías relacionadas
authorImage: URL de imagen del autor

Características Automáticas

Tabla de Contenidos (TOC)

Se genera automáticamente desde los headings del markdown:

## Sección 1
### Subsección 1.1
## Sección 2

Genera un TOC navegable en el sidebar.

Guías Relacionadas

Se calculan automáticamente basándose en tags compartidos.

Ejemplo:

# Guía A
tags: ["principiantes", "depósito", "pujas"]

# Guía B
tags: ["depósito", "procedimiento"]

Guía B aparecerá como relacionada de Guía A (comparten "depósito").

SEO

Los meta tags se generan automáticamente desde el frontmatter:

<title> ← frontmatter.title
<meta description> ← frontmatter.description
Open Graph tags
Structured data

Componentes Personalizados

Alertas

::alert{type="info"}
Contenido informativo
::

::alert{type="warning"}
Advertencia importante
::

::alert{type="danger"}
Peligro o error crítico
::

::alert{type="success"}
Mensaje de éxito
::

Buenas Prácticas

Títulos

H1 (#): Solo el título principal (auto-generado desde frontmatter)
H2 (##): Secciones principales
H3 (###): Subsecciones
H4 (####): Raramente necesario

Longitud

Beginner: 500-1000 palabras (~5-8 min)
Intermediate: 1000-2000 palabras (~8-15 min)
Advanced: 2000+ palabras (~15+ min)

Estructura Recomendada

## Introducción
Qué aprenderá el lector, por qué es importante

## Contexto / Conceptos Previos
Conocimientos necesarios

## Sección Principal 1
Contenido detallado

## Sección Principal 2
Más contenido

## Ejemplos Prácticos
Casos de uso reales

## Conclusión
Resumen y próximos pasos

## Recursos Adicionales
Enlaces útiles (opcional)

Imágenes

Para añadir imágenes:

Coloca la imagen en /public/images/guides/
Referencia en markdown:

![Descripción de la imagen](/images/guides/nombre-imagen.jpg)

Enlaces

Enlaces internos (otras guías):

[Ver guía de depósitos](/guides/bidding/constituir-deposito-pujar)

Enlaces externos:

[Portal BOE](https://subastas.boe.es)

Internacionalización (i18n)

Para crear versiones en otros idiomas:

Crea archivo con sufijo de idioma:
- guia-principiantes.md (español, default)
- guia-principiantes.ca.md (catalán)
- guia-principiantes.en.md (inglés)
El sistema seleccionará automáticamente según el locale del usuario

Testing Local

Inicia el servidor de desarrollo:
```
pnpm dev
```
Navega a /guides para ver el listado
Accede a tu guía:
```
/guides/categoria/nombre-guia
```

Deployment

Las guías se generan estáticamente en build time:

pnpm build

Nuxt Content convierte todos los archivos .md en páginas optimizadas.

Troubleshooting

La guía no aparece en el listado

Verifica que el archivo tiene extensión .md
Comprueba que el frontmatter es válido (YAML correcto)
Asegúrate de que no faltan campos obligatorios
Reinicia el servidor de desarrollo

El TOC no se genera

Asegúrate de usar headings markdown (##, ###)
No uses HTML para títulos
Deja líneas en blanco antes y después de headings

Las guías relacionadas no funcionan

Verifica que ambas guías tengan tags
Los tags deben coincidir exactamente (case-sensitive)
Se necesita al menos 1 tag compartido

Errores de frontmatter

# ❌ Incorrecto
title: Guía sin comillas con: caracteres especiales

# ✅ Correcto
title: "Guía sin comillas con: caracteres especiales"

# ❌ Incorrecto
tags: tag1, tag2

# ✅ Correcto
tags: ["tag1", "tag2"]

Mantenimiento

Actualizar una guía existente

Edita el archivo .md
Actualiza updatedAt en el frontmatter
Commit y push

Reorganizar categorías

Mueve archivos .md a nueva carpeta
Actualiza category en frontmatter
Actualiza meta.json en ambas carpetas

Archivar guías obsoletas

Cambia featured: false

Añade nota de deprecación al inicio:

::alert{type="warning"}
Esta guía está desactualizada. Ver [nueva guía](/nueva-guia)
::

Recursos

Última actualización: 2024-01-18 Mantenedor: Equipo CazaSubastas