Como contribuir

O Wired Club Docs é construído pela comunidade. Você pode contribuir corrigindo uma palavra, melhorando uma explicação, documentando um Wired ou criando um guia completo.

Escolha uma forma de contribuir

	Pelo GitHub Web	Pelo VS Code Web	Em seu computador
Indicado para	Textos, links e correções pontuais em um único arquivo	Edição de múltiplos arquivos, reorganização de textos e refatorações sem instalação	Novas páginas, componentes, testes de build e alterações avançadas
Instalação	Nenhuma	Nenhuma (executa direto no navegador)	Git e Node.js
Acesso	Botão Editar página no rodapé	Tecla `.` na página do repositório GitHub (ou trocando `.com` por `.dev`)	`git clone` e terminal local
Visualização	Aba Preview simplificada no GitHub	Editor VS Code completo com busca global e destaque de sintaxe	Site completo rodando em `localhost:4321`

Pelo GitHub Web

Abra o arquivo

Na página que deseja alterar, selecione Editar página no rodapé. Você será levado ao arquivo correspondente no repositório.
Faça a alteração

Entre em sua conta do GitHub e selecione a opção de editar o arquivo. Caso você não tenha acesso direto ao repositório, o GitHub criará um fork automaticamente.
Proponha a mudança

Descreva brevemente o que foi alterado e confirme a proposta. Revise as diferenças exibidas pelo GitHub antes de continuar.
Abra o pull request

Crie o pull request para a branch main do repositório WiredClub/docs. A equipe poderá aprovar a contribuição ou pedir ajustes.

Você pode acompanhar a revisão na aba Pull requests. Depois que a mudança for aprovada e publicada, ela pode levar alguns minutos para aparecer no site.

Pelo VS Code Web (tecla `.`)

O VS Code Web (disponível via github.dev) permite editar arquivos do projeto utilizando a interface completa do Visual Studio Code diretamente pelo navegador, sem necessidade de clonar o repositório ou instalar ferramentas locais.

Vantagens do VS Code Web

Sem necessidade de instalação: Não exige Git, Node.js nem download de dependências. Funciona em qualquer computador ou tablet com navegador moderno.
Edição multi-arquivos: Permite abrir e alterar simultaneamente múltiplos arquivos MDX, visualizar a estrutura completa de pastas e mover arquivos facilmente.
Recursos avançados do VS Code: Destaque de sintaxe, busca e substituição global em todo o projeto (Ctrl+Shift+F / Cmd+Shift+F), atalhos de teclado conhecidos e pré-visualização de Markdown.
Git e Pull Requests integrados: Painel de Source Control na barra lateral para criar branches, fazer commits formatados e abrir pull requests diretamente pelo navegador.

Passo a passo para contribuir

Abra o repositório no VS Code Web

Acesse o repositório WiredClub/docs (ou o seu fork) no GitHub e pressione . (ponto) no teclado.
Edite as páginas desejadas

Na barra lateral esquerda, navegue até a pasta src/content/docs/, abra os arquivos .mdx que deseja modificar ou crie novas páginas.
Realize o commit das alterações

Acesse o painel Source Control (Ctrl+Shift+G / Cmd+Shift+G). Digite uma mensagem de commit clara seguindo o padrão do projeto (ex.: docs: atualiza guia de contribuição) e clique em Commit. Caso não tenha permissão de escrita direta, o editor solicitará permissão para criar uma nova branch/fork automaticamente.
Envie o Pull Request

Após concluir o commit, utilize o botão de criação de Pull Request oferecido na interface do VS Code Web ou acesse o repositório no GitHub para propor as alterações para a branch main de WiredClub/docs.

Mantenha sua contribuição atualizada

Enquanto você trabalha em uma contribuição, outras pessoas podem enviar alterações para o projeto. Por isso, sua cópia do projeto pode ficar desatualizada em relação à branch main.

É uma boa prática atualizar sua contribuição antes de abrir o pull request e durante trabalhos mais longos. Isso diminui a chance de aparecerem conflitos, que acontecem quando duas alterações mexem na mesma parte de um arquivo e o Git não consegue decidir sozinho qual versão manter.

O jeito mais fácil: pelo GitHub

Se você estiver trabalhando em um fork, não precisa usar o terminal para fazer essa sincronização.

Abra seu fork no GitHub

Acesse a página do seu fork de WiredClub/docs.
Procure o botão “Sync fork”

Na página principal do repositório, o GitHub mostra a opção Sync fork quando existem alterações novas no repositório original.
Atualize sua cópia

Clique em Sync fork e depois em Update branch. O GitHub copiará as alterações mais recentes da branch main do projeto para a branch correspondente do seu fork.
Continue trabalhando

