Правила оформления файла README.MD на GITHUB
Этот сайт построен на русской CMS Ruxe Engine!
Правила оформления файла README.MD на GITHUB
Если вы начали работу на GitHub, решили загрузить туда свой проект для совместной работы с единомышленниками, то, скорее всего, в первую очередь перед вами встанет проблема создания первого файла – файла «readme.md».
Можно, конечно, просто выложить простой, неформатированный текстовой файл. Но вам захочется сделать его удобочитаемым, чтобы ссылки были выделены, блоки кода, присутствовали таблицы и так далее…
Эта статья поможет вам в этом.
Для форматирования текста на GitHub используются достаточно простые правила. Я перечислю основные и достаточные, так как не претендую на полноту официального руководства.
Текст можно обработать в любом простом текстовом редакторе, например в Notepad++, которым пользуюсь сам. А можно и прямо на GitHub редактировать файл в он-лайн режиме.
Стилистическая разметка должна быть такой:
Разбиение на абзацы производится вставкой пустой строки между ними (нажмите «Enter» после абзаца).
Если заключить адрес в угловые скобки, то он автоматически станет ссылкой
Выделение жирным шрифтом
Выделение тёмным фоном прямо в тексте
Блок текста с более тёмным фоном, четыре пробела (и более) от начала каждой строки
Блоки текста с подвеченным синтаксисом. Выделенный цветом фона блок с html-кодом. Теги выделяются цветом по правилам html
Выделенный цветом фона блок с php-кодом. Теги выделяются цветом по правилам php
Выделенный цветом фона блок с каскадными таблицами. Теги выделяются цветом по правилам css
Блок текста, выделенный тёмной полосой по левому краю (цитата)
Таблица с чередованием светлых и тёмных строк (зебра)
Нумерованный список создаётся ещё проще:
Комбинируя эти маркеры вы сможете правильно разметить свой текст, сделать его более понятным.
Надеюсь, что эта статья будет вам полезна. Успехов в работе на GitHub!
UPDATE!
Вставка изображения в текст
Комментарии
Зарегистрируйтесь или войдите в Ваш аккаунт, чтобы оставить комментарий.
Как написать хороший README для вашего проекта на GitHub
Если вы читаете эту статью, это, вероятно, означает, что вы уже размещаете репозитории на GitHub и, возможно, даже вносите свой вклад в открытый исходный код. А если вы используете GitHub, то вам нужно писать хорошую документацию для своих проектов, чтобы помочь другим понять их.
Когда я впервые зашла на Github, честно говоря, я понятия не имела, что такое файл README (хотя я видела его в проектах других людей).
Во-первых, зачем мне хороший файл README?
Файл README — это руководство, которое дает пользователям подробное описание проекта, который вы разместили в своем репозитории.
Возможно, вам интересно, зачем тратить время на написание хорошего README. Вот несколько причин, которые помогут убедить вас в том, что это хорошая идея:
README должен ответить на следующие вопросы: что, почему и как:
Если в вашем проекте много функций, подумайте о том, чтобы добавить раздел «Возможности» и перечислить их здесь.
Как написать хороший файл README
Вот шаги, которые вы должны предпринять, чтобы написать README.
Включите название вашего проекта
Это название проекта. Он описывает весь проект одним предложением и помогает людям понять, какова основная цель и цель проекта.
Напишите описание
Ваше описание — чрезвычайно важный аспект проекта. Хорошо составленное описание позволяет продемонстрировать свою работу другим разработчикам, а также потенциальным работодателям.
Как установить ваш проект
Если ваш проект представляет собой программное обеспечение или приложение, которое требует установки, вы должны включить шаги, необходимые для установки вашего проекта. Предоставьте пошаговое описание того, как запустить среду разработки.
Как использовать ваш проект
Предоставьте инструкции и примеры, чтобы пользователи/участники могли использовать проект. Это упростит им задачу в случае, если они столкнутся с проблемой — у них всегда будет место для ссылки. Вы также можете вставить скриншоты, чтобы показать примеры работающего проекта.
Если вы работали над проектом как команда или организация, перечислите своих соавторов / членов команды. Вы также должны включить ссылки на их профили GitHub.
Как написать красивый и информативный README.md
Многие программисты лихо управляются с кодом и знают мельчайшие подробности своих проектов. Но некоторым из них (в том числе и мне) недостаёт коммуникативных навыков.
Удивительное дело: программист может потратить час на подгонку внутренних и внешних отступов для одной-единственной кнопки и не найти каких-то 15 минут на файл Readme описания проекта.
Надеюсь, вы уже знаете, что такое файл readme.md и для чего он нужен.На всякий случай попробую объяснить.
Что такое Readme.md?
README (буквально означает «прочти меня») — это первый файл, который нужно читать, получив доступ к проекту на Github или любой Git-хостинговой площадке. Этот файл в первую очередь и предлагается вниманию пользователя, когда он открывает здесь репозиторий того или иного проекта. Такой файл содержит кучу полезной информации, так что его вполне можно рассматривать как справочное руководство по проекту.
Посмотрите, где у нас здесь файл Readme:
Файл Readme.md находится в корневой папке репозитория и автоматически отображается в каталоге проекта на github.
Вот как выглядит файл разметки на github (здесь использован VSCode, который одновременно показывает нам файлы разметки и в режиме предварительного просмотра):
Здесь можно найти официальный гайд Github для формата разметки на тот случай, если вам захочется основательно разобраться в языке разметки.
Зачем тратить время на Readme?
Генерирование документации для ваших компонентов
Кроме readme проекта, для понятной кодовой базы необходимо документирование компонентов, благодаря которому упрощается сопровождение кода и повторное их (компонентов) использование. Для автоматического генерирования документации к компонентам, выкладываемым на bit.dev, можно использовать такие инструменты, как Bit (Github).
Создание краткого описания проекта
Для проекта надо подготовить хорошее описание. При составлении описания можно придерживаться такого плана:
Некоторые нюансы
Используемый здесь проект будем считать за образец. Ну, просто у него один из красивейших файлов readme, который мне приходилось видеть. Код файла Readme.md можно найти здесь:silent-lad/VueSolitaire
NOW WITH DRAG AND DROP Solitaire implemented by scratch on vue.js. It contains 3 types of solitaire namely spider(which…github.com
Чтобы показать код разметки, используйте значок карандаша:
1. Добавляем картинки
У вас может быть отличная фотографическая память, но интересующимся вашим проектом могут понадобиться фотографии его демо-версии.
Так, в описание нашего образцового проекта «Паук» в readme добавлены такие изображения:
Кроме изображений, вы можете добавить и видео-описание проекта. Вот только Github не разрешает добавлять видео в readme… Что же делать?
Используем gif
2. Элементы оформления
Элементы оформления создадут у читающего readme ощущение уникальности вашего проекта. Нестандартные или активно используемые элементы оформления для репозитория можно раздобыть здесь: https://shields.io
Персонализированные или настраиваемые элементы оформления, такие как количество звёзд в репозитории и процентный индикатор кода, берутся там же.
3. Добавляем интерактивную демо-версию
Если есть возможность, разместите проект на своих ресурсах и установите запускаемую демо-версию. Затем пропишите в README ссылку на демо. Кто знает, сколько людей могут заинтересоваться вашим проектом и решить протестировать его? А уж работодатели просто обожают интерактивные проекты. Этим вы покажете, что ваш проект не просто кусок кода, лежащий на github, но заодно продемонстрируете своё серьёзное отношение к делу.
Да, всё верно: в readme можно использовать гиперссылки, так что поместите ссылку на интерактивную демо-версию прямо под изображением с названием.
4. Форматируем код
Разметка даёт возможность форматировать текст, как код. Поэтому не пишите код, как обычный текст, а воспользуйтесь знаком `, чтобы придать коду аккуратный вид var a = 1;
Github также даёт возможность указывать язык, на котором написан код, и использовать соответствующее выделение текста, улучшая читаемость кода. Вот как это делается:
«` используется для многострочного кода и позволяет указывать язык блока кода. Сравните:
5. Используем HTML
Да, внутри можно использовать HTML. Не все функции, но большинство. Рекомендуется всё же придерживаться разметки, но некоторые функции, такие как выравнивание текста и изображений по центру, в readme доступны только с использованием HTML.
6. Творим
Всё остальное зависит от вас. Ведь каждому проекту нужен свой readme и свой тип описания. Так проявите изобретательность: те 15–20 минут, которые вы потратите на readme, могут произвести неизгладимое впечатление на посетителей вашего профиля на github.
Как написать readme github
Описание разметки файла README.md
получается разделительная черта
Заголовок первого уровня
Заголовок первого уровня также можно создать:
Заголовок второго уровня
Заголовок второго уровня также можно создать:
Заголовок третьего уровня
Заголовок четвертого уровня
Заголовок пятого уровня
Заголовок шестого уровня
Работа с выделением текста
Зачеркнутый текст (Strikethrough)
Для выделения текста жирным или наклонным и их сочетания можно использовать комбинации * или _
Жирный текст (bold)
Наклонный текст (italic)
Жирный наклонный текст (bold italic)
Жирный текст (bold)
Наклонный текст (italic)
Жирный наклонный текст (bold italic)
Тут странный текст
Использование эмодзи (emoji)
В самом тексте можно использовать эмодзи, например написать вот так:
✅ Это уже сделано
❎ Я не буду это делать
? делать или не делать, вот в чем вопрос?
В оригинале это выглядит так (в конце строки четыре (4) пробела для того, что бы был переход на новую строку):
Использование цитирования в тексте
Внешний вид, конечно, не очень, но может и пригодиться.
Если нужно выделить слово или фразу внутри строки, то используются одинарные обратные кавычки (`):
Дополнительно можно задавать язык кода внутри блока, указав его после первых трех кавычек:
Пример блока для C# :
Пример блока для Python :
Можно создавать многоуровневые списки. Каждый уровень отделяется четырьмя (4) пробелами:
Каждый уровень отделяется двумя пробелами.
Для Githib работа с нумерованными списками выглядит очень интересно. Каждый уровень отделяется четырьмя (4) пробелами:
При использовании смешанных списков нужно очень внимательно следить за нумерацией. Лучше, как и в нумерованных, использовать четыре (4) пробела для отделения уровня.
Также можно создавать многоуровневые списки задач. Каждый уровень отделяется четырьмя (4) пробелами:
Либо просто вставить ссылку, либо дополнительно задать текст ссылки (пробела между скобками быть не должно):
Второй вариант записывается так: [текст ссылки](адрес ссылки)
Вставка ссылки с картинкой на ролик с YouTube
Описание комбинации [](ссылка на страничку YouTube)
Пример:
[](https://youtu.be/RHPYGwVQB2o)
Что мы увидим: 
| LEFT | CENTER | RIGHT |
|---|---|---|
| По левому краю | По центру | По правому краю |
| текст | текст | текст |
Как написать прекрасный файл README на GitHub
Перевод статьи «How to Write an Awesome GitHub README».
Я прочел самый ранний (из тех, что смог найти) файл README. Он был написан в 1975 году Вильямом Дж. Эрлом из CS-отдела UIC. Текст суховат, но удивительно актуален даже 44 года спустя. «Из-за бага в компиляторе эта функция неправильно компилируется».
README это индикатор того, как поддерживается репозиторий. Причем, когда этот файл хороший, это не значит, что проект активный, не содержит багов и прекрасно покрыт тестами. Это показывает, что собственник репозитория заботится о вас, пользователе (или будущем мейнтейнере). Хороший README расскажет вам, как пользоваться этим проектом и как принять в нем участие. Он продает проект, но дает знать посетителям, что, возможно, им нужно другое решение. Таким образом этот файл как бы выражает уважение автора к читателям и экономит их время.
При использовании GitHub-профайла как части приложения файлы README приобретают особое значение. Они демонстрируют навыки технического письма – способность к хорошей коммуникации и умение собирать воедино документ, описывающий программу.
Трудно ожидать, что кто-то захочет погрузиться в ваш код, если ему не предоставили общего описания проекта. Поэтому файлы README просто необходимы.
Четкое описание
Люди должны иметь возможность использовать созданное вами программное обеспечение, даже если не прочтут ни строчки вашего кода.
Для начала, измените дефолтное название, которое дает GitHub. Например, смените python-ml-project-for-cat-lovers-2 на Cat Crawler — Classify Cat GIFs. Следующий шаг – объяснение вашего проекта в простейшей форме. Многие люди используют однострочный комментарий в самом верху. Например: «Бот для скачивания и индексации GIF-файлов с котами».
Следует учитывать, что чем длиннее описание, тем больше риск умственной перегрузки читателя.
Отредактируйте ваш текст. Используйте заголовки, переносы строк, разбивку на абзацы (два перевода строки, чтобы начать новый абзац, и
для разрыва строки. Шпаргалка.). Не стесняйтесь использовать логотипы продуктов и скриншоты. В отличие от прочей технической документации, здесь мультимедиа работает хорошо.
Если ваш репозиторий содержит что-то интересное и веселое, это должно отражаться в его описании! Безусловно, изложение текста в соответствии с правилами стилистики и композиции имеет значение, однако интернет это место, где классные программисты могут проявлять свое творческое начало. Обратите внимание на README проекта not-paid (спасибо большое его создателям), который помогает разработчикам сайтов обезопасить себя от недобросовестных клиентов.
Использование
Каким образом следует использовать ваш проект? Если это API, у вас должен быть приведен отрывок кода с самыми основными взаимодействиями. Более полная документация может быть изложена ниже или где-то в другом месте. Например, facebook/react в своем README дает небольшой фрагмент кода – маленький пример использования React. Используйте одинарные левые кавычки (`) для выделения кода и по три таких кавычки для разделения блоков кода. Для специфической подсветки синтаксиса указывайте язык сразу после первого экземпляра трех кавычек.
Покажите результат работы кода. Если можно приложить GIF – сделайте это! Файлы GIF очень помогают людям разобраться в том, что именно вы хотите им показать. Это великолепно использовано в README проекта alexfoxy/laxxx (библиотека для плавных web-анимаций).
Для создания GIF-файлов я использую инструмент с открытым кодом ShareX. Он просто выбирает область вашего экрана. Могу посоветовать и другое решение, тоже open source, – LICEcap.
Установка
Допустим, ваш посетитель хочет установить себе ваш проект после того, как увидел его в действии. Раздел с описанием установки иногда называется Getting Started («как начать»). Он должен быть в каждом проекте, даже если весь процесс установки заключается во введении в терминале команды npm install catcrawler.
Если ваш проект – статический сайт, скажите об этом! Напишите что-то вроде «Разместите родительский каталог на веб-сервере». Укажите, знание каких базовых инструментов понадобится читателю для установки. Не нужно пояснять, что такое pip или npm, просто перечислите все команды, которые нужно будет запускать при установке и первоначальной настройке.
У DEV есть очень основательный раздел о сборке и запуске. Это отличный пример, которому смело можно следовать, если хотите, чтобы ваш продукт был доступен людям. Хорошая практика при этом – запустить виртуальную машину и самому попробовать воспользоваться своим руководством по инсталляции.
Значки (Badges)
Значки на GitHub, главным образом стандартизированные при помощи badges/shields, это одна из первых вещей, на которые обращает внимание посетитель, прокручивая страницу. Значки со статусом сборки описывают стабильность проекта. Другие значки могут показывать активность репозитория, указывая количество коммитов за месяц или число мейнтейнеров. Все эти значки не обязательны, но, как и GIF, являются большим преимуществом.
У shields.io есть API для создания ваших собственных значков, а также npm-пакет, приятный в использовании. С его помощью я сделал и запустил несколько значков меньше, чем за час. Другая npm-альтернатива это badger. У Python есть pybadges от Google.
Участие в проекте (Contributing)
Если вам нужны соратники, то очень желательно добавить раздел для потенциальных контрибуторов. На GitHub есть стандарт добавления файла CONTRIBUTING.md в корневую папку. Там может быть изложен кодекс поведения и общие рекомендации по поиску проблем и созданию пул-реквестов. Такие пошаговые руководства могут помочь большому количеству новичков, жаждущих принять участие в open source проектах. Я знаю, что некоторые из моих друзей поддерживают только репозитории с четко прописанными правилами для мейнтейнеров.
Если вы не уверены, с чего начать, мне недавно попался генератор кодексов поведения, который, как мне кажется, очень хорошо исполнен.
Лицензия
Когда я ищу решение для каких-то рабочих вопросов, первое, на что я обращаю внимание, это лицензия. При создании репозитория на GitHub есть опция выбора лицензии, благодаря чему для вас будет сгенерирован файл LICENSE.md. У GitHub также есть страница, посвященная этому файлу, а еще они создали choosealicense.com – фантастическое руководство по всем возможным вариантам.
Лично я для своего открытого исходного кода использую лицензию MIT. У некоторых людей есть свое сложившееся мнение относительно лицензирования, особенно, когда речь идет о GPL. «Любые модификации программы, включающие код, лицензированный по лицензии GPL, также должны быть доступны под лицензией GPL вместе с инструкциями по сборке и установке».
Шаблоны
Существует много шаблонов README-файлов. Это прекрасный вариант «на крайний случай», но я обнаружил, что «из коробки» они не совсем подходят для небольших проектов. Конечный вариант получается слишком холодным. Шаблоны больше пригождаются более крупным, состоявшимся проектам, но с учетом времени, вложенного в разработку, все равно имеет смысл сделать собственное решение.
Вот это мой фаворит среди шаблонов. Мне он нравится, поскольку там все сделано четко и по сути, а кроме того есть два подраздела для тестов. Если у вас есть какие-то тесты, следует упомянуть об этом в вашем README. Первое, что я делаю при клонировании проекта, это запускаю тесты. Это позволяет удостовериться, что для разработки все готово.
Другие разделы
Разобравшись с основными разделами, можно дополнить README по своему вкусу. Возможно, я окажусь в меньшинстве, но мне нравится бродить по GitHub в поисках новых вещей и разбираться, как они устроены. Я благодарен репозиториям, в которых есть подробные файлы README с большим количеством примеров кода. Чтобы увлечься проектом, я должен видеть, что мейнтейнерам он интересен по крайней мере не меньше, чем мне.