#How to contribute to the portal

This guide covers the full flow to add or edit a portal page: decide where it lives, write it in Spanish and English, and validate it before the MR.

#Prerequisites

• Access to the crehana-team/platform/engineering-docs repo
• Node.js 20 or later
• pnpm (this repo uses pnpm; do not add a second package manager)

Install the dependencies once:

pnpm install

#Decide where your page goes

The rule in one sentence: if your content is about one repo, it lives in that repo; if it is about how we all work, it lives here, grouped by genre.

Three rules hold that table up:

1. Genre owns the top level. The sections are guides/, standards/ and repos/. Never a team or an org unit: teams get renamed and URLs break.
2. Discipline is a leaf, not a root. Backend, frontend, QA and infra appear beneath a topic: standards/code-review/backend, never backend/code-review.
3. Shared first, split late. Write one page per topic. Split it by discipline when the content genuinely diverges, not before. The topic URL stays the same either way.

#Write the page in both languages

The portal serves Spanish at unprefixed URLs and English under /en/. Slugs are identical across languages: always English, ASCII and kebab-case.

1. Create the Spanish page:

   docs/es/guides/cdn/index.md

2. Create its English counterpart, under the same slug:

   docs/en/guides/cdn/index.md

3. Write the Spanish body in LATAM Spanish with technical terms in English. The English page is a full translation.

4. Pick one page type and do not mix types. The templates are in page templates.

The build fails when a page exists in one language and not the other, and it names the missing file. Pages aggregated from other repos are exempt: they are served as their source repo wrote them.

#Validate before the MR

pnpm run build

You should see the three checks pass before Rspress compiles:

✓ catalog: 2 repos, 0 registered for aggregation
✓ i18n parity: 8 page(s) present in es + en
✓ provenance: 0 aggregated page(s) traced to a source

A broken build means a dead link, invalid frontmatter, or a page without its counterpart. Fix it before asking for review.

To preview the portal while you write:

pnpm run dev

#Open the MR

The team that owns the topic approves. An MR adding a cross-cutting guide needs approval from the teams that will use it, not only from whoever wrote it.

#Troubleshooting

#Related

• Portal structure — the sections, the URLs, and what is generated
• Page templates — the anatomy of each page type
• How to register a repo — catalog and aggregation