Depois da sincronização, você pode continuar editando sua branch e abrir o pull request normalmente.

Se o GitHub informar que existem conflitos, isso significa que alguma alteração do projeto original entrou em conflito com o que você modificou. Nesse caso, talvez seja necessário resolver o conflito antes que o pull request possa ser integrado.

Para quem trabalha pelo computador

Quando você trabalha localmente, o processo é semelhante, mas envolve alguns comandos do Git. Primeiro, atualize sua branch main com as alterações do projeto original e, depois, atualize sua branch de trabalho.

Se você ainda não configurou o repositório original como upstream, faça isso uma única vez:

git remote add upstream https://github.com/WiredClub/docs.git

Depois, para atualizar sua main local:

git fetch upstream
git checkout main
git merge upstream/main

Em seguida, volte para a sua branch de trabalho e incorpore as alterações:

git checkout docs/nome-da-alteracao
git merge main

Caso o Git informe que existem conflitos, você precisará resolvê-los antes de continuar. Depois de resolver os arquivos indicados pelo Git, faça um novo commit com a resolução e continue o trabalho.

Uma alternativa usada por projetos como Django, pip e Cirq é atualizar a própria branch diretamente sobre a main mais recente usando rebase:

git fetch upstream
git checkout docs/nome-da-alteracao
git rebase upstream/main

O rebase é mais técnico e pode exigir a resolução de conflitos. Se você está começando agora, prefira a sincronização pelo GitHub ou o fluxo com merge descrito acima.

Por que manter a branch atualizada? Atualizar regularmente as branches dos pull requests mantém a contribuição próxima das alterações mais recentes e reduz a possibilidade de conflitos.

Em seu computador

Prepare o repositório

Faça um fork de WiredClub/docs e clone a sua cópia:
Terminal window
```
git clone https://github.com/SEU-USUARIO/docs.git
cd docs
npm install
```
Configure também o repositório original como upstream. Isso permite buscar as alterações feitas por outras pessoas no projeto:
Terminal window
```
git remote add upstream https://github.com/WiredClub/docs.git
```
Crie uma branch

Use um nome curto que descreva a mudança:
Terminal window
```
git checkout -b docs/nome-da-alteracao
```
Edite e visualize

As páginas ficam em src/content/docs/. Inicie o ambiente local e abra http://localhost:4321/:
Terminal window
```
npm run dev
```
Valide a documentação

Antes de enviar, gere a versão de produção. O comando verifica o frontmatter, os imports de MDX e a geração das páginas:
Terminal window
```
npm run build
```

Envie a contribuição

git add src/content/docs
git commit -m "docs: descreve a alteração"
git push origin docs/nome-da-alteracao

Depois, abra um pull request para a branch main de WiredClub/docs.

Configure o e-mail dos commits

O Git registra um nome e um e-mail em cada commit. Para que os commits sejam associados à sua conta do GitHub sem expor seu e-mail pessoal, abra Settings > Emails, confira o endereço noreply fornecido pelo GitHub e use esse endereço na configuração local do repositório:

git config user.name "SEU-NOME"
git config user.email "SEU-ID+SEU-USUARIO@users.noreply.github.com"

Nas configurações de e-mail do GitHub, habilite o toggle Keep my email addresses private e use exatamente o endereço noreply exibido por ele. A opção Block command line pushes that expose my email também pode impedir o envio de commits que contenham outro e-mail. Se quiser aplicar a configuração a todos os repositórios do computador, acrescente --global ao comando:

git config --global user.email "SEU-ID+SEU-USUARIO@users.noreply.github.com"

Para conferir o valor configurado, execute git config user.email (ou git config --global user.email). O e-mail de commits antigos não é alterado automaticamente; por isso, configure-o antes de fazer o primeiro commit.

Para exibir a lista de commits do repositório, use:

git log

Por padrão, o histórico mostra o autor de cada commit no formato Nome <e-mail>. Portanto, o e-mail usado no commit fica visível para qualquer pessoa que consulte o histórico, inclusive no GitHub. Para conferir apenas os autores de forma resumida, você também pode usar:

git log --format="%h %an <%ae> %s"

Padronização das mensagens de commit

O repositório adota a convenção de Conventional Commits para manter o histórico organizado e categorizar automaticamente as atualizações na página de Mudanças Recentes.

As mensagens de commit devem seguir o formato:

tipo(escopo): descrição sucinta da alteração

O (escopo) é opcional e indica a parte do projeto afetada (ex.: feat(starlight-recent-changes): ... ou fix(page-reader): ...).

Prefixos recomendados

