Guía de Contribución a la Documentación

¡Bienvenido a la Guía de Contribución para la Documentación de Next.js! Estamos emocionados de tenerte aquí.

Esta página proporciona instrucciones sobre cómo editar la documentación de Next.js. Nuestro objetivo es asegurar que todos en la comunidad se sientan capacitados para contribuir y mejorar nuestros documentos.

¿Por qué contribuir?

El trabajo de código abierto nunca termina, y tampoco la documentación. Contribuir a la documentación es una buena manera para que los principiantes se involucren en el código abierto y para que los desarrolladores experimentados aclaren temas más complejos mientras comparten su conocimiento con la comunidad.

Al contribuir a la documentación de Next.js, estás ayudándonos a construir un recurso de aprendizaje más robusto para todos los desarrolladores. Ya sea que hayas encontrado un error tipográfico, una sección confusa o hayas notado que falta un tema en particular, tus contribuciones son bienvenidas y apreciadas.

Cómo contribuir

El contenido de la documentación se encuentra en el repositorio de Next.js. Para contribuir, puedes editar los archivos directamente en GitHub o clonar el repositorio y editar los archivos localmente.

Flujo de trabajo en GitHub

Si eres nuevo en GitHub, te recomendamos leer la Guía de Código Abierto de GitHub para aprender cómo bifurcar un repositorio, crear una rama y enviar una solicitud de extracción (pull request).

Es bueno saberlo: El código subyacente de la documentación reside en una base de código privada que se sincroniza con el repositorio público de Next.js. Esto significa que no puedes previsualizar la documentación localmente. Sin embargo, verás tus cambios en nextjs.org después de fusionar una solicitud de extracción.

Escribiendo en MDX

La documentación está escrita en MDX, un formato de markdown que soporta sintaxis JSX. Esto nos permite incrustar componentes React en la documentación. Consulta la Guía de Markdown de GitHub para una descripción rápida de la sintaxis de markdown.

VSCode

Previsualizando cambios localmente

VSCode tiene un previsualizador de markdown incorporado que puedes usar para ver tus ediciones localmente. Para habilitar el previsualizador para archivos MDX, necesitarás agregar una opción de configuración a tus ajustes de usuario.

Abre la paleta de comandos (⌘ + ⇧ + P en Mac o Ctrl + Shift + P en Windows) y busca Preferences: Open User Settings (JSON).

Luego, agrega la siguiente línea a tu archivo settings.json:

