RPGRoll — Documentación (UI)

Sitio de documentación de todo el ecosistema RPGRoll (core + los 18 addons), hecho con React + Vite + TypeScript + Tailwind CSS v4, componentizado con componentes propios (sin librerías de UI de terceros). Pensado para ser autocontenido y fácil de mover a otro repositorio o hostearlo donde sea — no tiene backend ni dependencias del resto del proyecto Java. Publicado en rpg-roll-docs.vercel.app.

Desarrollo

npm install
npm run dev

Build de producción

npm run build

Corre tsc -b (typecheck) y después vite build. Genera un dist/ estático (HTML/CSS/JS, sin backend) que se puede servir desde cualquier lado — Vercel, Nginx, GitHub Pages, Netlify, o simplemente abriendo dist/index.html directamente (el build usa rutas relativas, base: "./" en vite.config.ts).

npm run preview   # sirve el build de dist/ localmente para verificarlo

Estructura

src/
├── content/            Datos de la documentación (comandos, permisos, config, navegación, índice de búsqueda)
├── components/
│   ├── ui/                Componentes base reutilizables (CodeBlock, Badge, Callout, Table, Card, YamlBuilder, ...)
│   └── layout/             Layout, Sidebar, Topbar, SearchBar
├── hooks/               useRoute (enrutador propio sin dependencias), useTheme (modo oscuro/claro)
├── pages/               Una página por sección de la documentación (31 páginas: introducción, arquitectura,
│                        sistemas del core, y una por cada uno de los 18 addons)
└── App.tsx              Enruta cada slug del sidebar a su página

Navegación

No usa React Router — es un enrutador por ruta hecho a mano (src/hooks/useRoute.ts): cada página vive en /<slug> y el #id queda libre para los anchors de sección de SectionHeading. Los enlaces antiguos /#page/<slug> se reescriben solos. npm run build termina con scripts/prerender.mjs, que escribe un dist/<slug>/index.html por página (título, descripción y canónica propios), el 404.html, el sitemap y el robots; sin ese paso las URLs directas darían 404 en Vercel. Agregar una página nueva:

1. Agregar la entrada en src/content/nav.ts (aparece en la sidebar automáticamente).
2. Crear el componente en src/pages/, recibiendo { onNavigate }: { onNavigate: (slug: string) => void } como prop para poder linkear a otras páginas.
3. Agregar el case correspondiente en el switch de App.tsx.
4. Agregar su descripción en src/content/seo.ts (si falta, el build avisa).

Buscador global (Ctrl/Cmd+K)

src/components/layout/SearchBar.tsx es un buscador tipo "command palette": busca por substring contra src/content/search.ts, que indexa dos niveles por página —el título (desde nav.ts) y cada SectionHeading dentro de esa página (id + texto)— y navega directo a la sección elegida. Si agregás una SectionHeading nueva en cualquier página, agregá también su entrada en search.ts (llamando al helper h(slug, headingLabel, id)) para que sea buscable; si no, la página sigue siendo buscable por título, pero esa sección puntual no aparecerá en los resultados.

La navegación por hash es asincrónica (depende del evento hashchange del navegador), así que el scroll a la sección elegida usa un poll con reintentos (scrollToHeadingWhenReady) en vez de un solo setTimeout — la sección puede no existir todavía en el DOM en el instante en que se hace click en un resultado.

Verificación de dependencias (npm run check:deps)

Los ejemplos de plugin.yml que muestran las páginas de los addons están escritos a mano en el JSX, así que se desincronizan del proyecto Java sin que nada lo note. El síntoma es silencioso: Bukkit ignora sin avisar un softdepend que apunta a un plugin inexistente, de modo que un ejemplo con el nombre equivocado se copia, parece funcionar, y rompe el orden de carga de forma intermitente más adelante.

npm run check:deps

scripts/check-plugin-deps.mjs descarga los plugin.yml reales de DarkSack/RPGRollSack y los compara contra dos lugares:

1. La tabla addonDependencies de src/content/integrations.ts, que alimenta la página de Integraciones.
2. El bloque depend:/softdepend: embebido en la página de cada addon.

Compara como conjuntos (reordenar una línea del plugin.yml no es un error) y sale con código 1 si algo difiere, o 2 si no pudo consultar el repositorio. No necesita dependencias ni token: el repo del proyecto Java es público y el script importa los .ts con el type stripping nativo de Node.

La fuente de verdad es el plugin.yml del proyecto Java. Si el check falla, lo que hay que corregir es la documentación.

Corre en CI (.github/workflows/ci.yml) en cada PR y también una vez por semana, porque la documentación puede quedar desactualizada sin que este repo cambie — lo que se mueve es el otro.

Si agregás un addon nuevo, sumá su carpeta de módulo al mapa MODULES del script.

Actualizar contenido

La mayoría de los datos "tabulares" (comandos, permisos, claves de configuración) viven en src/content/*.ts como arrays tipados — no hace falta tocar JSX para agregar o corregir una fila. El texto explicativo de cada página, y los bloques de código YAML de ejemplo, viven directamente en src/pages/*.tsx.

Cada addon con contenido YAML configurable (ítems, encantamientos, mobs, hechizos, etc.) tiene, además de los ejemplos "curados" en su página, un bloque reference_full.yml que documenta todos los campos disponibles de un solo tipo de contenido — ese archivo existe también de verdad en <addon>/src/main/resources/ del proyecto Java; si agregás un campo nuevo a un parser, actualizá los dos lados.

Componentes de UI (src/components/ui)

Componente	Para qué
PageHeader	Título + intro de cada página
SectionHeading	Encabezado de sección con anchor #id (usado por el buscador y por links cruzados)
Callout	Recuadro de aviso (tone: info / tip / warning)
CodeBlock	Bloque de código con resaltado simple + botón de copiar
CopyButton	Botón de copiar reutilizable (usado dentro de CodeBlock y YamlBuilder)
Table / Thead / Th / Tr / Td	Tabla básica con el estilo del sitio
Card / CardGrid	Tarjetas para listados (ej. addons en Home)
Badge	Etiqueta pequeña (permisos, tags)
Kbd	Estilo de tecla/comando inline
PrevNext	Navegación anterior/siguiente al pie de cada página
YamlBuilder	Formulario visual que genera YAML en vivo para los campos "planos" de un tipo de contenido

Tema claro/oscuro

useTheme persiste la preferencia en localStorage y aplica la clase dark en <html>; todos los componentes usan las variantes dark: de Tailwind, no un sistema de temas separado.