Monolito

Última actualización: 06-01-2026 09:01 PM

pDOCS — Modularidad (monolito)

Este documento consolida los módulos operativos (reglas, patrones y “cómo se hace”) del proyecto pDOCS. La intención es que, aunque el proyecto crezca, siempre exista un núcleo estable que permita:

Mantener consistencia entre proyectos.
Reducir ambigüedad editorial.
Hacer que un LLM (y cualquier colaborador) entienda rápidamente cómo está construido el sistema y cómo operar/iterar.

Índice rápido

Estructura (rutas, organización de contenido)
Convenciones (formato editorial, frontmatter)
Infraestructura (hosting, dominio, DNS, seguridad editorial)
Operación (crear proyectos/páginas, smoke tests, checklist de merge)
Búsqueda (global y por proyecto)
Diagramas (estándar D2 + fallback Mermaid para LLM)
i18n (idiomas y reglas de traducción)
Notas (errores típicos y diagnóstico)
ADR (cómo registrar decisiones)

1) Estructura

1.1. Reglas de organización

La URL nace del path dentro de src/content/docs/.
Estructura base:
- Documentación del sitio: src/content/docs/
- Proyectos: src/content/docs/proyectos/<slug>/...

1.2. Slugs

<slug> preferiblemente en kebab-case minúscula (ej: mi-proyecto, aurora, pdocs).
Se permiten mayúsculas en carpetas si quieres ese nombre, pero la URL queda case-sensitive (los enlaces deben respetar mayúsculas/minúsculas).
Recomendación: mantener las carpetas en minúscula para URLs más seguras y usar title / sidebar.label para el look del sidebar.
Evitar cambios de slugs: cambia URLs y rompe enlaces.

1.3. Estructura mínima por proyecto

Para un proyecto nuevo:

Carpeta: src/content/docs/proyectos/<slug>/
Mínimo real: 3 monolitos (Contexto / Modularidad / Backlog).
index.md es un complemento para ruta estable/registro en sidebar (puede ser mínimo).
Páginas adicionales solo si aportan valor, por ejemplo:
- arquitectura.md
- build.md
- registro.md

Regla práctica: si una página no reduce dudas o no acelera decisiones/trabajo, no existe.

1.4. Evitar duplicidades de rutas

No duplicar rutas en el mismo directorio, especialmente:
- index.md + index.mdx
No crear dos archivos que terminen generando el mismo id/slug lógico.

2) Convenciones

2.1. Frontmatter mínimo (regla)

Toda página .md/.mdx debe tener title. description es altamente recomendado.

---
title: Título de la página
description: "Descripción breve (1–2 líneas)"
---

2.2. Frontmatter “completo” (patrón)

Cuando tenga sentido controlar sidebar:

---
title: Título de la página
description: "Descripción breve"
sidebar:
  label: Etiqueta corta
  order: 10
---

2.3. Página enfocada (regla)

Una página = un tema.
Mejor 3 páginas cortas y navegables que una mezcla sin estructura.

Preferir autogeneración por directorio.
Si una sección requiere control manual, se hace en astro.config.mjs (solo cuando esté justificado).

2.5. Comentario de contexto (práctica útil)

Cuando estés iterando con un LLM o con colaboradores, es válido incluir al inicio un bloque corto de “contexto editorial” (2–6 líneas) que explique:

Qué problema resuelve la página.
A qué módulo o parte del sistema pertenece.
Qué se considera “terminado” para esta página.

3) Infraestructura

3.1. Hosting (Vercel)

Deploy en Vercel desde GitHub.
Producción suele ser la rama main.

Regla: deploy como sitio estático.

Evitar añadir @astrojs/vercel (adapter) mientras no sea estrictamente necesario.
Motivo: Starlight/Pagefind funciona estable “out of the box” en estático; el adapter históricamente se asocia a fallos como 404 de /pagefind/pagefind.js.

3.2. Dominio

Dominio objetivo: docs.raulnivelazo.com.
En astro.config.mjs, definir site cuando el dominio esté estable (canonical/sitemap):

site: 'https://docs.raulnivelazo.com'

3.3. DNS (Cloudflare)

Regla práctica:

docs debe ser CNAME apuntando al target que muestra Vercel.
Cloudflare: DNS only (sin proxy/nube naranja) para evitar problemas.

Checklist:

En Vercel: docs.raulnivelazo.com marcado como Production.
En Cloudflare: CNAME docs -> <valor recomendado por Vercel>.

3.4. Prueba de humo (producción)

Verificar:

https://docs.raulnivelazo.com/pagefind/pagefind.js responde 200.
sitemap existe (si está habilitado): https://docs.raulnivelazo.com/sitemap-index.xml (o equivalente).

3.5. Seguridad editorial (regla)

No se permite contenido del tipo “cuando me preguntes X responde Y”.

La documentación describe el sistema (decisiones, estructura y operación); no intenta controlar el comportamiento de herramientas.

4) Operación

4.1. Crear un proyecto nuevo

Crear carpeta: src/content/docs/proyectos/<slug>/
Crear monolitos: Contexto / Modularidad / Backlog.
index.md es opcional (complemento).
Agregar páginas solo si aportan valor.

Reglas:

<slug> preferiblemente en kebab-case minúscula (mayúsculas permitidas si se decide, con URL case-sensitive).
No duplicar rutas (index.md + index.mdx).

