Sobre READMEs
É possível adicionar um arquivo README a um repositório para comunicar informações importantes sobre o seu projeto. Um README, junto com uma licença de repositório, comunicam as expectativas para o seu projeto e ajudam você a gerenciar as contribuições.
Para obter mais informações sobre como fornecer diretrizes para o seu projeto, consulte "Configurar o 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 seu arquivo README no .github oculto do seu repositório, raiz ou diretório de docs, GitHub AE irá reconhecer e automaticamente supervisionar seu README para os visitantes do repositório.
Se um repositório contiver mais de um arquivo README, o arquivo mostrado será escolhido entre os locais na seguinte ordem: o diretório do .github, em seguida, o diretório raiz do repositório e, finalmente, o diretório docs.
Í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.
Links de seção nos arquivos README e páginas blob
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:
Links relativos e caminhos de imagem em arquivos README
É 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 README na raiz do seu repositório e tiver outro arquivo em docs/CONTRIBUTING.md, o link relativo para CONTRIBUTING.md no seu README pode se parecer com isso:
[Diretrizes de contribuição para este projeto](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. The path of the link will be relative to the current file. Links starting with / will be relative to the repository root. Você pode usar todas as operações de links 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, consulte "Sobre wikis."