• Español

      • Estructura del portal

      El portal tiene tres secciones de primer nivel y dos idiomas. Esta página define esa estructura: qué secciones existen, en qué URL vive cada una y qué páginas se escriben a mano frente a las que genera el build.

      Secciones

      El primer nivel es por género, nunca por equipo ni por área del organigrama. Hay tres secciones y son fijas.

      SecciónURL (es / en)Qué contieneOrigen
      Guías/guides/ / /en/guides/How-tos transversales que involucran a más de un repo o equipoEscrita a mano
      Estándares/standards/ / /en/standards/Normas y criterios comunes: code review, testing, convencionesEscrita a mano
      Repos/repos/ / /en/repos/Catálogo de todos los repos y docs agregadas de los repos registradosGenerada

      Dentro de guides/, las páginas meta del portal viven en /guides/contributing/. Cada tema transversal vive en su propia carpeta, /guides/<tema>/: por ejemplo, la guía de autenticación vivirá en /guides/authentication/ cuando se escriba con el equipo de backend.

      Principios de la estructura

      Tres reglas deciden dónde va cada carpeta. Se aplican en los dos idiomas por igual.

      PrincipioQué significaEjemplo
      El género manda en el primer nivelLas secciones son guides/, standards/ y repos/. Nunca un equipo ni un área: los equipos se renombran y las URLs se rompenstandards/code-review/, no backend/code-review
      La disciplina es una hojaBackend, frontend, QA e infra aparecen debajo de un tema, no como raízstandards/code-review/backend
      Primero compartido, dividir despuésUn tema es una sola página hasta que su contenido diverge de verdad. La URL del tema no cambia al dividirse/standards/graphql/ sigue igual tras dividirse

      Estructura de URLs

      El idioma por defecto es español y se sirve sin prefijo. El inglés vive bajo /en/.

      Español (por defecto)Inglés
      Home//en/
      Sección/guides//en/guides/
      Página/guides/contributing//en/guides/contributing/

      Reglas de los slugs:

      • El slug es siempre en inglés, ASCII y kebab-case: code-review, register-a-repo. Un slug con acentos se percent-encodea en las URLs y se vuelve ilegible.
      • El slug es idéntico en los dos idiomas. Solo cambian el contenido y las etiquetas de navegación, nunca la ruta.
      • El slug de un repo agregado (/repos/<slug>/) no cambia nunca, ni cuando el repo se mueve en GitLab. Cómo registrar un repo explica por qué.

      Las rutas que sí cambian se cubren con redirects (@rspress/plugin-client-redirects), para que un enlace ya compartido no muera.

      Páginas escritas a mano y páginas generadas

      RutaCómo se mantiene
      docs/es/** y docs/en/** (salvo repos/)Escritas a mano, un archivo por idioma
      docs/*/repos/Generada por el build; está en .gitignore; nunca se edita a mano

      docs/*/repos/ se reconstruye desde repos-inventory.json (el catálogo) y docs-manifest.yaml (la agregación). pnpm run gen genera el índice del catálogo; pnpm run aggregate, las docs agregadas.

      Toda página escrita a mano existe en los dos idiomas con el mismo slug. El build falla y nombra el archivo faltante cuando una página existe en un idioma y no en el otro. Las páginas bajo repos/ están exentas: se copian tal como las escribió su repo de origen.

      Cómo se define la navegación

      • _nav.json (uno por idioma) define la barra superior. Los enlaces se escriben sin el prefijo de idioma: /guides/, no /en/guides/. Rspress agrega el prefijo por idioma.
      • _meta.json (uno por carpeta e idioma) define el orden y las etiquetas de la barra lateral.

      Relacionado