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

¡Bienvenido a la Guía de Contribución a 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 nuestra documentación.

¿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).

Bueno saber: El código subyacente de la documentación vive 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 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 visió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.
• Grammarly: Corrector gramatical y ortográfico.
• 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 más asistencia 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 correr Prettier antes de enviar tu PR.

Estructura de archivos

La documentación usa enrutamiento por sistema de archivos. Cada carpeta y archivo dentro de /docs representa un segmento de ruta. Estos segmentos se usan 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:

03-functions
├── cookies.mdx
├── draft-mode.mdx
├── fetch.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:

02-routing
├── 01-defining-routes.mdx
├── 02-pages-and-layouts.mdx
├── 03-linking-and-navigating.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 encontramos que un manifiesto se desincronizaría rápidamente con los archivos. El enrutamiento por sistema de 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 obligatorios

Los siguientes campos son obligatorios:

---
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
---

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, usamos 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 debería 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 confirmarlos. 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.

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

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 enlazamos con la prop switcher:

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

```

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

```

Bueno saber: 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.

> **Bueno saber**: Esta es una nota de una sola línea.

> **Bueno saber**:
>
> - También usamos este formato para notas de múltiples líneas.
> - A veces hay múltiples elementos que vale la pena conocer o tener en cuenta.

Salida:

Bueno saber: Esta es una nota de una sola línea.

Bueno saber:

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

Enlaces relacionados

Los enlaces relacionados guían el 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 hijas. Por ejemplo, la sección Optimización tiene enlaces a todas sus páginas hijas.

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 viven 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 además 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:

• Descripción general: 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 descripción general al final de la página con enlaces de salto a sección (cuando sea posible).
• Próximos pasos (Enlaces relacionados): Agrega enlaces a páginas relacionadas para guiar el aprendizaje del usuario.

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

Tipos de Páginas

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

• Páginas Conceptuales se utilizan para explicar un concepto o característica. 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 se encuentran en la sección Referencia de API.

Es bueno saber: Dependiendo de la página a la que esté contribuyendo, puede que necesite seguir un tono y estilo diferente. Por ejemplo, las páginas conceptuales son más instructivas y usan 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:

• Escriba oraciones claras y concisas. Evite divagaciones.
  • Si nota que está usando muchas comas, considere dividir la oración en múltiples frases o usar una lista.
  • Reemplace palabras complejas por otras más simples. Por ejemplo, usar en lugar de utilizar.
• Tenga cuidado con la palabra esto. Puede ser ambigua y confusa, no tema repetir el sujeto de la oración si no queda claro.
  • Por ejemplo, Next.js usa React en lugar de Next.js usa esto.
• Use 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 nota que usa palabras como fue y por, puede estar usando voz pasiva.
• Evite usar palabras como fácil, rápido, simple, solo, etc. Esto es subjetivo y puede desmotivar a los usuarios.
• Evite palabras negativas como no, no puede, no hará, etc. Esto puede desalentar a los lectores.
  • Por ejemplo, "Puede usar el componente Link para crear enlaces entre páginas" en lugar de "No use la etiqueta <a> para crear enlaces entre páginas".
• Escriba en segunda persona (usted/su). Esto es más personal y atractivo.
• Use lenguaje neutral en cuanto al género. Use desarrolladores, usuarios o lectores cuando se refiera a la audiencia.
• Si agrega ejemplos de código, asegúrese de que estén correctamente formateados y funcionen.

Aunque estas pautas no son exhaustivas, deberían ayudarle a comenzar. Si desea profundizar en escritura técnica, consulte el Curso de Escritura Técnica de Google.

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