• English

      • Portal structure

      The portal has three top-level sections and two languages. This page defines that structure: which sections exist, the URL each one lives at, and which pages are hand-written versus generated by the build.

      Sections

      The top level is by genre, never by team or org unit. There are three sections and they are fixed.

      SectionURL (es / en)What it holdsSource
      Guides/guides/ / /en/guides/Cross-cutting how-tos that involve more than one repo or teamHand-written
      Standards/standards/ / /en/standards/Shared norms and criteria: code review, testing, conventionsHand-written
      Repos/repos/ / /en/repos/Catalog of every repo, plus aggregated docs from registered reposGenerated

      Inside guides/, the portal's meta pages live under /guides/contributing/. Each cross-cutting topic lives in its own directory, /guides/<topic>/: for example, the authentication guide will live at /guides/authentication/ once it is written with the backend team.

      Structure principles

      Three rules decide where each directory goes. They apply to both languages alike.

      PrincipleWhat it meansExample
      Genre owns the top levelThe sections are guides/, standards/ and repos/. Never a team or an org unit: teams get renamed and URLs breakstandards/code-review/, not backend/code-review
      Discipline is a leafBackend, frontend, QA and infra appear beneath a topic, not as a rootstandards/code-review/backend
      Shared first, split lateA topic is a single page until its content genuinely diverges. The topic URL does not change when it splits/standards/graphql/ stays the same after a split

      URL structure

      The default language is Spanish and is served without a prefix. English lives under /en/.

      Spanish (default)English
      Home//en/
      Section/guides//en/guides/
      Page/guides/contributing//en/guides/contributing/

      Slug rules:

      • The slug is always English, ASCII and kebab-case: code-review, register-a-repo. An accented slug percent-encodes into unreadable URLs.
      • The slug is identical across both languages. Only the content and the navigation labels change, never the path.
      • An aggregated repo's slug (/repos/<slug>/) never changes, not even when the repo moves in GitLab. How to register a repo explains why.

      Paths that do change are covered by redirects (@rspress/plugin-client-redirects), so a link that was already shared does not die.

      Hand-written and generated pages

      PathHow it is maintained
      docs/es/** and docs/en/** (except repos/)Hand-written, one file per language
      docs/*/repos/Generated by the build; listed in .gitignore; never hand-edited

      docs/*/repos/ is rebuilt from repos-inventory.json (the catalog) and docs-manifest.yaml (the aggregation). pnpm run gen generates the catalog index; pnpm run aggregate generates the aggregated docs.

      Every hand-written page exists in both languages under the same slug. The build fails and names the missing file when a page exists in one language and not the other. Pages under repos/ are exempt: they are copied as their source repo wrote them.

      How navigation is defined

      • _nav.json (one per language) defines the top bar. Links are written without the language prefix: /guides/, not /en/guides/. Rspress adds the prefix per language.
      • _meta.json (one per directory and language) defines the sidebar order and labels.