Pular para o conteúdo principal

Guia de Estilo de Conteúdo

Todos os níveis

A consistência é o que faz uma referência parecer confiável. Siga estas regras e seu PR passará pela revisão sem percalços.

Tom de voz​

  • Claro e direto. Frases curtas. Comece pelo ponto principal.
  • Amigável, nunca prolixo. Corte o "no mundo acelerado de hoje". Respeite o tempo do leitor.
  • Opinativo, depois honesto. Apresente primeiro a única forma recomendada, depois anote alternativas e trade-offs.
  • Exemplos em vez de teoria. Mostre um trecho de código ou um caso concreto; não apenas descreva.
  • Inglês americano.

Estrutura de uma página​

---
sidebar_position: 2
title: "Your Page Title"
description: "One sentence for search and previews."
---

<LevelBadge level="beginner" />

A one or two sentence intro that states what the reader will get.

## Sections with ## headings
...

## Next
- 2–4 links to related pages
  • Comece com o selo de nível (beginner | intermediate | advanced | all). Os componentes são globais — não os importe.
  • Termine com uma lista "Next" / "Related" de 2 a 4 links internos.
  • Use admonições (:::tip, :::warning, :::note, :::info) para dar ênfase, com moderação.

As duas regras rígidas​

:::warning Inegociável

  1. Cite fontes para fatos voláteis. Nomes de modelos, preços, limites, flags exatas, funcionalidades em beta → faça link para a fonte oficial e adicione <VerifyNote lastVerified="YYYY-MM-DD" source="…">. Nunca fixe fatos de modelo no código — faça link para a tabela de modelos. Detalhes: Verificação de Fatos.
  2. Não invente. Nada de estatísticas, citações, APIs ou funcionalidades inventadas. Se não tiver certeza, diga isso ou marque com [verify]. :::

Opinião vs. oficial​

  • Somos opinativos — esse é o valor. Recomende, não apenas enumere.
  • Mas a documentação oficial é a fonte da verdade. Submeta-se a ela, faça link para ela e nunca a contradiga silenciosamente.

Pegadinhas do MDX​

  • Chaves {like this} na prosa são interpretadas como código pelo MDX — coloque-as em backticks ou blocos de código, ou use [colchetes] em exemplos.
  • Teste localmente: npm run build deve passar (ele falha em links quebrados).

Próximo​