Capítulo 452 de 456

Contribution Guide

Core Idea

How to edit and submit changes to the Next.js documentation: file structure, MDX conventions, metadata fields, and style guide.

Key Concepts

  • Docs source: lives in github.com/vercel/next.js/tree/canary/docs, written in MDX; underlying docs code is private/synced, so changes aren't previewable locally beyond MDX rendering.
  • File-system routing: folder/file structure generates URL paths, nav, and breadcrumbs; alphabetical by default, or ordered via a NN- numeric prefix (e.g. 01-installation.mdx).
  • Required frontmatter: title (H1, SEO/OG), description (meta description).
  • Optional frontmatter: nav_title (override nav label), source (pull content from another page, for App/Pages shared content), related (related-links card list), version (experimental/legacy/unstable/RC).
  • Shared pages: use source field to pull one page's content into another (avoids App/Pages duplication); target page gets a "DO NOT EDIT" comment.
  • <AppOnly> / <PagesOnly>: wrap content blocks that only apply to one router within a shared page.
  • Code block conventions: minimum working, runnable examples; filename + language header; package="pnpm|npm|yarn|bun" prop for CLI commands; .js extension for JSX-containing JS files (jsx fence), .tsx for TSX; switcher prop pairs TS/JS versions; highlight={1}/{1,3}/{1-5} for line highlighting.
  • Allowed custom components: <Image />, <PagesOnly />, <AppOnly />, <Cross />, <Check />; raw HTML disallowed except <details>; no emojis in docs.
  • Page types: Conceptual (longer, instructional, "you") vs. Reference (shorter, imperative, API-focused).

Code Examples

---
nav_title: Nav Item Title
source: app/building-your-application/optimizing/images
related:
  description: See the image component API reference.
  links:
    - app/api-reference/components/image
version: experimental
---
  • O que demonstra: uso combinado dos campos opcionais de frontmatter.
---
title: <Link>
description: API reference for the <Link> component.
source: app/api-reference/components/link
---

{/* DO NOT EDIT THIS PAGE. */}
{/* The content of this page is pulled from the source above. */}
  • O que demonstra: como uma página "pages" reaproveita conteúdo de uma página "app" via source, evitando duplicação.

Reference Tables

Field (required)Description
titleTítulo H1 da página, usado pra SEO e OG Images
descriptionDescrição usada na meta tag SEO
Field (optional)Description
nav_titleSobrescreve o título na navegação
sourcePuxa conteúdo de outra página compartilhada
relatedLista de links relacionados (vira cards)
versionEstágio: experimental, legacy, unstable, RC
JS contentFence/extensão
JS com JSX```jsx / .js
JS sem JSX```js / .js
TS com JSX```tsx / .tsx
TS sem JSX```ts / .ts

Anti-patterns

  • Usar manifest file pra navegação em vez de file-system routing: considerado e rejeitado, pois fica dessincronizado dos arquivos reais.
  • Usar emojis ou HTML cru (exceto <details>) na documentação: não permitido no style guide.
  • Escrever em voz passiva ou usar palavras subjetivas (fácil, simples, só) ou negativas (não pode, não deve): contra o guia de voz.

Key Takeaways

  1. Rode pnpm prettier-fix antes de submeter um PR de docs.
  2. Páginas conceituais usam segunda pessoa ("você"); páginas de referência tendem a omitir o sujeito e usar imperativo.
  3. Blocos de código devem ser mínimos, executáveis e testados localmente antes do commit.

Connects To

  • Community (ch451): página pai desta seção.
  • Page Title (ch453) / <Link> (ch454, ch455): exemplos de frontmatter/MDX extraídos diretamente deste guia.
AnteriorCommunityPróximoPage Title