Guias
PT
한국어KOEnglishEN日本語JA简体中文ZHEspañolESPortuguês (Brasil)PTFrançaisFRDeutschDEРусскийRUBahasa IndonesiaIDहिन्दीHI

Todas as ferramentas

Dev

Como pôr um banner ASCII num README do GitHub

Coloque num bloco de código Markdown e mantenha abaixo de 80 colunas.

Atualizado em:

O nome do projeto em forma de banner ASCII faz o topo de um README chamar atenção. Diferente de uma imagem, é texto puro: não adiciona arquivo ao repositório e fica certo nos temas claro e escuro.

Adicionando ao README

No Markdown, o banner precisa ficar dentro de um bloco de código. Fora dele, espaços repetidos viram um só, e _ e * viram marcadores de itálico e negrito, estragando a arte.

```text
                                       _           _
 _ __ ___  _   _       _ __  _ __ ___ (_) ___  ___| |_
| '_ ` _ \| | | |_____| '_ \| '__/ _ \| |/ _ \/ __| __|
| | | | | | |_| |_____| |_) | | | (_) | |  __/ (__| |_
|_| |_| |_|\__, |     | .__/|_|  \___// |\___|\___|\__|
           |___/      |_|           |__/
```

# my-project

Uma pequena ferramenta CLI que roda direto no terminal.
  • Escrever text depois das crases de abertura desliga o realce de sintaxe, e os caracteres ficam de uma cor só.
  • Coloque um título de texto de verdade (# my-project) abaixo do banner. Buscadores e leitores de tela não leem o banner como nome do projeto.
  • Se a arte tiver três crases seguidas, envolva-a com quatro crases.

Mantenha abaixo de 80 colunas

Um bloco de código no GitHub rola para o lado quando a linha é longa demais. Um banner cortado perde o sentido, então fique abaixo de 80 colunas, ou por volta de 50 se quiser que caiba no celular também.

Onde é lido Largura sugerida
README do GitHub no computador até 80 colunas
App do GitHub, telas estreitas cerca de 50 colunas
Saída de terminal até 80 colunas

Para um nome longo, escolha uma fonte menor como Small ou Mini em vez de Standard ou Big, ou divida o nome em duas linhas. O canto superior direito de cada card de fonte no lab.ascii mostra a largura do resultado.

Adicionando a um comentário de código

Um banner no topo de um arquivo, ou no começo de uma seção grande, ajuda a se localizar num arquivo longo.

/*
 *  ___ ___ _  _ ___  ___ ___
 * | _ \ __| \| |   \| __| _ \
 * |   / _|| .` | |) | _||   /
 * |_|_\___|_|\_|___/|___|_|_\
 */
export function render() {}
  • Comece cada linha com o marcador de comentário (*, // ou #).
  • Se a arte tiver */, o comentário de bloco termina ali. Use comentários de linha // para essa arte.
  • Se a equipe tiver limite de tamanho de linha, como 100 caracteres, faça o banner caber nele.

Mostrando ao iniciar um programa

Para mostrar um banner quando uma ferramenta CLI inicia, a arte precisa ser guardada como string. O problema é a barra invertida (\). Na maioria das linguagens ela inicia uma sequência de escape, então colar a arte como está perde caracteres ou gera erro.

Em JavaScript, String.raw mantém as barras invertidas como estão.

const banner = String.raw`
 _  _ ___ _    _    ___
| || | __| |  | |  / _ \
| __ | _|| |__| |_| (_) |
|_||_|___|____|____\___/
`;
console.log(banner);

Uma crase ou ${ dentro da arte encerra a template string. Normalmente é mais fácil trocar de fonte para essa arte.

Em Python, use uma raw string colocando r na frente.

BANNER = r"""
 _  _ ___ _    _    ___
| || | __| |  | |  / _ \
| __ | _|| |__| |_| (_) |
|_||_|___|____|____\___/
"""
print(BANNER)

Um banner de abertura não atrapalha se você seguir duas regras.

  • Não mostre quando a saída vai para outro programa, como um pipe ou um arquivo de log.
  • Ofereça uma opção como --quiet para desligá-lo.

Qual fonte usar?

Fonte Estilo
Standard O padrão seguro. Combina com qualquer nome
Slant Letras inclinadas, com sensação de velocidade
Small Um Standard menor. Bom para nomes longos
Banner Letras pesadas preenchidas com #. A que mais chama atenção
Digital Um banner pequeno de três linhas com cada letra numa caixa. Bom para comentários de código

As 12 fontes do lab.ascii usam só caracteres ASCII, então ficam intactas no GitHub, em terminais e em ambientes antigos. Banners de caracteres de bloco (█ ╗ ═) de outros geradores podem quebrar em ambientes muito antigos; se o banner precisa funcionar em qualquer lugar, escolha uma fonte ASCII.

Digite o nome do seu projeto no lab.ascii para comparar banners em 12 fontes e clique num card para copiar.

Mais guias