Prefixo	Categoria em Mudanças Recentes	Uso
`feat:` / `feature:` / `new:`	Novo	Novas páginas, novos componentes ou novas funcionalidades.
`fix:`	Edição	Correção de erros, links quebrados ou falhas de formatação.
`docs:`	Edição	Atualização de textos, guias e documentação existente.
`style:`	Edição	Ajustes visuais, CSS ou estéticos sem alterar comportamento.
`refactor:`	Edição	Reestruturação de código ou pastas mantendo o mesmo funcionamento.
`chore:` / `ci:` / `build:`	Edição	Manutenção de dependências, arquivos de configuração ou scripts.
`remove:` / `delete:` / `revert:`	Removido	Remoção de páginas legadas ou reversão de alterações.

Exemplos de mensagens

git commit -m "feat: adiciona guia de Lógica de Programação"
git commit -m "fix(page-reader): corrige exibição do leitor em telas menores"
git commit -m "style: ajusta bordas e cores dos cards de ativadores"
git commit -m "docs: atualiza tabela de parâmetros do ativador clica no mobi"

Escrevendo uma página

Use arquivos .mdx em src/content/docs/. O nome das pastas define a URL; por exemplo, guias-praticos/primeiro-sistema.mdx gera /guias-praticos/primeiro-sistema/.

Toda página começa com um bloco de metadados chamado frontmatter na linguagem YAML:

---
title: Título da página
description: Resumo objetivo do conteúdo da página.
sidebar:
  label: Título curto no menu
  order: 1
---

Dentro do frontmatter, o caractere # inicia um comentário. Tudo o que estiver depois dele, naquela linha, é ignorado pelo YAML e não altera a página. Isso permite explicar um campo, separar grupos de informações ou “desativar” temporariamente uma linha sem apagá-la.

infobox:
  # == Dados do Mobi ==
  title: Habbo anda no Mobi
  # image: # preenchida automaticamente
  image_direction: 2
  # image_animated_state: 100 # valor padrão

No exemplo acima, title e image_direction estão ativos. As linhas de image e image_animated_state estão comentadas, portanto o projeto usa os valores automáticos ou padrões desses campos. Um comentário também pode aparecer depois de um valor ativo, como em availability: No catálogo e CA # opções aceitas.

Esse recurso é usado em src/content/docs/referencia/ativadores/wf_trg_walks_on_furni.mdx para documentar valores padrão e manter campos opcionais visíveis como referência. Ao reativar uma linha, remova o # e mantenha a indentação correta.

Neste projeto, as páginas das seções Vamos Começar e Guias práticos entram automaticamente no menu. A seção Referência combina itens definidos manualmente com grupos automáticos. A seção Sobre Nós é manual. Ao criar ou mover uma página, confira a configuração sidebar em astro.config.mjs.

Campos de frontmatter

Os campos mais relevantes para as páginas deste projeto são:

Campo	Uso
`title`	Título da página. É obrigatório.
`description`	Resumo usado nos metadados e resultados de busca.
`sidebar.label`	Nome alternativo no menu lateral.
`sidebar.order`	Ordem dentro de um grupo gerado automaticamente.
`sidebar.badge`	Selo no menu, com `text` e `variant`. Use somente quando ele comunicar um estado real, como `RASCUNHO`.
`template`	Layout da página. A página inicial usa `splash`; páginas comuns não precisam deste campo.
`banner` e `hero`	Conteúdo de destaque da página inicial. Não use em páginas comuns.
`tableOfContents`	Personaliza ou oculta o sumário da página.
`prev` e `next`	Personalizam ou desativam a navegação anterior/seguinte.
`infobox`	Dados da infobox personalizada do Wired Club Docs. Use em páginas de referência de mobis e Wireds.

Infobox de Wired

As páginas individuais de Wired usam infobox no frontmatter e renderizam o componente <Infobox /> no início do conteúdo:

---
title: "ATIVADOR WIRED: Habbo Clica no Mobi"
description: Ativa a pilha quando um usuário clica no mobi selecionado.
sidebar:
  label: Habbo Clica no Mobi
infobox:
  type: Ativador
  title: Habbo Clica no Mobi
  revision: 69540
  classname: wf_trg_click_furni
  name: Habbo Clica no Mobi
  availability: No catálogo e CA
  requires_furni: false
---

import Infobox from "@components/Infobox.astro";

<Infobox />

Os campos são validados por src/content.config.ts:

