update-docs

Actualizador de la documentación de Next.js

Te guía a través del proceso de actualización de la documentación de Next.js en función de los cambios en el código de la rama activa. Diseñado para que los responsables del mantenimiento revisen las solicitudes de incorporación de cambios (PR) y comprueben que la documentación esté completa.

Inicio rápido

1. Analizar cambios: ejecuta git diff canary...HEAD --stat para ver qué archivos han cambiado
2. Identifica los documentos afectados: asigna los archivos fuente modificados a las rutas de la documentación
3. Revisa cada documento: repasa las actualizaciones con la confirmación del usuario
4. Validar: Ejecutar pnpm lint para comprobar el formato
5. Confirmar: Preparar los cambios en la documentación

Flujo de trabajo: Analizar los cambios en el código

Paso 1: Obtener las diferencias

# See all changed files on this branch
git diff canary...HEAD --stat# See changes in specific areas
git diff canary...HEAD -- packages/next/src/

Paso 2: Identificar los cambios relevantes para la documentación

Busca cambios en estas áreas:

Paso 3: Asignar a los archivos de documentación

Utiliza la correspondencia entre código y documentación en references/CODE-TO-DOCS-MAPPING.md para encontrar los archivos de documentación correspondientes.

Ejemplos de asignaciones:

• src/client/components/image.tsx → docs/01-app/03-api-reference/02-components/image.mdx
• src/server/config-shared.ts → docs/01-app/03-api-reference/05-config/

Flujo de trabajo: Actualizar la documentación existente

Paso 1: Lee la documentación actual

Antes de realizar cambios, lee la documentación existente para comprender:

• La estructura y las secciones actuales
• Los campos de frontmatter que se utilizan
• Si utiliza / para contenido específico del enrutador

Paso 2: Identificar qué hay que actualizar

Las actualizaciones habituales incluyen:

• Nuevas propiedades u opciones: añádelas a la tabla de propiedades y crea una sección que explique su uso
• Cambios en el comportamiento: Actualizar las descripciones y los ejemplos
• Funcionalidades obsoletas: añadir avisos de obsolescencia y orientación para la migración
• Nuevos ejemplos: añadir bloques de código siguiendo las convenciones

Paso 3: Aplicar las actualizaciones con confirmación

Para cada cambio:

1. Mostrar al usuario lo que se va a cambiar
2. Esperar a que el usuario confirme antes de editar
3. Aplicar la modificación
4. Pasa al siguiente cambio

Paso 4: Comprueba si hay contenido compartido

Si el documento utiliza el source patrón de campo (habitual en los documentos del enrutador de páginas), el archivo fuente es el que hay que editar. Ejemplo:

# docs/02-pages/... file with shared content
---
source: app/building-your-application/optimizing/images
---

Edita el código fuente del App Router, no el archivo del Pages Router.

Paso 5: Valida los cambios

pnpm lint          # Check formatting
pnpm prettier-fix  # Auto-fix formatting issues

Flujo de trabajo: Crear la estructura de la documentación de una nueva función

Utiliza este procedimiento cuando añadas documentación para funciones completamente nuevas.

Paso 1: Determina el tipo de documento

Paso 2: Crea el archivo con el nombre adecuado

• Utiliza el formato «kebab-case»: my-new-feature.mdx
• Añade un prefijo numérico si el orden es importante: 05-my-new-feature.mdx
• Colócalo en el directorio correcto según el tipo de función

Paso 3: Utiliza la plantilla adecuada

Plantilla de referencia de la API:

---
title: Feature Name
description: Brief description of what this feature does.
---{/* The content of this doc is shared between the app and pages router. You can use the `Content` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}Brief introduction to the feature.## Reference### Props
| Prop                    | Example            | Type   | Status   |
| ----------------------- | ------------------ | ------ | -------- |
| [`propName`](#propname) | `propName="value"` | String | Required |
#### `propName`Description of the prop.\`\`\`tsx filename="app/example.tsx" switcher
// TypeScript example
\`\`\`\`\`\`jsx filename="app/example.js" switcher
// JavaScript example
\`\`\`

Plantilla de la guía:

---
title: How to do X in Next.js
nav_title: X
description: Learn how to implement X in your Next.js application.
---Introduction explaining why this guide is useful.## PrerequisitesWhat the reader needs to know before starting.## Step 1: First StepExplanation and code example.\`\`\`tsx filename="app/example.tsx" switcher
// Code example
\`\`\`## Step 2: Second StepContinue with more steps...## Next StepsRelated topics to explore.

Paso 4: Añade enlaces relacionados

Actualiza el frontmatter con la documentación relacionada:

related:
  title: Next Steps
  description: Learn more about related features.
  links:
    - app/api-reference/functions/related-function
    - app/guides/related-guide

Convenciones de documentación

Consulta references/DOC-CONVENTIONS.md las reglas completas de formato.

Referencia rápida

Frontmatter (obligatorio):

---
title: Page Title (2-3 words)
description: One or two sentences describing the page.
---

Bloques de código:

\`\`\`tsx filename="app/page.tsx" switcher
// TypeScript first
\`\`\`\`\`\`jsx filename="app/page.js" switcher
// JavaScript second
\`\`\`

Contenido específico del enrutador:

Content only for App Router docs.Content only for Pages Router docs.

Notas:

> **Good to know**: Single line note.> **Good to know**:
>
> - Multi-line note point 1
> - Multi-line note point 2

Lista de comprobación de validación

Antes de confirmar los cambios en la documentación:

• El frontmatter tiene title y description
• Los bloques de código tienen filename el atributo
• Los ejemplos de TypeScript utilizan switcher con la variante JS
• Las tablas de propiedades tienen el formato adecuado
• Los enlaces relacionados apuntan a rutas válidas
• pnpm lint supera las pruebas
• Los cambios se muestran correctamente (si hay vista previa disponible)

Referencias

• references/DOC-CONVENTIONS.md - Reglas completas de frontmatter y formato
• references/CODE-TO-DOCS-MAPPING.md - Correspondencia entre el código fuente y la documentación