Skip to main content

Sobre LEIAMEs

Você pode adicionar um arquivo README ao seu repositório para informar outras pessoas por que seu projeto é útil, o que elas podem fazer com o projeto e como elas podem usá-lo.

Sobre LEIAMEs

É possível adicionar um arquivo README a um repositório para comunicar informações importantes sobre o seu projeto. Um LEIAME, junto com uma licença de repositório, um arquivo de citação, diretrizes de contribuição e um código de conduta, comunica as expectativas do projeto e ajuda você a gerenciar contribuições.

Para obter mais informações sobre como fornecer diretrizes para seu projeto, confira "Adicionar um código de conduta ao seu projeto" e "Configurar projeto para contribuições úteis".

Um README, muitas vezes, é o primeiro item que um visitante verá ao visitar seu repositório. Os arquivos README geralmente incluem informações sobre:

  • O que o projeto faz
  • Por que o projeto é útil
  • Como os usuários podem começar a usar o projeto
  • Onde os usuários podem obter ajuda com seu projeto
  • Quem mantém e contribui com o projeto

Se você colocar o arquivo LEIAME no .github oculto do seu repositório, na raiz ou no diretório docs, o GitHub reconhecerá e exibirá automaticamente o LEIAME para os visitantes do repositório.

Se um repositório contiver mais de um arquivo README, o arquivo mostrado nos links será escolhido nos locais na seguinte ordem: o diretório .github, o diretório raiz do repositório e, por fim, o diretório docs.

Se você adicionar um arquivo README à raiz de um repositório público com o mesmo nome de usuário, esse README aparecerá automaticamente na sua página de perfil. Você pode editar seu perfil README com GitHub Flavored Markdown para criar uma seção personalizada no seu perfil. Para obter mais informações, confira "Gerenciar o README do seu perfil".

Índice gerado automaticamente para arquivos README

Para a visualização interpretada de qualquer arquivo Markdown em um repositório, incluindo arquivos README GitHub irá gerar automaticamente um índice com base nos títulos da seção. Você pode visualizar o índice para um arquivo LEIAME, clicando no ícone de menu no canto superior esquerdo da página interpretada.

Captura de tela do LEIAME de um repositório. No canto superior esquerdo, um menu suspenso, rotulado com um ícone de lista, é expandido para mostrar um índice.

Você pode vincular diretamente a uma seção de um arquivo interpretado, passando o mouse sobre o título da seção para expor o .

Captura de tela de um LEIAME de um repositório. À esquerda de um título de seção, um ícone de link é descrito em laranja escuro.

É possível definir links relativos e caminhos de imagens em seus arquivos representados para ajudar os leitores a acessar outros arquivos no repositório.

Um link relativo é um link que é relativo ao arquivo atual. Por exemplo, se você tiver um arquivo LEIAME na raiz do repositório e tiver outro arquivo em docs/CONTRIBUTING.md, o link relativo para CONTRIBUTING.md no LEIAME poderá ter esta aparência:

[Contribution guidelines for this project](docs/CONTRIBUTING.md)

GitHub transformará automaticamente o seu link relativo ou caminho da imagem baseado em qualquer branch em que você estiver no momento para que o link ou caminho sempre funcione. O caminho do link será relativo ao arquivo atual. Links que começam com / serão relativos à raiz do repositório. Você pode usar todos os operandos de link relativos, como ./ e ../.

Os links relativos são mais fáceis para usuários que clonam o seu repositório. Os links absolutos podem não funcionar em clones do seu repositório - recomendamos usar links relativos para referir-se a outros arquivos no seu repositório.

Wikis

Um README deve conter apenas as informações necessárias para desenvolvedores começarem a usar e a contribuir para o seu projeto. A documentação mais longa é mais adequada para wikis. Para obter mais informações, confira "Sobre wikis".

Leitura adicional