Contribuindo para a Documentação

Nota Importante

Nosso objetivo é ter todas as versões da documentação espelhadas. A documentação em inglês é a mais completa e serve como referência principal. Quaisquer novas páginas que não existam nas documentações de outros idiomas devem ser adicionadas primeiro na documentação em inglês para garantir a consistência em todas as traduções. Se você não estiver confiante no seu inglês, envie uma mensagem privada para "WritingTeam" no site da RetroAchievements. Eles ficarão felizes em ajudar.

Todas as contribuições para a documentação são bem-vindas.

Agradecemos seu interesse em contribuir. Seja você novo no Git ou um desenvolvedor experiente, estamos aqui para ajudar. Veja como você pode melhorar nossa documentação:

Edições Rápidas

Se você só quer fazer uma edição rápida em uma página existente, siga estes passos simples:

1. Editar Esta Página: Visite qualquer página no site da documentação, role até o final e clique no link "Edit this page".
2. Fork do Repositório: Clique no botão "Fork this repository". Isso criará sua própria cópia da documentação.
3. Faça Suas Alterações: Use o editor Markdown na tela para fazer e visualizar suas alterações.
4. Enviar Alterações: Clique no botão "Commit changes". Escreva um título e uma descrição para suas alterações e envie.
5. Criar Pull Request: Clique no botão "Create pull request". Escreva um título e uma descrição para sua pull request e envie para revisão.

Contribuições Detalhadas

Se você quer criar novas páginas ou trabalhar em várias páginas, siga estes passos:

1. Fork do Repositório

• Vá para a página do repositório e clique no botão "Fork".
• Pressione "Create fork" no formulário que aparece.

2. Abra no VSCode

• Uma vez que você esteja visualizando seu fork (geralmente em github.com/seu-usuario-aqui/docs), pressione a tecla ponto (".") no seu teclado para abrir o VSCode no seu navegador.
• Use a árvore de arquivos à esquerda para explorar a documentação, expandindo especificamente a pasta "docs".
• Use o atalho Ctrl+P para buscar arquivos, como "README".

3. Edite e Visualize

• Abra a paleta de comandos com Ctrl+Shift+P (ou F1 no Firefox), busque "markdown preview" e selecione "Markdown: Open Preview to the Side".
• Use a visualização de Markdown para ver suas alterações enquanto as escreve.

4. Crie um Branch

• Clique no nome do branch (geralmente main) no canto inferior esquerdo do VSCode.
• Clique em "Create branch", nomeie seu branch, pressione Enter e depois clique em "Switch to Branch".

5. Salve e Faça o Commit

• Use Ctrl+S para salvar os arquivos enquanto trabalha.
• Clique no ícone de Controle de Código-Fonte à esquerda, clique com o botão direito nos arquivos que você alterou e clique em "Stage Changes".
• Escreva uma mensagem de commit, depois clique no botão "Commit & Push".

6. Crie um Pull Request

• Abra a paleta de comandos com Ctrl+Shift+P (ou F1 no Firefox) e use o comando "Create Pull Request".
• Preencha o formulário com um título e uma descrição, depois clique em "Create".

Adicionando Novas Páginas

Se você quer adicionar uma nova página, precisará atualizar a configuração do sidebar no arquivo pt.ts. É assim que você pode conectar a navegação às novas páginas.

Por exemplo, se seu novo arquivo Markdown for docs/general/my-file.md, adicione isto a sidebarGeneral():

{
    text: "Minha Nova Página",
    link: "/general/my-file",
}

Também é uma boa prática adicionar isso às configurações dos outros idiomas para mantê-los sincronizados, mesmo que esteja comentado:

// {
//     text: "Minha Nova Página",
//     link: "/general/my-file",
// }

Executando o Site de Documentação Localmente

Para executar o site de documentação no seu computador:

1. Baixe e instale Node.js v20.

2. Instale o Git. Baixe e instale o Git se você for um usuário de Windows.

3. Abra um terminal e clone o repositório:

git clone https://github.com/RetroAchievements/docs.git

4. Navegue até o repositório clonado e execute o servidor de desenvolvimento local:

cd docs
npm install
npm run dev

É isso! Seu servidor local deve estar funcionando, permitindo que você visualize suas alterações.