Contribuir a la Documentación

Inicio Rápido

# 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 estará disponible en http://localhost:3333 con hot-reload.

Stack Técnico

Estructura del Proyecto

Crear un Nuevo Documento

1. Crear el archivo MDX

Crea un archivo .mdx en la carpeta correspondiente dentro de ambos idiomas:

# Ejemplo: nueva guia (ES + EN)
touch content/es/tecnico/guias/mi-nueva-guia.mdx
touch content/en/tecnico/guias/mi-nueva-guia.mdx

2. Agregar frontmatter

Todo documento debe incluir frontmatter al inicio:

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

# Titulo del Documento

Contenido aqui...

3. Verificar en la navegación

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

Sistema de Diagramas Premium

nvito-docs usa un sistema de diagramas basado en componentes React que reemplaza completamente a Mermaid. Los diagramas son interactivos, responsivos, accesibles y consistentes con el design system del sitio.

Arquitectura del sistema

El sistema se compone de 3 capas:

Primitivos (building blocks)

Los 6 primitivos base que componen todos los diagramas:

Componentes compuestos

Diagramas completos con tipado estricto, definidos en src/components/diagrams/types.ts:

Presets de color

Los colores semanticos estan centralizados en src/components/diagrams/presets.ts:

Como crear un diagrama nuevo

Paso 1: Crear el wrapper

Crea un archivo en src/components/diagrams/{sección}/{nombre}-wrappers.tsx:

import { HierarchyDiagram } from '../hierarchy-diagram';
import type { HierarchyNode, HierarchyEdge } from '../types';

const nodes: HierarchyNode[] = [
  { id: 'api', label: 'nvito-api', description: 'Backend NestJS', type: 'service' },
  { id: 'admin', label: 'nvito-admin', description: 'Panel admin', type: 'app' },
  { id: 'db', label: 'PostgreSQL', type: 'database' },
];

const edges: HierarchyEdge[] = [
  { from: 'admin', to: 'api', label: 'REST' },
  { from: 'api', to: 'db' },
];

/** Ejemplo de diagrama de arquitectura */
export function MiDiagramaEjemplo() {
  return (
    <HierarchyDiagram
      title="Arquitectura Ejemplo"
      direction="top-down"
      nodes={nodes}
      edges={edges}
    />
  );
}

Paso 2: Registrar en el mapa MDX

Agrega el import y la entrada al mapa en src/components/mdx/index.ts:

// Agregar import
import { MiDiagramaEjemplo } from '@/components/diagrams/{sección}/{nombre}-wrappers';

// Agregar al objeto mdxComponents
export const mdxComponents = {
  // ... componentes existentes
  MiDiagramaEjemplo,
} as const;

Paso 3: Usar en MDX

En el archivo .mdx, usa el componente directamente:

<MiDiagramaEjemplo />

Reglas importantes

• NUNCA usar bloques ```mermaid para diagramas nuevos. Usar componentes React premium.
• Arrays de objetos complejos NO se pueden pasar inline desde MDX. Siempre crear wrappers.
• Importar componentes desde rutas relativas dentro de los wrappers (../sequence-diagram, no @/components/diagrams/).
• Un wrapper por sección: agrupar todos los diagramas de un documento en un solo archivo {nombre}-wrappers.tsx.
• Exportar funciones nombradas (no default exports) con nombres descriptivos usando PascalCase.

Componentes MDX legacy (solo lectura)

Estos componentes existen para compatibilidad con contenido antiguo. No usar en documentos nuevos:

Componentes MDX Disponibles

Además de los diagramas premium, estos componentes estan disponibles en todo archivo MDX:

Convenciones de Escritura

Idioma

• El contenido se escribe en español (ES) e inglés (EN) simultaneamente.
• Terminos técnicos se mantienen en su idioma original: middleware, guard, hook, query, etc.
• Nombres de código se escriben tal cual: ClerkAuthGuard, createEvent, user_roles.
• Ortografía correcta en texto español: usar acentos (á, é, í, ó, ú), eñe (ñ) y diéresis (ü) donde corresponda.

Formato

• Titulos: Usa ## para secciones principales, ### para subsecciones.
• Código inline: Usa backticks para nombres de código: apiClient, EventsService.
• Bloques de código: Siempre específica el lenguaje (typescript, bash, sql, json, yaml).
• Tablas: Usa tablas Markdown para comparaciones y listados estructurados.
• Links internos: Usa rutas relativas dentro del contenido.
• MDX: No usar <= o >= fuera de bloques de código (causa errores de parseo MDX).

Estructura de documento

1. Frontmatter con title, description, order, sidebar_label
2. Titulo H1 (puede ser diferente al frontmatter title)
3. Secciones principales con ##
4. Diagramas premium donde aporten claridad
5. Links internos a documentos relacionados

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)

Scripts Disponibles

# Servidor de desarrollo con hot-reload
npm run dev

# Build de producción (100% estático, verifica links rotos)
npm run build

# Servir el build localmente
npm run start

# Verificar tipos TypeScript
npm run typecheck

# Actualizar metricas desde los proyectos
npm run update-metrics

# Validar links internos y externos
npm run validate-links

El build de producción (npm run build) es más estricto que el servidor de desarrollo:

• Detecta links rotos (falla con error)
• Genera archivos estáticos optimizados para Cloudflare Pages
• Ejecuta Pagefind para indexar contenido de búsqueda

Despliegue

La documentación se despliega automáticamente a Cloudflare Pages cuando se hace push a la rama main:

1. Push a main activa el build en Cloudflare Pages
2. Cloudflare ejecuta npm run build generando output estático
3. El sitio se pública automáticamente en el dominio configurado
4. Pagefind indexa el contenido para búsqueda full-text

No se requiere intervención manual. Simplemente haz merge de tu MR a main.

i18n (Internacionalización)

Todo contenido debe existir en ambos idiomas:

• Español: content/es/{sección}/{documento}.mdx
• Inglés: content/en/{sección}/{documento}.mdx

Las rutas se generan automáticamente con el prefijo /{locale}/:

• /es/tecnico/guias/desarrollo-local
• /en/tecnico/guias/desarrollo-local

El sitio detecta automáticamente el idioma del navegador (navigator.language) y redirige al locale correspondiente. El usuario puede cambiar manualmente con el LocaleSwitch en el navbar.

Checklist para Nuevos Documentos

• Archivo .mdx en la carpeta correcta para ambos idiomas (ES + EN)
• Frontmatter completo (title, description, order, sidebar_label)
• Links internos usan rutas relativas
• Bloques de código tienen lenguaje especificado
• Diagramas usan componentes premium (no Mermaid)
• Wrappers de diagramas registrados en src/components/mdx/index.ts
• npm run build pasa sin errores
• Contenido revisado en ambos idiomas