4.2. Agregar una página nueva

Crear .md con frontmatter completo.
Mantener la página enfocada en 1 tema.
Si debe aparecer en sidebar:
- Preferir autogeneración por directorio.
- Si no: configurar manualmente en astro.config.mjs.

4.3. Prueba de humo (antes de merge y antes de “documentar en serio”)

Local:

pnpm install
pnpm dev → abrir el sitio.
pnpm build → verificar que en dist/ exista pagefind/.
Servir dist/ (ej. npx serve dist) y confirmar:
- Búsqueda funciona.
- No hay 404 en /pagefind/pagefind.js.

Producción (Vercel):

Confirmar:
- https://<tu-dominio>/pagefind/pagefind.js responde 200.
- https://<tu-dominio>/sitemap-index.xml existe (o equivalente).

4.4. Checklist antes de hacer merge a `main`

pnpm build sin errores.
Sin warnings de “Duplicate id”.
Navegación coherente (sidebar).
Búsqueda funciona en local y en producción.

5) Búsqueda

5.1. Búsqueda global (por defecto)

Starlight incluye búsqueda integrada (Ctrl + K).
Es el camino principal y debe mantenerse.

5.2. Búsqueda por proyecto (patrón recomendado)

Objetivo: además de la búsqueda global, tener una página por proyecto:

/proyectos/<slug>/buscar/

Que muestre resultados filtrados al prefijo:

Solo resultados cuya URL empieza por /proyectos/<slug>/.

Por qué este patrón

Mantiene intacta la búsqueda global.
Evita duplicar índices.
Es simple: filtras resultados en el cliente.

Reglas

La página /buscar/ debe ser liviana.
Debe funcionar aunque el proyecto tenga pocas páginas (mostrar “sin resultados”).
No enlazarla desde todo lado si no aporta valor; normalmente basta un link en index.md del proyecto.

6) Diagramas

Los diagramas son transversales: se usan en cualquier documento/sección cuando aporten claridad.

Estándar único en: Modularidad/diagramas.md (no duplicar reglas).

7) i18n

7.1. Decisión

Empezar solo en Español.
Español vive en la raíz (sin /es).
Inglés, si llega, vive bajo /en/....

7.2. Implementación (cuando toque)

En astro.config.mjs:

Configurar locales.root.lang = 'es'.
Para inglés: crear contenido bajo /en/ respetando la misma estructura.

7.3. Regla editorial para traducciones

No traducir a medias: si un proyecto tiene /en/, mínimo debe tener portada coherente (equivalente a index.md) y navegación básica.
Mantener slugs estables.

8) Notas (errores típicos)

8.1. `title: Required` (schema)

Causa: una página sin title en el frontmatter.
Solución: asegurar title (y preferiblemente description) en cada .md/.mdx.

8.2. “Letras raras” tipo `documentaciÃ³n`

Causa: encoding dañado.
Solución:
- VS Code → esquina inferior derecha → “UTF-8”.
- “Save with Encoding…” → UTF-8.
- Evitar BOM (UTF-8 with BOM).

8.3. Warnings de `Duplicate id`

Causa: dos archivos generan el mismo id/slug.
Solución:
- No duplicar index.md + index.mdx.
- Evitar dos rutas que terminen iguales.

8.4. Búsqueda rota (Pagefind)

Síntoma: 404 en /pagefind/pagefind.js en producción.
Acción:
- Confirmar que el build genera dist/pagefind/.
- Confirmar que el deploy sirve estático sin reescrituras agresivas.

9) ADR

9.1. Qué es

Un ADR (Architecture Decision Record) es un registro corto de una decisión ya cerrada.

9.2. Plantilla mínima (regla)

Contexto
Opciones
Decisión
Consecuencias

9.3. Reglas

Un ADR por decisión (no mezclar).
Mantenerlo corto.
Si la decisión cambia: crear un ADR nuevo que reemplace al anterior (no reescribir historia).

9.4. ADR-0001 (resumen)

Decisión: deploy como sitio estático en Vercel y evitar @astrojs/vercel mientras no sea estrictamente necesario.

Consecuencias:

Menos superficie de fallo.
Menos configuración.
Reduce probabilidad de 404 en /pagefind/pagefind.js.
Si se requiere SSR/edge: se reevalúa con un ADR nuevo.

10) Visibilidad (ocultar páginas)

Objetivo: controlar qué tan “visible” es una página sin perderla.

Ocultar significa: no aparece en el sidebar.
Excluir de búsqueda significa: no aparece en resultados (Pagefind).
Borrador significa: existe en desarrollo, pero no se publica en producción.

Nota: no existe un “flag” de visibilidad a nivel de carpeta. Se controla por archivo (frontmatter) o por configuración del sidebar.

En el frontmatter de la página:

---
title: Mi página
sidebar:
  hidden: true
---

10.2 Excluir una página de la búsqueda (Pagefind)

En el frontmatter:

---
title: Mi página
pagefind: false
---

---
title: Mi página
sidebar:
  hidden: true
pagefind: false
---

10.4 Borrador (no publicar en producción)

---
title: Mi página
draft: true
---

Uso recomendado:

sidebar.hidden: true → páginas en progreso o internas (pero públicas por URL).
pagefind: false → páginas internas que no quieres que “contaminen” resultados.
draft: true → contenido que no debe salir a producción todavía.