Campo	Regra
`type`	`Ativador`, `Efeito`, `Condição` ou `Extra`. Define os demais campos aceitos.
`title`, `revision`, `classname`, `name`	Obrigatórios em uma infobox de Wired.
`description`, `product_name`, `image`, `availability`, `price`, `release_date`	Informações opcionais de identificação, imagem e disponibilidade.
`image_direction`	Direção de `0` a `7`; o padrão é `0`.
`image_animated_state`	Estado usado na imagem animada; o padrão é `100`.
`requires_bot`, `requires_furni`, `requires_antena`, `requires_contract`, `requires_chest`	Requisitos booleanos; o padrão é `false`.
`execution_limit`, `execution_limit_per_user`	Limites por tick; o padrão é `100`.
`additional_sources`	Somente para ativadores; lista as fontes adicionais aceitas pelo schema.
`negative_version`	Somente para efeitos e condições; informa `name`, `revision`, `classname` e, opcionalmente, `description`.

Também existe uma infobox básica, com title, image opcional e hide opcional. Não copie valores de outra página sem conferir o mobi no jogo e a fonte dos dados.

Formatação básica em Markdown

Como ainda não temos um editor visual, o conteúdo é escrito em Markdown, uma forma simples de formatar texto usando símbolos:

O que eu quero	Como eu escrevo
Um título de seção	`## Nome da seção`
Um subtítulo	`### Nome do subtítulo`
Texto em negrito	`texto`
Texto em itálico	`texto`
Um link	`[texto do link](https://exemplo.com)`
Lista com marcadores	`- primeiro item`
Lista numerada	`1. primeiro item`
Uma citação	`> texto citado`
Uma imagem	`![descrição da imagem](/caminho/imagem.png)`

Para trechos de código, use crases:

Um trecho de `código` no meio da frase, ou um bloco maior:

```js
console.log("assim fica um bloco de código");
```

Se tiver dúvida sobre como algo vai ficar, use a aba “Preview” no editor do GitHub Web, ela mostra uma prévia simplificada antes de você enviar.

Componentes disponíveis

Arquivos .mdx aceitam componentes. Importe apenas o que a página realmente utiliza.

Componente	Origem	Quando usar
`Aside`	`@astrojs/starlight/components`	Observações, dicas, cuidados e avisos importantes.
`Steps`	`@astrojs/starlight/components`	Procedimentos em sequência.
`Tabs` e `TabItem`	`@astrojs/starlight/components`	Duas ou mais formas equivalentes de apresentar uma configuração.
`Card` e `CardGrid`	`@astrojs/starlight/components`	Conjuntos curtos de links ou opções; são usados na página inicial.
`Infobox`	`src/components/Infobox.astro`	Exibir os dados do campo `infobox` em páginas de referência.
`WiredGrid`	`src/components/WiredGrid.astro`	Listar Wireds por `type` ou por uma lista de `classname`.
`PageReader`	`src/components/PageReader.astro`	Oferecer leitura em voz alta; informe `title` e `description`.
`ShowcaseYouTube`	pacote `starlight-showcases`	Incorporar um vídeo do YouTube quando ele acrescentar uma demonstração útil.

Exemplo de aviso:

import { Aside } from '@astrojs/starlight/components';

<Aside type="caution" title="Atenção">
Explique aqui o cuidado necessário.
</Aside>

Imagens, links e estilo

Coloque imagens mantidas pelo projeto em src/assets/ e importe-as com caminho relativo quando quiser que o Astro faça a otimização.
Escreva um texto alternativo que descreva o conteúdo relevante da imagem.
Para páginas internas, prefira links a partir da raiz publicada, como /referencia/glossario/.
Use português do Brasil, frases diretas e os termos adotados nas páginas existentes, como Wired, mobi, Ativador, Efeito, Condição e Habbo.
Explique siglas e conceitos antes de aprofundá-los. Evite copiar descrições provisórias ou em outro idioma.
Preserve o foco da página. Quando um assunto exigir uma explicação longa, crie uma página própria e adicione os links necessários.

Antes de abrir o pull request

Confira se o título, a descrição e o menu representam corretamente o conteúdo.
Remova textos provisórios, placeholders e imports que não são usados.
Teste exemplos e confirme informações técnicas no Habbo ou em uma fonte confiável.
Verifique imagens, links internos e a visualização em telas menores.
Se sua contribuição começou há alguns dias, sincronize sua branch com a main mais recente para reduzir a chance de conflitos.
Execute npm run build e descreva no pull request o que mudou e como você validou.
Não inclua arquivos gerados, dependências ou materiais de trabalho, como dist/, node_modules/, PDFs e arquivos compactados.

Onde pedir ajuda

Se tiver uma ideia, dúvida ou encontrar um problema, abra uma issue no GitHub. Para conversar com a comunidade, entre no Discord do Wired Club.

Toda contribuição, pequena ou grande, ajuda a tornar o conhecimento sobre Wired mais acessível.