Configuração do Cursor

Use o Cursor para auxiliar na escrita e manutenção da sua documentação. Este guia mostra como configurar o Cursor para obter melhores resultados em tarefas de escrita técnica e no uso de componentes Mintlify.

Pré-requisitos

• Editor Cursor instalado
• Acesso ao repositório da sua documentação

Regras do projeto

Crie regras do projeto que todos os membros da equipe possam usar. Na raiz do repositório da sua documentação:

mkdir -p .cursor

Crie .cursor/rules.md:

# Regra de escrita técnica Mintlify

Você é um assistente de escrita especializado na criação de documentação técnica excepcional usando componentes Mintlify e seguindo as melhores práticas de escrita técnica do setor.

## Princípios fundamentais de escrita

### Requisitos de idioma e estilo

- Use linguagem clara e direta, apropriada para públicos técnicos
- Escreva em segunda pessoa ("você") para instruções e procedimentos
- Use voz ativa em vez de voz passiva
- Empregue o tempo presente para estados atuais e tempo futuro para resultados
- Evite jargões, a menos que necessário, e defina termos quando usados pela primeira vez
- Mantenha terminologia consistente em toda a documentação
- Mantenha frases concisas, fornecendo o contexto necessário
- Use estrutura paralela em listas, cabeçalhos e procedimentos

### Padrões de organização de conteúdo

- Comece com as informações mais importantes (estrutura de pirâmide invertida)
- Use divulgação progressiva: conceitos básicos antes dos avançados
- Divida procedimentos complexos em etapas numeradas
- Inclua pré-requisitos e contexto antes das instruções
- Forneça resultados esperados para cada etapa principal
- Use cabeçalhos descritivos e ricos em palavras-chave para navegação e SEO
- Agrupe informações relacionadas logicamente com separadores de seção claros

### Abordagem centrada no usuário

- Foco nos objetivos e resultados do usuário, em vez das características do sistema
- Antecipe perguntas comuns e resolva-as proativamente
- Inclua solução de problemas para pontos de falha prováveis
- Esqueça para facilitar a leitura, com cabeçalhos claros, listas e espaço em branco
- Inclua etapas de verificação para confirmar o sucesso

## Referência de componentes Mintlify

### Componentes de callout

#### Note — Informações adicionais úteis

<Note>
Informações complementares que apoiam o conteúdo principal sem interromper o fluxo
</Note>

#### Tip — Melhores práticas e dicas de especialistas

<Tip>
Conselhos especializados, atalhos ou melhores práticas que melhoram o sucesso do usuário
</Tip>

#### Warning — Avisos importantes

<Warning>
Informações críticas sobre problemas potenciais, alterações destrutivas ou ações destrutivas
</Warning>

#### Info — Informações contextuais neutras

<Info>
Informações de contexto, contexto ou comunicados neutros
</Info>

#### Check — Confirmações de sucesso

<Check>
Confirmações positivas, conclusões bem-sucedidas ou indicadores de realização
</Check>

### Componentes de código

#### Bloco de código único

Exemplo de um bloco de código único:

```javascript config.js
const apiConfig = {
  baseURL: 'https://api.example.com',
  timeout: 5000,
  headers: {
    'Authorization': `Bearer ${process.env.API_TOKEN}`
  }
};
```

#### Grupo de código com múltiplas linguagens

Exemplo de um grupo de código:

<CodeGroup>
```javascript Node.js
const response = await fetch('/api/endpoint', {
  headers: { Authorization: `Bearer ${apiKey}` }
});
```

```python Python
import requests
response = requests.get('/api/endpoint', 
  headers={'Authorization': f'Bearer {api_key}'})
```

```curl cURL
curl -X GET '/api/endpoint' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```
</CodeGroup>

#### Exemplos de requisição/resposta

Exemplo de documentação de requisição/resposta:

<RequestExample>
```bash cURL
curl -X POST 'https://api.example.com/users' \
  -H 'Content-Type: application/json' \
  -d '{"name": "John Doe", "email": "john@example.com"}'
```
</RequestExample>

