Contribuir a la Documentacion

Guia para agregar y actualizar documentacion en el proyecto Nvito Docs.

Inicio Rapido

# Clonar el repositorio
git clone git@gitlab.com:nvito/nvito-docs.git
cd nvito-docs

# Instalar dependencias
npm install

# Iniciar servidor de desarrollo
npm run dev

El servidor local estara disponible en http://localhost:3333 con hot-reload.

Estructura del Proyecto

nvito-docs/
├── content/                 # Documentacion en MDX
│   ├── negocio/             # Documentacion de negocio
│   └── tecnico/             # Documentacion tecnica
│       ├── arquitectura/    # Arquitectura y diagramas
│       ├── backend/         # API Overview, modelo de datos, seguridad
│       ├── frontend/        # Admin dashboard, invitaciones, app movil
│       ├── flujos/          # Invitaciones, eventos, notificaciones
│       ├── guias/           # Guias de desarrollo
│       └── metricas-calidad.mdx
├── src/app/                 # App Router (Next.js)
├── src/components/          # Componentes React
└── src/lib/                 # Utilidades y configuracion

Crear un Nuevo Documento

1. Crear el archivo MDX

Crea un archivo .mdx en la carpeta correspondiente:

# Ejemplo: nueva guia
touch content/tecnico/guias/mi-nueva-guia.mdx

2. Agregar frontmatter

Todo documento debe incluir frontmatter al inicio:

---
title: "Titulo del Documento"
description: "Descripcion breve que aparece en SEO y previews."
order: 3
sidebar_label: "Label en Sidebar"
---

# Titulo del Documento

Contenido aqui...

Campo	Requerido	Descripcion
`title`	Si	Titulo que aparece en la pagina y metadata
`description`	Recomendado	Descripcion para SEO y meta tags
`order`	Si	Orden numerico en la navegacion (1 = primero)
`sidebar_label`	Recomendado	Texto corto para la navegacion lateral

3. Verificar en la navegacion

Los documentos se descubren automaticamente por el sistema de archivos. Solo asegurate de que el archivo este en la carpeta correcta y tenga frontmatter valido.

Diagramas con Mermaid

La documentacion soporta diagramas Mermaid. Usa bloques de codigo con el lenguaje mermaid:

```mermaid
graph TD
    A[Inicio] --> B[Proceso]
    B --> C[Fin]
```

Tipos de diagramas soportados

Tipo	Uso	Ejemplo
`graph` / `flowchart`	Flujos y arquitectura	Diagrama C4, pipelines
`sequenceDiagram`	Interacciones entre componentes	Flujo de autenticacion
`stateDiagram-v2`	Maquinas de estado	Ciclo de vida de invitaciones
`erDiagram`	Relaciones de entidades	Modelo de datos
`classDiagram`	Estructura de clases	Patrones de diseno

Convenciones de color

Usa las clases CSS establecidas para mantener consistencia:

Convenciones de Escritura

Idioma

Toda la documentacion se escribe en espanol.
Terminos tecnicos se mantienen en su idioma original: middleware, guard, hook, query, etc.
Nombres de codigo (funciones, clases, variables) se escriben tal cual: ClerkAuthGuard, createEvent, user_roles.

Formato

Titulos: Usa ## para secciones principales, ### para subsecciones.
Codigo inline: Usa backticks para nombres de codigo: apiClient, EventsService.
Bloques de codigo: Siempre especifica el lenguaje (typescript, bash, sql, json, yaml).
Tablas: Usa tablas Markdown para comparaciones y listados estructurados.
Links internos: Usa rutas relativas dentro del contenido.

Estructura de documento

Frontmatter con title, description, order, sidebar_label
Titulo H1 (puede ser diferente al frontmatter title)
Secciones numeradas con ##
Diagramas Mermaid donde aporten claridad

Links entre Documentos

Usa rutas relativas desde el archivo actual para links internos.

Para links externos (API interactiva, repositorios):

[API Interactiva (Scalar)](http://localhost:3000/api/docs)
[Repositorio nvito-api](https://gitlab.com/nvito/nvito-api)

Preview y Build

# Servidor de desarrollo con hot-reload
npm run dev

# Build de produccion (verifica links rotos)
npm run build

# Servir el build localmente
npm run start

El build de produccion (npm run build) es mas estricto que el servidor de desarrollo:

Detecta links rotos (falla con error)
Genera archivos estaticos optimizados

Despliegue

La documentacion se despliega automaticamente a GitLab Pages cuando se hace push a la rama main:

Push a main activa el pipeline de GitLab CI
Stage build: instala dependencias y ejecuta npm run build
Stage deploy: publica el build en GitLab Pages

No se requiere intervencion manual. Simplemente haz merge de tu MR a main.

Checklist para Nuevos Documentos

Archivo .mdx en la carpeta correcta
Frontmatter completo (title, description, order, sidebar_label)
Links internos usan rutas relativas
Bloques de codigo tienen lenguaje especificado
Diagramas Mermaid renderizan correctamente en npm run dev
npm run build pasa sin errores