📓Файл Readme.md

Файл Readme представляет собой файл, который описывает цель репозитория/проекта, что это за проект, основные фишки, как использовать проект, как поднять/установить/скомпилировать/использовать у себя этот проект, какие настройки при этом нужно сделать, кто авторы проекта и прочая дополнительная информация, если таковая будет нужна.

Чаще всего этот файл хранится в корневой папке проекта. Он может иметь имя README.md, readme.txt, README, readme.1st (от read me first — сначала прочти меня), read.me и т.д. Иногда в проекте может быть несколько таких файлов на разных языках. Язык может указываться в расширении (readme.en, readme.ua, readme.ru), в самом названии (README-EN.md) или, к примеру, разделяться по соответствующим папкам (project/docs/guide-ru/README.md, project/docs/guide-de/README.md).

README должен быть простым и четким. Хороший README поможет сэкономить время как вашим коллегам, так и вам спустя некоторое время, если вы забудете что-то из указанной выше информации.

Что должно быть в ReadMe?

Файл README обычно включает в себя:

• Название проекта, его цель и возможности. Если это open-source библиотека, то постарайтесь сжато описать самые главные фишки, чтобы другой разработчик захотел использовать ваше творение.

• Информацию о системных требованиях, нужных для запуска и работы данного приложения (т.н. pre-requisites).

• Инструкции по установке и настройке приложения, чтобы любой желающий мог без проблем установить его.

• Инструкции по управлению и сопровождению приложения.

• Примеры использования и работы приложения.

• Информация о текущей стабильной/релизной версии и данные о работоспособности тестов (если таковые имеются).

• Информация о лицензии и авторском праве. Для open-source проектов, в основном, используется лицензия GNU или MIT.

• Контактную информацию — как связаться с автором (в случае, если вы хотите, чтобы с вами могли связаться).

• Известные ошибки и неисправности (иногда выносится в файл BUGS), а также инструкции по их устранению, если таковые имеются.

• Инструкция по обновлению программы, если у вас в новых версиях что-то поменялось, что требует изменений всех использующих ваш софт.

• Также, будет хорошим тоном описать эти изменения программы (обычно выносится в файлы типа CHANGELOG.md). Его содержимое, например, может быть таким:

readme

Bug - была исправлена ошибка Enh - было сделано улучшение Chg - было сделано изменение текущего функционала

Что значит расширение .md?

Markdown — это язык разметки текстов. По своей сути, Markdown представляет из себя инструмент для легкого и простого конвертирования текста в HTML документ. Он позволяет составлять документацию (и не только), используя легкий в чтении и понимании простой текстовый формат, который можно автоматически конвертировать в красивый XHTML (или HTML).

Две основные сферы применения Markdown:

1. Для добавления разметки туда, где невозможна реальная HTML разметка. Например, в простом текстовом файле или в тех же СМС, где невозможно выделение жирным, создание заголовков, выделение цитат и пр.

2. Для более удобного написания текстов для последующей конвертации в HTML или другие форматы.

На практике это выглядит таким образом - мы пишем что-то такое (не обращайте внимание на черную тему в IDE, она не влияет на сам текст):

readme

А на Github или Gitlab видим такую красивую HTML страницу:

readme

Таким образом, мы получаем простой в обращении конвертер из текста в HTML страницу.

Каждый сервис управления GIT-репозиториями (Github, Gitlab, Bitbucket и т.д.), имеет свои собственные пожелания по поводу форматирования файлов Markdown:

• Github

• Gitlab

• Bitbucket

В основном, эти рекомендации можно свести к тому, что если у вас есть два файла с именем README и README.md, предпочтительным является файл с именем README.md, и он будет использоваться для генерации сводки HTML страницы при заходе в репозиторий, плюс те правила форматирования, которые мы затронем в следующем разделе.

Форматирование MD файлов

• Старайтесь писать README.md на английском языке, используя только ASCII-символы:

  

  readme
• Если есть надобность и возможность, добавляйте файл с переведенной версией.

• Соблюдайте правило 120 символов в строке (в этом вам поможет вертикальная линия справа в файле в IDE от Jetbrains):

  

  readme
• Оставляйте одну пустую строку между абзацами.

• Подчеркивайте строку заголовка символами "минус" (больше вариантов будет ниже).

• Для отступов используйте пробелы, а не табуляцию.

Давайте более подробно рассмотрим основные способы форматирования .md файлов (дополнительную информацию можно посмотреть в шпаргалках на английском и русском языке).

• Разбиение на абзацы производится вставкой пустой строки между ними (нажмите "Enter" после абзаца). Горизонтальная полоса между абзацами (тег <hr>) - три или более звёздочек или дефисов:

  

  readme

  или

  

  readme
• Заголовки и прочее:

  

  readme
• Оформление ссылки по схеме:

  [Название ссылки](http://webdesign.ru.net адрес ссылки)

  Первая часть (в квадратных скобках) - будет видимой, левая часть (в круглых скобках) - не видимой. :

  

  readme

  Если заключить адрес в угловые скобки, то он автоматически станет ссылкой:

  

  readme
• Выделение жирным шрифтом:

  

  readme
• Выделение темным фоном прямо в тексте (обратные кавычки):

  

  readme
• Блок текста с более тёмным фоном: четыре пробела (и более) от начала каждой строки

  

  readme
• Блоки кода с подвеченным синтаксисом. Выделенный цветом фона блок с HTML кодом. Теги выделяются цветом по правилам HTML. При необходимости, можно указать другой язык блока кода (javascript, java и т.д.)

  

  readme

  

  readme

  

  readme
• Блок текста, выделенный тёмной полосой по левому краю (цитата)

  

  readme

  Допустимы вложенные цитаты (цитата в цитате). Тогда цитата второго уровня выделяется двумя знаками ">>", а цитата третьего уровня вложенности - тремя.

• Таблица с чередованием светлых и тёмных строк (зебра)

  

  readme
• <li> Листинг - ненумерованый список

  

  readme
• Нумерованный список создаётся ещё проще:

  

  readme
• Вставка изображения в текст

  

  readme

Несколько примеров README.md файлов:

• Простой, но хороший README HTTP-сервера Apache (попробуйте его перевести в красивую HTML страничку с помощью онлайн-конвертера).

• Красивая документация по nodejs и ее "сырой" текстовый вариант.

• Онлайн .md конвертеры с множеством примеров: здесь и здесь.

Плагин для удобной работы

Существует удобный плагин для работы с .md файлами в IDE от JetBrains (WebStorm, PHPStorm, Intellij Idea, PYCharm и т.д.) - он так и называется Markdown. Для того, чтобы установить его: заходим в настройки (Ctrl+Alt+S):

readme

Далее:

• Выбираем раздел Plugins.

• В строке поиска пишем Markdown.

• Находим нужный нам плагин и нажимаем на кнопку Install.

Высока вероятность того, что в вашей IDE данный плагин уже будет установлен и включен по умолчанию. Тогда никаких действий не требуется.

После установки, при открытии файла с расширением .md у вас появляется вот такое окошко:

readme

В блоке с номером 1, можно менять форматирование текста.

В блоке с номером 2, можно переключаться между видом этого окна:

• Только сырой markdown.

• Только готовый HTML вариант.

• 2 окна (как на скриншоте): слева - сырой markdown, справа - как это будет выглядеть на HTML странице после конвертации.

В блоках с номером 3 показано как сырой markdown текст сразу преобразовывается в красивый вид.