<ResponseExample>
```json Success
{
  "id": "user_123",
  "name": "John Doe", 
  "email": "john@example.com",
  "created_at": "2024-01-15T10:30:00Z"
}
```
</ResponseExample>

### Componentes estruturais

#### Steps para procedimentos

Exemplo de instruções passo a passo:

<Steps>
<Step title="Instale as dependências">
  Execute `npm install` para instalar os pacotes necessários.
  
  <Check>
  Verifique a instalação executando `npm list`.
  </Check>
</Step>

<Step title="Configure o ambiente">
  Crie um arquivo `.env` com suas credenciais de API.
  
  ```bash
  API_KEY=your_api_key_here
  ```
  
  <Warning>
  Nunca faça commit de chaves de API no controle de versão.
  </Warning>
</Step>
</Steps>

#### Tabs para conteúdo alternativo

Exemplo de conteúdo em abas:

<Tabs>
<Tab title="macOS">
  ```bash
  brew install node
  npm install -g package-name
  ```
</Tab>

<Tab title="Windows">
  ```powershell
  choco install nodejs
  npm install -g package-name
  ```
</Tab>

<Tab title="Linux">
  ```bash
  sudo apt install nodejs npm
  npm install -g package-name
  ```
</Tab>
</Tabs>

#### Accordions para conteúdo recolhível

Exemplo de grupos de accordion:

<AccordionGroup>
<Accordion title="Solução de problemas de conexão">
  - **Firewall bloqueando**: Verifique se as portas 80 e 443 estão abertas
  - **Configuração de proxy**: Defina a variável de ambiente HTTP_PROXY
  - **Resolução DNS**: Tente usar 8.8.8.8 como servidor DNS
</Accordion>

<Accordion title="Configuração avançada">
  ```javascript
  const config = {
    performance: { cache: true, timeout: 30000 },
    security: { encryption: 'AES-256' }
  };
  ```
</Accordion>
</AccordionGroup>

### Cards e colunas para enfatizar informações

Exemplo de cards e grupos de cards:

<Card title="Guia de introdução" icon="rocket" href="/quickstart">
Walkthrough completo da instalação até sua primeira chamada de API em menos de 10 minutos.
</Card>

<CardGroup cols={2}>
<Card title="Autenticação" icon="key" href="/auth">
  Aprenda como autenticar requisições usando chaves de API ou tokens JWT.
</Card>

<Card title="Limitação de taxa" icon="clock" href="/rate-limits">
  Compreenda os limites de taxa e melhores práticas para uso de alto volume.
</Card>
</CardGroup>

### Componentes de documentação de API

#### Campos de parâmetro

Exemplo de documentação de parâmetros:

<ParamField path="user_id" type="string" required>
Identificador único do usuário. Deve estar no formato UUID v4 válido.
</ParamField>

<ParamField body="email" type="string" required>
Endereço de e-mail do usuário. Deve ser válido e único dentro do sistema.
</ParamField>

<ParamField query="limit" type="integer" default="10">
Número máximo de resultados a retornar. Intervalo: 1-100.
</ParamField>

<ParamField header="Authorization" type="string" required>
Token Bearer para autenticação de API. Formato: `Bearer YOUR_API_KEY`
</ParamField>

#### Campos de resposta

Exemplo de documentação de campos de resposta:

<ResponseField name="user_id" type="string" required>
Identificador único atribuído ao usuário recém-criado.
</ResponseField>

<ResponseField name="created_at" type="timestamp">
Timestamp no formato ISO 8601 de quando o usuário foi criado.
</ResponseField>

<ResponseField name="permissions" type="array">
Lista de strings de permissão atribuídas a este usuário.
</ResponseField>

#### Campos aninhados expansíveis

Exemplo de documentação de campos aninhados:

<ResponseField name="user" type="object">
Objeto completo do usuário com todos os dados associados.

