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, 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 "Como configurar seu projeto para contribuições benéficas".

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 AE 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.

Página principal do repositório github/scientist e seu arquivo README

Arquivo README no nome de usuário/repositório do nome de usuário

Índice gerado automaticamente para arquivos README

Para a visualização interpretada de qualquer arquivo Markdown em um repositório, incluindo arquivos README GitHub AE 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.

README com TOC gerado automaticamente

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 link:

Link da seção no arquivo README para o repositório github/scientist

É 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 AE 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 os wikis".

Leitura adicional