Sobre READMEs

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 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, comunica as expectativas para o seu projeto e ajuda você a gerenciar 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 arquivo README na raiz do repositório, docs, ou no diretório .github oculto, o GitHub AE reconhecerá e apresentará automaticamente o README aos visitantes do repositório.

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

O índice gerado automaticamente é habilitado por padrão para todos os arquivos Markdown em um repositório, mas você pode desabilitar esta funcionalidade para o repositório.

  1. No GitHub AE, navegue até a página principal do repositório.
  2. No nome do seu repositório, clique em Configurações. Botão de configurações do repositório
  3. Em "Funcionalidades", desmarque Índice. Configuração automática de TOC para repositórios

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

Leia mais

Esse documento ajudou você?Política de Privacidade

Ajude-nos a tornar esses documentos ótimos!

Todos os documentos do GitHub são de código aberto. Você percebeu que algo que está errado ou não está claro? Envie um pull request.

Faça uma contribuição

Ou, aprenda como contribuir.