update-docs

Atualizador da documentação do Next.js

Orientam você na atualização da documentação do Next.js com base nas alterações de código no branch ativo. Projetado para mantenedores que revisam PRs para verificar se a documentação está completa.

Introdução rápida

1. Analise as alterações: execute git diff canary...HEAD --stat para ver quais arquivos foram alterados
2. Identifique os documentos afetados: mapeie os arquivos-fonte alterados para os caminhos da documentação
3. Revise cada documento: percorra as atualizações com a confirmação do usuário
4. Validar: Executar pnpm lint para verificar a formatação
5. Confirmar: Preparar as alterações na documentação

Fluxo de trabalho: Analisar alterações no código

Etapa 1: Obter o diff

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

Etapa 2: Identificar alterações relevantes para a documentação

Procure por alterações nessas áreas:

Etapa 3: Mapeie para os arquivos de documentação

Use o mapeamento de código para documentação em references/CODE-TO-DOCS-MAPPING.md para encontrar os arquivos de documentação correspondentes.

Exemplos de mapeamentos:

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

Fluxo de trabalho: Atualizar a documentação existente

Passo 1: Leia a documentação atual

Antes de fazer alterações, leia a documentação existente para entender:

• A estrutura e as seções atuais
• Campos de frontmatter em uso
• Se ela utiliza / para conteúdo específico do roteador

Etapa 2: Identifique o que precisa ser atualizado

Atualizações comuns incluem:

• Novas propriedades/opções: Adicione à tabela de propriedades e crie uma seção explicando o uso
• Mudança de comportamento: atualize as descrições e os exemplos
• Recursos obsoletos: adicione avisos de obsolescência e orientações de migração
• Novos exemplos: adicione blocos de código seguindo as convenções

Etapa 3: Aplicar as atualizações com confirmação

Para cada alteração:

1. Mostre ao usuário o que você pretende alterar
2. Aguarde a confirmação antes de editar
3. Aplique a edição
4. Passe para a próxima alteração

Etapa 4: Verifique se há conteúdo compartilhado

Se o documento usar o source padrão de campo (comum em documentos do Pages Router), o arquivo de origem é o que deve ser editado. Exemplo:

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

Edite o código-fonte do App Router, não o arquivo do Pages Router.

Etapa 5: Valide as alterações

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

Fluxo de trabalho: Estruturar a documentação de novos recursos

Use isso ao adicionar documentação para recursos totalmente novos.

Etapa 1: Determinar o tipo de documento

Etapa 2: Crie o arquivo com a nomenclatura adequada

• Use o formato “kebab-case”: my-new-feature.mdx
• Adicione um prefixo numérico se a ordem for importante: 05-my-new-feature.mdx
• Coloque no diretório correto de acordo com o tipo de recurso

Passo 3: Use o modelo apropriado

Modelo de referência da 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
\`\`\`

Modelo de guia:

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

Etapa 4: Adicione links relacionados

Atualize o frontmatter com a documentação relacionada:

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

Convenções de documentação

Consulte references/DOC-CONVENTIONS.md para as regras completas de formatação.

Referência rápida

Frontmatter (obrigatório):

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

Blocos de código:

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

Conteúdo específico do roteador:

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 verificação de validação

Antes de enviar as alterações na documentação:

• O frontmatter contém title e description
• Os blocos de código têm filename o atributo
• Os exemplos em TypeScript usam switcher com a variante JS
• As tabelas de props estão formatadas corretamente
• Os links relacionados apontam para caminhos válidos
• pnpm lint aprovado
• As alterações são renderizadas corretamente (se houver visualização disponível)

Referências

• references/DOC-CONVENTIONS.md - Regras completas de frontmatter e formatação
• references/CODE-TO-DOCS-MAPPING.md - Mapeamento entre o código-fonte e a documentação