Softonic

Gerador de README

Etapa 1 / 4 README.md
Próximo

Repositórios vazios causam uma má primeira impressão. Preencha o nome do projeto, uma tagline de uma linha, uma lista de recursos, o comando de instalação, um trecho de início rápido, o autor e a licença, e este gerador emite um README em Markdown limpo com uma hierarquia de cabeçalhos adequada e blocos de código cercados: as seções que o GitHub renderiza na página do seu projeto. Copie, salve como README.md na raiz do seu repositório e faça push. Os cabeçalhos das seções são escritos em inglês, a convenção quase universal dos READMEs de código aberto; o seu próprio texto aparece exatamente como você digita, em qualquer idioma.

Como elaborar um README

  1. 1

    Adicione o básico

    Nome do projeto, uma URL de repositório opcional e uma tagline de uma linha. O nome vira o título `#`; a tagline vira a citação abaixo dele.

  2. 2

    Liste os recursos e um início rápido

    Um recurso por linha (cada um vira um marcador), mais um breve trecho de início rápido, que é envolvido em um bloco de código cercado.

  3. 3

    Instalação, licença e autor

    O comando de instalação vai em um bloco de código `bash` na Instalação; adicione a licença (MIT, Apache-2.0…) e uma linha de autor opcional.

  4. 4

    Copie o Markdown

    Clique em copiar e cole a saída como `README.md` na raiz do seu repositório. Faça push e a versão renderizada aparece na página do projeto.

O que um bom README contém

O guia de estilo do próprio GitHub e a especificação amplamente utilizada standard-readme concordam com a ordem. Coloque as partes que podem ser lidas rapidamente no topo, uma pessoa que acessa seu repositório decide em 20 segundos se vai continuar lendo.

Seção Posição Propósito
Título + tagline Linha 1–2 # Projeto seguido por uma frase sobre o que ele faz
Badges Linha 3–5 Status CI, versão npm, licença, cobertura
Instalação Acima da dobra Um único comando que alguém pode copiar
Uso Acima da dobra O trecho mínimo viável que produz saída
API / opções Meio Tabelas de flags, chaves de configuração ou endpoints
Contribuição Perto do fim Link para CONTRIBUTING.md, código de conduta, convenções de PR
Licença Última Identificador SPDX mais link para LICENSE

Badges que realmente ajudam

URLs do Shields.io seguem um padrão previsível: https://img.shields.io/badge/<label>-<message>-<color>.svg. Badges úteis em tempo real apontam para status de build, versão do pacote e contagens de download, não métricas de vaidade. Quatro badges geralmente são suficientes; mais é ruído.

Erros comuns em READMEs

  • Sem comando de instalação na linha 1 da Instalação. Leitores procuram por npm install ou pip install; esconda atrás de prosa e eles vão embora.
  • Capturas de tela que têm 3 MB. Redimensione para 800 px de largura e comprima, o GitHub as servirá de qualquer forma, mas leitores móveis pagam pela largura de banda.
  • Badges desatualizados. Um badge CI vermelho informa aos visitantes que o projeto está quebrado. Conserte o CI ou remova o badge.
  • Licença ausente. Sem uma licença, seu código é “todos os direitos reservados” por padrão e as empresas não podem usá-lo.

Perguntas frequentes

Sim. Blocos de código cercados, listas com marcadores e cabeçalhos no estilo ATX (prefixo #) são renderizados no GitHub, GitLab e Bitbucket sem alterações. O comando de instalação é marcado como bloco bash; o bloco de início rápido fica sem tag para que você defina a linguagem.

Para a maioria dos ecossistemas, README.md. Use .rst apenas se você estiver publicando um pacote Python cuja documentação está no Read the Docs e você deseja que o Sphinx reutilize o arquivo como a página de destino.

Quando você fornece uma URL de repositório, o gerador adiciona um único badge de licença estático (https://img.shields.io/badge/license-<type>-blue.svg). Para badges ao vivo (status de build, versão, downloads), copie um padrão de URL do shields.io e cole você mesmo na saída.

Não. O README é montado a partir dos valores do formulário e nada é salvo. Feche a aba e os dados desaparecem.

Ferramentas relacionadas

Referência da Tabela ASCII

Tabela ASCII completa de 0 a 127 com valores decimais, hexadecimais, octais e binários e notação de referência numérica HTML, incluindo NUL, LF e DEL.

Referência de Caracteres HTML

Lista pesquisável de entidades HTML, seus códigos nomeados e numéricos, e uma cópia com um clique para caracteres e símbolos especiais.

Referência de atalhos de teclado

Pesquise atalhos padrão documentados do VS Code, Chrome e Bash com GNU Readline no macOS, Windows e Linux.

Conversor de Tamanho de Arquivo

Converta entre bytes, KB, MB, GB, TB e as unidades binárias IEC (KiB, MiB, GiB, TiB), combinando decimal e binário como preferir.

Gerador de EditorConfig

Monte um .editorconfig com as suas regras de indentação, fim de linha e charset e acrescente a seção correta para cada linguagem do seu repositório: Python, Go, YAML, Makefile e mais.

Validador de Email

Valide um endereço de email: verificação de sintaxe RFC 5322, consulta de registro MX em tempo real, além de detalhes de parte local, domínio e comprimento. Nenhum email é enviado.

Ferramenta disponível em outros idiomas