{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

Después, abre la paleta de comandos nuevamente y busca Markdown: Preview File o Markdown: Open Preview to the Side. Esto abrirá una ventana de previsualización donde podrás ver tus cambios formateados.

Extensiones

También recomendamos las siguientes extensiones para usuarios de VSCode:

• MDX: Intellisense y resaltado de sintaxis para MDX.
• Prettier: Formatea archivos MDX al guardar.

Proceso de revisión

Una vez que hayas enviado tu contribución, los equipos de Next.js o Experiencia del Desarrollador revisarán tus cambios, proporcionarán retroalimentación y fusionarán la solicitud de extracción cuando esté lista.

Por favor, háznos saber si tienes alguna pregunta o necesitas asistencia adicional en los comentarios de tu PR. ¡Gracias por contribuir a la documentación de Next.js y ser parte de nuestra comunidad!

Consejo: Ejecuta pnpm prettier-fix para ejecutar Prettier antes de enviar tu PR.

Estructura de archivos

La documentación utiliza enrutamiento basado en archivos. Cada carpeta y archivo dentro de /docs representa un segmento de ruta. Estos segmentos se utilizan para generar las URL, la navegación y las migas de pan.

La estructura de archivos refleja la navegación que ves en el sitio, y por defecto, los elementos de navegación se ordenan alfabéticamente. Sin embargo, podemos cambiar el orden de los elementos anteponiendo un número de dos dígitos (00-) al nombre de la carpeta o archivo.

Por ejemplo, en la Referencia de API de funciones, las páginas se ordenan alfabéticamente porque facilita a los desarrolladores encontrar una función específica:

04-functions
├── after.mdx
├── cacheLife.mdx
├── cacheTag.mdx
└── ...

Pero, en la sección de enrutamiento, los archivos tienen prefijos con números de dos dígitos, ordenados en el orden en que los desarrolladores deberían aprender estos conceptos:

01-routing
├── 01-defining-routes.mdx
├── 02-pages.mdx
├── 03-layouts-and-templates.mdx
└── ...

Para encontrar rápidamente una página, puedes usar ⌘ + P (Mac) o Ctrl + P (Windows) para abrir la barra de búsqueda en VSCode. Luego, escribe el slug de la página que estás buscando. Ej. defining-routes

¿Por qué no usar un manifiesto?

Consideramos usar un archivo de manifiesto (otra forma popular de generar la navegación de la documentación), pero descubrimos que un manifiesto se desincronizaría rápidamente con los archivos. El enrutamiento basado en archivos nos obliga a pensar en la estructura de la documentación y se siente más nativo para Next.js.

Metadatos

Cada página tiene un bloque de metadatos en la parte superior del archivo separado por tres guiones.

Campos requeridos

Los siguientes campos son requeridos:

---
title: Título de la página
description: Descripción de la página
---

Es una buena práctica limitar el título de la página a 2-3 palabras (ej. Optimización de imágenes) y la descripción a 1-2 oraciones (ej. Aprende cómo optimizar imágenes en Next.js).

Campos opcionales

Los siguientes campos son opcionales:

---
nav_title: Título del elemento de navegación
source: app/building-your-application/optimizing/images
related:
  description: Consulta la referencia de API del componente de imagen.
  links:
    - app/api-reference/components/image
version: experimental
---

Documentación de App y Pages

Dado que la mayoría de las características en el App Router y el Pages Router son completamente diferentes, su documentación para cada uno se mantiene en secciones separadas (02-app y 03-pages). Sin embargo, hay algunas características que son compartidas entre ellos.

Páginas compartidas

Para evitar duplicación de contenido y el riesgo de que el contenido se desincronice, utilizamos el campo source para extraer contenido de una página a otra. Por ejemplo, el componente <Link> se comporta mayormente igual en App y Pages. En lugar de duplicar el contenido, podemos extraer el contenido de app/.../link.mdx a pages/.../link.mdx:

---
title: <Link>
description: Referencia de API para el componente <Link>.
---

Esta referencia de API te ayudará a entender cómo usar las props
y opciones de configuración disponibles para el Componente Link.

---
title: <Link>
description: Referencia de API para el componente <Link>.
source: app/api-reference/components/link
---

{/* NO EDITES ESTA PÁGINA. */}
{/* El contenido de esta página se extrae de la fuente anterior. */}

Por lo tanto, podemos editar el contenido en un solo lugar y que se refleje en ambas secciones.

Contenido compartido

En páginas compartidas, a veces puede haber contenido que es específico del App Router o del Pages Router. Por ejemplo, el componente <Link> tiene una prop shallow que solo está disponible en Pages pero no en App.

Para asegurarnos de que el contenido solo se muestre en el router correcto, podemos envolver bloques de contenido en componentes <AppOnly> o <PagesOnly>:

Este contenido es compartido entre App y Pages.

<PagesOnly>

Este contenido solo se mostrará en la documentación de Pages.

</PagesOnly>

Este contenido es compartido entre App y Pages.

Es probable que uses estos componentes para ejemplos y bloques de código.

Bloques de código

Los bloques de código deben contener un ejemplo mínimo funcional que pueda copiarse y pegarse. Esto significa que el código debe poder ejecutarse sin ninguna configuración adicional.

Por ejemplo, si estás mostrando cómo usar el componente <Link>, debes incluir la declaración import y el componente <Link> mismo.

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

Siempre ejecuta los ejemplos localmente antes de comprometerlos. Esto asegurará que el código esté actualizado y funcione.

Idioma y nombre de archivo

Los bloques de código deben tener un encabezado que incluya el idioma y el filename. Agrega una prop filename para renderizar un ícono especial de Terminal que ayuda a los usuarios a orientarse sobre dónde ingresar el comando. Por ejemplo:

```bash filename="Terminal"
npx create-next-app
```

La mayoría de los ejemplos en la documentación están escritos en tsx y jsx, y algunos en bash. Sin embargo, puedes usar cualquier idioma soportado, aquí está la lista completa.

Al escribir bloques de código en JavaScript, usamos las siguientes combinaciones de idioma y extensión.

Es bueno saberlo:

• Asegúrate de usar la extensión js con código JSX en archivos JavaScript.
• Por ejemplo, ```jsx filename="app/layout.js"

Conmutador TS y JS

Agrega un conmutador de idioma para alternar entre TypeScript y JavaScript. Los bloques de código deben ser primero en TypeScript con una versión en JavaScript para acomodar a los usuarios.

Actualmente, escribimos ejemplos de TS y JS uno después del otro, y los vinculamos con la prop switcher:

```tsx filename="app/page.tsx" switcher

```

```jsx filename="app/page.js" switcher

```

Es bueno saberlo: Planeamos compilar automáticamente fragmentos de TypeScript a JavaScript en el futuro. Mientras tanto, puedes usar transform.tools.

Resaltado de líneas

Se pueden resaltar líneas de código. Esto es útil cuando quieres llamar la atención sobre una parte específica del código. Puedes resaltar líneas pasando un número a la prop highlight.

Línea única: highlight={1}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

Múltiples líneas: highlight={1,3}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

Rango de líneas: highlight={1-5}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">About</Link>
}

Íconos

Los siguientes íconos están disponibles para usar en la documentación:

<Check size={18} />
<Cross size={18} />

Salida:

No usamos emojis en la documentación.

Notas

Para información que es importante pero no crítica, usa notas. Las notas son una buena manera de agregar información sin distraer al usuario del contenido principal.

> **Es bueno saberlo**: Esta es una nota de una sola línea.

> **Es bueno saberlo**:
>
> - También usamos este formato para notas de varias líneas.
> - A veces hay varios elementos que vale la pena conocer o tener en cuenta.

Salida:

Es bueno saberlo: Esta es una nota de una sola línea.

Es bueno saberlo:

• También usamos este formato para notas de varias líneas.
• A veces hay varios elementos que vale la pena conocer o tener en cuenta.

Enlaces relacionados

Los enlaces relacionados guían el viaje de aprendizaje del usuario agregando enlaces a los siguientes pasos lógicos.

• Los enlaces se mostrarán en tarjetas debajo del contenido principal de la página.
• Los enlaces se generarán automáticamente para páginas que tienen páginas secundarias.

Crea enlaces relacionados usando el campo related en los metadatos de la página.

---
related:
  description: Aprende cómo comenzar rápidamente con tu primera aplicación.
  links:
    - app/building-your-application/routing/defining-routes
    - app/building-your-application/data-fetching
    - app/api-reference/file-conventions/page
---

Campos anidados

Diagramas

Los diagramas son una excelente manera de explicar conceptos complejos. Usamos Figma para crear diagramas, siguiendo la guía de diseño de Vercel.

Los diagramas actualmente se encuentran en la carpeta /public en nuestro sitio privado de Next.js. Si deseas actualizar o agregar un diagrama, por favor abre un problema en GitHub con tus ideas.

Componentes personalizados y HTML

Estos son los componentes React disponibles para la documentación: <Image /> (next/image), <PagesOnly />, <AppOnly />, <Cross />, y <Check />. No permitimos HTML crudo en la documentación aparte de la etiqueta <details>.

Si tienes ideas para nuevos componentes, por favor abre un problema en GitHub.

Guía de estilo

Esta sección contiene pautas para escribir documentación para aquellos que son nuevos en la escritura técnica.

Plantillas de página

Si bien no tenemos una plantilla estricta para las páginas, hay secciones de página que verás repetidas en la documentación:

• Resumen: El primer párrafo de una página debe decirle al usuario qué es la característica y para qué se usa. Seguido de un ejemplo mínimo funcional o su referencia de API.
• Convención: Si la característica tiene una convención, debe explicarse aquí.
• Ejemplos: Muestra cómo se puede usar la característica con diferentes casos de uso.
• Tablas de API: Las páginas de API deben tener una tabla de resumen al final de la página con enlaces de salto a secciones (cuando sea posible).
• Próximos pasos (Enlaces relacionados): Agrega enlaces a páginas relacionadas para guiar el viaje de aprendizaje del usuario.

Siéntete libre de agregar estas secciones según sea necesario.

Tipos de Páginas

Las páginas de documentación también se dividen en dos categorías: Conceptuales y de Referencia.

• Páginas Conceptuales se utilizan para explicar un concepto o funcionalidad. Suelen ser más extensas y contener más información que las páginas de referencia. En la documentación de Next.js, estas páginas se encuentran en la sección Construyendo Tu Aplicación.
• Páginas de Referencia se utilizan para explicar una API específica. Suelen ser más breves y enfocadas. En la documentación de Next.js, estas páginas están en la sección Referencia de API.

Bueno saber: Dependiendo de la página a la que estés contribuyendo, puede que necesites seguir un tono y estilo diferentes. Por ejemplo, las páginas conceptuales son más instructivas y utilizan la palabra usted para dirigirse al usuario. Las páginas de referencia son más técnicas, usan palabras más imperativas como "crear, actualizar, aceptar" y tienden a omitir la palabra usted.

Tono

Aquí hay algunas pautas para mantener un estilo y tono consistentes en la documentación:

• Escribe oraciones claras y concisas. Evita divagaciones.
  • Si notas que estás usando muchas comas, considera dividir la oración en varias o usa una lista.
  • Sustituye palabras complejas por otras más simples. Por ejemplo, usar en lugar de utilizar.
• Ten cuidado con la palabra esto. Puede ser ambigua y confusa, no temas repetir el sujeto de la oración si no queda claro.
  • Por ejemplo, Next.js usa React en lugar de Next.js usa esto.
• Usa voz activa en lugar de pasiva. Una oración activa es más fácil de leer.
  • Por ejemplo, Next.js usa React en lugar de React es usado por Next.js. Si te encuentras usando palabras como fue o por, puede que estés usando voz pasiva.
• Evita palabras como fácil, rápido, simple, solo, etc. Esto es subjetivo y puede desmotivar a los usuarios.
• Evita palabras negativas como no, no puedes, no hará, etc. Esto puede desanimar a los lectores.
  • Por ejemplo, "Puedes usar el componente Link para crear enlaces entre páginas" en lugar de "No uses la etiqueta <a> para crear enlaces entre páginas".
• Escribe en segunda persona (usted/tu). Esto resulta más personal y atractivo.
• Usa lenguaje neutro en cuanto al género. Emplea desarrolladores, usuarios o lectores al referirte a la audiencia.
• Si añades ejemplos de código, asegúrate de que estén correctamente formateados y funcionen.

Aunque estas pautas no son exhaustivas, te ayudarán a empezar. Si deseas profundizar en la escritura técnica, consulta el Curso de Escritura Técnica de Google.

¡Gracias por contribuir a la documentación y ser parte de la comunidad de Next.js!