Softonic

Генератор README

Шаг 1 / 4 README.md
Далее

Пустые репозитории производят плохое первое впечатление. Заполните имя проекта, слоган в одну строку, список возможностей, команду установки, фрагмент быстрого старта, автора и лицензию, и этот генератор выдаст аккуратный README в формате Markdown с правильной иерархией заголовков и огороженными блоками кода: разделы, которые GitHub показывает на странице вашего проекта. Скопируйте его, сохраните как README.md в корне репозитория и отправьте. Заголовки разделов написаны по-английски, что является почти универсальным соглашением для README с открытым исходным кодом; а ваш собственный текст отображается ровно так, как вы его вводите, на любом языке.

Как составить README

  1. 1

    Добавьте основное

    Имя проекта, необязательный URL репозитория и слоган в одну строку. Имя становится заголовком `#`; слоган становится цитатой под ним.

  2. 2

    Перечислите возможности и быстрый старт

    По одной возможности в строке (каждая становится пунктом списка), плюс короткий фрагмент быстрого старта, который оборачивается в огороженный блок кода.

  3. 3

    Установка, лицензия и автор

    Команда установки помещается в блок кода `bash` под разделом установки; добавьте лицензию (MIT, Apache-2.0…) и необязательную строку автора.

  4. 4

    Скопируйте Markdown

    Нажмите «Копировать» и вставьте результат как `README.md` в корень репозитория. Отправьте его, и отрендеренная версия появится на странице проекта.

Что содержит хороший README

Собственное руководство по стилю GitHub и широко используемая спецификация standard-readme сходятся в порядке разделов. Разместите легко просматриваемые части наверху: посетитель, попавший в ваш репозиторий, за 20 секунд решает, читать ли дальше.

Раздел Позиция Назначение
Заголовок + слоган Строки 1–2 # Project, за которым следует одно предложение о том, что он делает
Бейджи Строки 3–5 Статус CI, версия npm, лицензия, покрытие
Установка В начале Одна команда, которую можно скопировать
Использование В начале Минимальный рабочий фрагмент, дающий результат
API / параметры Середина Таблицы флагов, ключей конфигурации или конечных точек
Вклад Ближе к концу Ссылка на CONTRIBUTING.md, кодекс поведения, правила оформления PR
Лицензия В конце Идентификатор SPDX и ссылка на LICENSE

Бейджи, которые действительно помогают

URL-адреса shields.io следуют предсказуемой схеме: https://img.shields.io/badge/<label>-<message>-<color>.svg. Полезные «живые» бейджи указывают на статус сборки, версию пакета и число загрузок, а не на тщеславные метрики. Обычно достаточно четырёх бейджей; а больше уже лишнее.

Частые ошибки в README

  • Нет команды установки в первой строке раздела «Установка». Читатели ищут глазами npm install или pip install; спрячете её за прозой, и они уйдут.
  • Скриншоты по 3 МБ. Уменьшите до 800 пикселей по ширине и сожмите; GitHub всё равно их отдаст, но мобильные читатели платят за трафик.
  • Устаревшие бейджи. Красный бейдж CI говорит посетителям, что проект сломан. Либо почините CI, либо уберите бейдж.
  • Отсутствует лицензия. Без лицензии ваш код по умолчанию «все права защищены», и компании не могут его использовать.

Часто задаваемые вопросы

Да. Огороженные блоки кода, маркированные списки и заголовки в стиле ATX (префикс #) отображаются на GitHub, GitLab и Bitbucket без изменений. Команда установки помечается как блок bash; блок быстрого старта оставлен без тега, чтобы вы сами задали язык.

Для большинства экосистем, README.md. Используйте .rst только если вы публикуете пакет Python, документация которого размещена на Read the Docs, и хотите, чтобы Sphinx переиспользовал файл как посадочную страницу.

Когда вы указываете URL репозитория, генератор добавляет один статический бейдж лицензии (https://img.shields.io/badge/license-<type>-blue.svg). Для «живых» бейджей (статус сборки, версия, загрузки) скопируйте шаблон URL shields.io и вставьте его в вывод самостоятельно.

Нет. README собирается из значений формы, и ничего не сохраняется. Закройте вкладку, и данные исчезнут.

Сопутствующие инструменты

Справочная таблица ASCII

Полная таблица ASCII от 0 до 127 с десятичным, шестнадцатеричным, восьмеричным и двоичным представлением, а также записью числовых ссылок HTML, включая NUL, LF и DEL.

Справочник символов HTML

Справочник HTML-сущностей с поиском, их именованными и числовыми кодами, а также копированием специальных символов и знаков одним кликом.

Справочник сочетаний клавиш

Ищите документированные сочетания по умолчанию для VS Code, Chrome и Bash с GNU Readline в macOS, Windows и Linux.

Конвертер размера файлов

Преобразуйте значения между байтами, КБ, МБ, ГБ, ТБ и двоичными единицами IEC (KiB, MiB, GiB, TiB), свободно сочетая десятичные и двоичные единицы.

Генератор случайных букв

Генерируйте случайные буквы A-Z. Выберите количество, верхний или нижний регистр либо смешанный вариант для игр, заданий и уроков.

Конвертер CMYK в RGB

Преобразуйте проценты CMYK в приблизительные значения RGB и Hex для быстрого экранного предпросмотра по стандартной формуле.

Инструмент доступен на других языках