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

Все инструменты

Разработка

Как добавить ASCII-баннер в README на GitHub

Поместите его в блок кода Markdown и уложитесь в 80 столбцов.

Обновлено:

Название проекта в виде ASCII-баннера делает начало README заметнее. В отличие от картинки, это обычный текст: он не добавляет файлов в репозиторий и выглядит правильно и в светлой, и в тёмной теме.

Как добавить в README

В Markdown баннер должен стоять внутри блока кода. Вне его повторяющиеся пробелы схлопываются в один, а _ и * превращаются в разметку курсива и жирного шрифта — арт разваливается.

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

# my-project

Маленькая CLI-утилита, которую можно запустить прямо из терминала.
  • Слово text после открывающих апострофов отключает подсветку синтаксиса, и символы остаются одного цвета.
  • Добавьте под баннером настоящий текстовый заголовок (# my-project). Поисковики и программы чтения с экрана не прочтут баннер как название проекта.
  • Если в арте есть три апострофа подряд, оберните его четырьмя.

Не шире 80 столбцов

На GitHub блок кода прокручивается вбок, если строка слишком длинная. Обрезанный баннер теряет смысл, поэтому держитесь в пределах 80 столбцов, а если хотите, чтобы он помещался и на телефоне, — около 50.

Где читают Рекомендуемая ширина
README на GitHub на компьютере до 80 столбцов
Приложение GitHub, узкие экраны около 50 столбцов
Вывод в терминале до 80 столбцов

Для длинного названия выберите шрифт помельче, например Small или Mini вместо Standard или Big, или разбейте название на две строки. В правом верхнем углу каждой карточки шрифта на lab.ascii указана ширина результата.

Как добавить в комментарий к коду

Баннер в начале файла или большого раздела помогает ориентироваться в длинном файле.

/*
 *  ___ ___ _  _ ___  ___ ___
 * | _ \ __| \| |   \| __| _ \
 * |   / _|| .` | |) | _||   /
 * |_|_\___|_|\_|___/|___|_|_\
 */
export function render() {}
  • Начинайте каждую строку с маркера комментария (*, // или #).
  • Если в арте есть */, блочный комментарий на этом закончится. Для такого арта используйте строчные комментарии //.
  • Если в команде есть ограничение длины строки, например 100 символов, баннер должен в него укладываться.

Вывод при запуске программы

Чтобы выводить баннер при запуске CLI-утилиты, арт нужно хранить в строке. Проблема — обратный слеш (\). В большинстве языков он начинает escape-последовательность, поэтому при вставке арта как есть символы пропадают или возникает ошибка.

В JavaScript String.raw сохраняет обратные слеши как есть.

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

Обратный апостроф или ${ внутри арта завершают шаблонную строку. Обычно проще выбрать для такого арта другой шрифт.

В Python используйте «сырую» строку, поставив перед ней r.

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

Стартовый баннер не будет мешать, если соблюдать два правила.

  • Не выводите его, когда вывод уходит в другую программу, например в конвейер или лог-файл.
  • Дайте опцию вроде --quiet, чтобы его отключить.

Какой шрифт выбрать?

Шрифт Характер
Standard Надёжный вариант по умолчанию. Подходит к любому названию
Slant Наклонные буквы, ощущение скорости
Small Уменьшенный Standard. Хорош для длинных названий
Banner Тяжёлые буквы, заполненные #. Самый заметный
Digital Маленький трёхстрочный баннер, каждая буква в рамке. Хорош для комментариев в коде

Все 12 шрифтов lab.ascii используют только символы ASCII, поэтому не ломаются на GitHub, в терминалах и в старых средах. Баннеры из блочных символов (█ ╗ ═) из других генераторов могут ломаться в очень старых средах; если баннер должен работать везде, выберите ASCII-шрифт.

Введите название проекта на lab.ascii, сравните баннеры в 12 шрифтах и нажмите на карточку, чтобы скопировать.

Другие гайды