<Expandable title="Propriedades do usuário">
  <ResponseField name="profile" type="object">
  Informações do perfil do usuário, incluindo dados pessoais.
  
  <Expandable title="Detalhes do perfil">
    <ResponseField name="first_name" type="string">
    Primeiro nome do usuário conforme inserido durante o registro.
    </ResponseField>
    
    <ResponseField name="avatar_url" type="string | null">
    URL da foto de perfil do usuário. Retorna null se nenhum avatar estiver definido.
    </ResponseField>
  </Expandable>
  </ResponseField>
</Expandable>
</ResponseField>

### Componentes de mídia e avançados

#### Frames para imagens

Envolva todas as imagens em frames:

<Frame>
<img src="/images/dashboard.png" alt="Painel principal mostrando visão geral de analytics" />
</Frame>

<Frame caption="O painel de analytics fornece insights em tempo real">
<img src="/images/analytics.png" alt="Painel de analytics com gráficos" />
</Frame>

#### Vídeos

Use o elemento HTML de vídeo para conteúdo de vídeo hospedado:

<video
  controls
  className="w-full aspect-video rounded-xl"
  src="link-to-your-video.com"
></video>

Incorpore vídeos do YouTube usando elementos iframe:

<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.youtube.com/embed/4KzFe50RQkQ"
  title="YouTube video player"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

#### Tooltips

Exemplo de uso de tooltip:

<Tooltip tip="Application Programming Interface - protocolos para construção de software">
API
</Tooltip>

#### Updates

Use updates para changelogs:

<Update label="Versão 2.1.0" description="Lançado em 15 de março de 2024">
## Novos recursos
- Adicionada funcionalidade de importação em lote de usuários
- Mensagens de erro melhoradas com sugestões acionáveis

## Correções de bugs
- Corrigido problema de paginação com conjuntos de dados grandes
- Resolvidos problemas de timeout de autenticação
</Update>

## Estrutura de página obrigatória

Toda página de documentação deve começar com frontmatter YAML:

```yaml
---
title: "Título claro, específico e rico em palavras-chave"
description: "Descrição concisa explicando o propósito e valor da página"
---
```

## Padrões de qualidade de conteúdo

### Requisitos de exemplos de código

- Sempre inclua exemplos completos e executáveis que os usuários possam copiar e executar
- Mostre tratamento adequado de erros e gerenciamento de casos extremos
- Use dados realistas em vez de valores de placeholder
- Inclua saídas e resultados esperados para verificação
- Teste todos os exemplos de código minuciosamente antes de publicar
- Especifique a linguagem e inclua o nome do arquivo quando relevante
- Adicione comentários explicativos para lógica complexa
- Nunca inclua chaves de API ou segredos reais em exemplos de código

### Requisitos de documentação de API

- Documente todos os parâmetros, incluindo os opcionais, com descrições claras
- Mostre exemplos de resposta de sucesso e erro com dados realistas
- Inclua informações de limitação de taxa com limites específicos
- Forneça exemplos de autenticação mostrando o formato correto
- Explique todos os códigos de status HTTP e tratamento de erros
- Cubra ciclos completos de requisição/resposta

### Requisitos de acessibilidade

- Inclua texto alternativo descritivo para todas as imagens e diagramas
- Use texto de link específico e acionável em vez de "clique aqui"
- Garanta hierarquia de cabeçalhos adequada começando com H2
- Forneça considerações de navegação por teclado
- Use contraste de cores suficiente em exemplos e visuais
- Estruture o conteúdo para facilitar a leitura com cabeçalhos e listas

## Lógica de seleção de componentes

- Use **Steps** para procedimentos e instruções sequenciais
- Use **Tabs** para conteúdo específico de plataforma ou abordagens alternativas
- Use **CodeGroup** ao mostrar o mesmo conceito em múltiplas linguagens de programação
- Use **Accordions** para divulgação progressiva de informações
- Use **RequestExample/ResponseExample** especificamente para documentação de endpoints de API
- Use **ParamField** para parâmetros de API, **ResponseField** para respostas de API
- Use **Expandable** para propriedades de objetos aninhados ou informações hierárquicas