Sobre READMEs
É 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, consulte Adicionar um código de conduta ao seu projeto e Configurar seu projeto para contribuições saudáveis.
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 README no diretório oculto .github, raiz ou docs, GitHub reconhecerá e exibirá automaticamente o seu README aos 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.
Quando o README for exibido no GitHub, qualquer conteúdo além de 500 KiB será truncado.
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 o Flavored Markdown para criar uma seção personalizada em seu perfil. Para saber mais, confira Gerenciar o README do seu perfil.
Sumário gerado automaticamente para arquivos markdown
Para a exibição renderizada de qualquer arquivo Markdown em um repositório, incluindo arquivos README, GitHub gerará automaticamente um sumário com base em títulos de seção. Você pode exibir o sumário de um arquivo README clicando no ícone de menu "Estrutura de Tópicos" no canto superior da página renderizada.
Links de seção em arquivos markdown e páginas de blob
Você pode criar um link direto para qualquer seção que tenha um título. Para visualizar a âncora gerada automaticamente em um arquivo renderizado, passe o mouse sobre o cabeçalho da seção para expor o ícone e clique no ícone para exibir a âncora em seu navegador.
Para obter informações mais detalhadas sobre links de seção, confira Links de seção.
Links relativos e caminhos de imagem em arquivos markdown
É 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)
O GitHub transformará automaticamente o link relativo ou o caminho da imagem baseado em qualquer branch em que você estiver no momento para que o link ou o 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 ../.
O texto do link deve estar em uma única linha. O exemplo abaixo não funcionará.
[Contribution
guidelines for this project](docs/CONTRIBUTING.md)
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 com o projeto. A documentação mais longa é mais adequada para wikis. Para saber mais, confira Sobre wikis.