Файл Readme.md
Last updated
Last updated
Файл 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 проектов, в основном, используется лицензия или .
Контактную информацию — как связаться с автором (в случае, если вы хотите, чтобы с вами могли связаться).
Известные ошибки и неисправности (иногда выносится в файл BUGS), а также инструкции по их устранению, если таковые имеются.
Инструкция по обновлению программы, если у вас в новых версиях что-то поменялось, что требует изменений всех использующих ваш софт.
Также, будет хорошим тоном описать эти изменения программы (обычно выносится в файлы типа CHANGELOG.md). Его содержимое, например, может быть таким:
Bug - была исправлена ошибка Enh - было сделано улучшение Chg - было сделано изменение текущего функционала
Что значит расширение .md?
Markdown — это язык разметки текстов. По своей сути, Markdown представляет из себя инструмент для легкого и простого конвертирования текста в HTML документ. Он позволяет составлять документацию (и не только), используя легкий в чтении и понимании простой текстовый формат, который можно автоматически конвертировать в красивый XHTML (или HTML).
Две основные сферы применения Markdown:
Для добавления разметки туда, где невозможна реальная HTML разметка. Например, в простом текстовом файле или в тех же СМС, где невозможно выделение жирным, создание заголовков, выделение цитат и пр.
Для более удобного написания текстов для последующей конвертации в HTML или другие форматы.
На практике это выглядит таким образом - мы пишем что-то такое (не обращайте внимание на черную тему в IDE, она не влияет на сам текст):
А на Github или Gitlab видим такую красивую HTML страницу:
Таким образом, мы получаем простой в обращении конвертер из текста в HTML страницу.
Каждый сервис управления GIT-репозиториями (Github, Gitlab, Bitbucket и т.д.), имеет свои собственные пожелания по поводу форматирования файлов Markdown:
В основном, эти рекомендации можно свести к тому, что если у вас есть два файла с именем README и README.md, предпочтительным является файл с именем README.md, и он будет использоваться для генерации сводки HTML страницы при заходе в репозиторий, плюс те правила форматирования, которые мы затронем в следующем разделе.
Форматирование MD файлов
Старайтесь писать README.md на английском языке, используя только ASCII-символы:
Если есть надобность и возможность, добавляйте файл с переведенной версией.
Соблюдайте правило 120 символов в строке (в этом вам поможет вертикальная линия справа в файле в IDE от Jetbrains):
Оставляйте одну пустую строку между абзацами.
Подчеркивайте строку заголовка символами "минус" (больше вариантов будет ниже).
Для отступов используйте пробелы, а не табуляцию.
Разбиение на абзацы производится вставкой пустой строки между ними (нажмите "Enter" после абзаца). Горизонтальная полоса между абзацами (тег <hr>) - три или более звёздочек или дефисов:
или
Заголовки и прочее:
Оформление ссылки по схеме:
[Название ссылки](http://webdesign.ru.net адрес ссылки)
Первая часть (в квадратных скобках) - будет видимой, левая часть (в круглых скобках) - не видимой. :
Если заключить адрес в угловые скобки, то он автоматически станет ссылкой:
Выделение жирным шрифтом:
Выделение темным фоном прямо в тексте (обратные кавычки):
Блок текста с более тёмным фоном: четыре пробела (и более) от начала каждой строки
Блоки кода с подвеченным синтаксисом. Выделенный цветом фона блок с HTML кодом. Теги выделяются цветом по правилам HTML. При необходимости, можно указать другой язык блока кода (javascript, java и т.д.)
Блок текста, выделенный тёмной полосой по левому краю (цитата)
Допустимы вложенные цитаты (цитата в цитате). Тогда цитата второго уровня выделяется двумя знаками ">>", а цитата третьего уровня вложенности - тремя.
Таблица с чередованием светлых и тёмных строк (зебра)
<li> Листинг - ненумерованый список
Нумерованный список создаётся ещё проще:
Вставка изображения в текст
Несколько примеров README.md файлов:
Плагин для удобной работы
Существует удобный плагин для работы с .md файлами в IDE от JetBrains (WebStorm, PHPStorm, Intellij Idea, PYCharm и т.д.) - он так и называется Markdown. Для того, чтобы установить его: заходим в настройки (Ctrl+Alt+S):
Далее:
Выбираем раздел Plugins.
В строке поиска пишем Markdown.
Находим нужный нам плагин и нажимаем на кнопку Install.
Высока вероятность того, что в вашей IDE данный плагин уже будет установлен и включен по умолчанию. Тогда никаких действий не требуется.
После установки, при открытии файла с расширением .md у вас появляется вот такое окошко:
В блоке с номером 1, можно менять форматирование текста.
В блоке с номером 2, можно переключаться между видом этого окна:
Только сырой markdown.
Только готовый HTML вариант.
2 окна (как на скриншоте): слева - сырой markdown, справа - как это будет выглядеть на HTML странице после конвертации.
В блоках с номером 3 показано как сырой markdown текст сразу преобразовывается в красивый вид.
Давайте более подробно рассмотрим основные способы форматирования .md файлов (дополнительную информацию можно посмотреть в шпаргалках на и языке).
Простой, но хороший README HTTP-сервера (попробуйте его перевести в красивую HTML страничку с помощью онлайн-конвертера).
Красивая по nodejs и ее "сырой" вариант.
Онлайн .md конвертеры с множеством примеров: и .
