Как написать readme github

Введение

Markdown — это удобный для чтения язык для форматирования обычного текста. Вы можете использовать синтаксис Markdown вместе с некоторыми дополнительными HTML-тегами для форматирования записи в GitHub, в таких местах, как репозиторий READMEs и комментарии к запросам на вытягивание и проблемам. В этом руководстве вы узнаете о некоторых расширенных функциях форматирования, создав или изменив файл сведений для профиля GitHub.

Если вы не знакомы с Markdown, вам может потребоваться начать с курса «Basic writing and formatting syntax» или курса Взаимодействие с помощью Markdown GitHub Skills.

Если у вас уже есть файл сведений профиля, вы можете следовать этому руководству, добавив некоторые функции в существующий файл СВЕДЕНИЙ или создав gist с файлом Markdown, который называется чем-то вроде about-me.md. Дополнительные сведения см. в разделе Creating gists.

Создание или изменение файла сведений профиля

Файл сведений профиля позволяет делиться сведениями о себе с сообществом на GitHub.com. Файл сведений отображается в верхней части страницы профиля.

Если у вас еще нет файла сведений профиля, его можно добавить.

1. Создайте репозиторий с тем же именем, что и имя пользователя GitHub, инициализировав репозиторий README.md с помощью файла. Дополнительные сведения см. в разделе Managing your profile README.
2. Измените README.md файл и удалите текст шаблона (начало ### Hi there), который автоматически добавляется при создании файла.

Если у вас уже есть файл сведений о профиле, его можно изменить на странице профиля.

1. В правом верхнем углу любой страницы GitHub нажмите фото своего профиля, затем выберите Ваш профиль.

2. Щелкните рядом с файлом сведений профиля.

   

Добавление изображения в соответствии с вашими посетителями

В GitHub можно включать изображения. Здесь вы добавите адаптивное изображение, например баннер, в верхнюю часть profile README.

С помощью элемента HTML <picture> с функцией prefers-color-scheme мультимедиа можно добавить изображение, которое изменяется в зависимости от того, использует ли посетитель светлый или темный режим. Дополнительные сведения см. в разделе Managing your theme settings.

1. Скопируйте и вставьте следующую разметку в файл README.md.

2. Замените заполнители в разметке URL-адресами выбранных изображений. Кроме того, чтобы сначала опробовать эту функцию, можно скопировать URL-адреса из нашего примера ниже.

   • Замените YOUR-DARKMODE-IMAGE URL-адресом изображения, отображаемого для посетителей в темном режиме.
   • Замените YOUR-LIGHTMODE-IMAGE URL-адресом изображения, отображаемого для посетителей в светлом режиме.
   • Замените YOUR-DEFAULT-IMAGE URL-адресом отображаемого изображения, если ни один из других изображений не может быть сопоставлен, например, если посетитель использует браузер, который не поддерживает эту функцию prefers-color-scheme .

3. Чтобы сделать изображение доступным для посетителей, использующих средство чтения с экрана, замените YOUR-ALT-TEXT его описанием.

4. Чтобы проверить правильность отображения изображения, перейдите на вкладку Предварительный просмотр .

Дополнительные сведения об использовании изображений в Markdown см. в разделе Basic writing and formatting syntax.

Пример адаптивного изображения

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/25423296/163456776-7f95b81a-f1ed-45f7-b7ab-8fa810d529fa.png">
  <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
  <img alt="Shows an illustrated sun in light mode and a moon with stars in dark mode." src="https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png">
</picture>

Как выглядит изображение

Добавление таблицы

Таблицы Markdown можно использовать для упорядочения информации. Здесь вы будете использовать таблицу, чтобы представить себя, ранжируя что-то, например ваши наиболее часто используемые языки программирования или платформы, то, что вы тратите свое время на обучение, или ваши любимые хобби. Если столбец таблицы содержит числа, полезно выровнять столбец по правому краю, используя синтаксис --: под строкой заголовка.

1. Вернитесь на вкладку Изменить .

2. Чтобы представиться, две строки под тегом </picture> , добавьте заголовок ## About me и короткий абзац о себе, как показано ниже.

   ## About me
   
   Hi, I'm Mona. You might recognize me as GitHub's mascot.
   

3. В двух строках под этим абзацем вставьте таблицу, скопировав и вставив следующую разметку.

4. В столбце справа замените THING-TO-RANK словами «Языки», «Хобби» или другими словами и заполните столбец своим списком вещей.

5. Чтобы проверить правильность отображения таблицы, перейдите на вкладку Предварительный просмотр .

Дополнительные сведения см. в разделе Organizing information with tables.

Пример таблицы

## About me

Hi, I'm Mona. You might recognize me as GitHub's mascot.

| Rank | Languages |
|-----:|-----------|
|     1| Javascript|
|     2| Python    |
|     3| SQL       |

Как выглядит таблица

Добавление свернутого раздела

Чтобы сохранить содержимое в порядке, можно использовать <details> тег для создания разворачиваемого свернутого раздела.

1. Чтобы создать свернутый раздел для созданной таблицы, заключите таблицу в <details> теги, как показано в следующем примере.

2. <summary> Между тегами замените THINGS-TO-RANK на то, что вы ранжированы в таблице.

3. При необходимости, чтобы по умолчанию раздел отображалось как открытый, добавьте open атрибут в <details> тег .

   <details open>
   

4. Чтобы проверить правильность отображения свернутого раздела, перейдите на вкладку Предварительный просмотр .

Пример свернутого раздела

<details>
<summary>My top languages</summary>

| Rank | Languages |
|-----:|-----------|
|     1| Javascript|
|     2| Python    |
|     3| SQL       |

</details>

Как выглядит свернутый раздел

Добавление цитаты

В Markdown есть много других вариантов форматирования содержимого. Здесь вы добавите горизонтальное правило для разделения страницы и блок-кавычки для форматирования любимой цитаты.

1. В нижней части файла в двух строках под </details> тегом добавьте горизонтальное правило, введя три или более дефисов.

   ---
   

2. Под строкой --- добавьте цитату, введя разметку, как показано ниже.

   > QUOTE
   

   Замените QUOTE цитатой по своему выбору. Кроме того, можно скопировать цитату из приведенного ниже примера.

3. Чтобы убедиться, что все отображается правильно, откройте вкладку Предварительный просмотр .

Пример цитаты

---
> If we pull together and commit ourselves, then we can push through anything.

— Mona the Octocat

Как выглядит цитата

Вы можете использовать синтаксис комментариев HTML, чтобы добавить комментарий, который будет скрыт в выходных данных. Здесь вы добавите комментарий, чтобы напомнить себе, что позже обновите README.

1. В двух строках под заголовком ## About me вставьте комментарий, используя следующую разметку.

   <!-- COMMENT -->
   

   Замените COMMENT элементом to-do, чтобы напомнить себе о необходимости выполнить что-то позже (например, добавить дополнительные элементы в таблицу).

2. Чтобы убедиться, что комментарий скрыт в выходных данных, перейдите на вкладку Предварительный просмотр .

## About me

<!-- TO DO: add more details about me later -->

Сохранение работы

Если вы довольны изменениями, сохраните профилировать файл сведений, нажав кнопку Зафиксировать изменения.

Фиксация непосредственно в main ветви сделает изменения видимыми для любого посетителя в вашем профиле. Если вы хотите сохранить свою работу, но не готовы сделать ее видимой в своем профиле, можно выбрать Создать новую ветвь для этой фиксации и запустить запрос на вытягивание.

Дальнейшие действия

• Ознакомьтесь с дополнительными функциями форматирования. Например, см. «Creating diagrams» и «Creating and highlighting code blocks».
• Используйте новые навыки при общении в GitHub, в вопросах, запросах на вытягивание и обсуждениях. Дополнительные сведения см. в разделе Communicating on GitHub.

Время на прочтение
14 мин

Количество просмотров 96K

Летом 2020 года GitHub позволила пользователям создавать персональные README-файлы и с их помощью кастомизировать свои профили. Сама платформа при создании подобного файла предлагает уже готовый шаблон, в который можно вписать свои данные. Но о какой кастомизации может идти речь, если у всех будут одинаково оформленные профили? За почти два года сообщество придумало множество различных способов выделиться и особенно оформить свою страницу на GitHub.

Создаем README.md профиля

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

Для редактирования файла понадобятся знание Markdown-разметки и базовое понимание HTML. Оба навыка не сложны в освоении и интуитивно понятны в том объеме, который необходим для кастомизации профиля. На самом деле можно ограничиться только Markdown, но его особенность в том, что текст автоматически выравнивается по левому краю и нет никакой возможности повлиять на это. А HTML в тандеме с Markdown позволяет контролировать расположение объектов на экране. Для создания интерактивных блоков понадобится понимание того, как устроен сервис GitHub Actions, но нужны тоже только лишь базовые знания. Глубокие понадобятся только в том случае, если захочется создать собственный динамический виджет.

Заголовок

Как уже и говорилось ранее, заголовки можно писать как с помощью Markdown, так и с помощью HTML. Последний способ поможет разместить текст по центру, что мне больше нравится — выделяется на фоне основного текста. Заголовок обычно содержит в себе приветствие, обращенное к посетителю профиля. Имя в моем заголовке оформлено в виде ссылки и ведет на сайт-визитку, в конце расположен эмодзи с машущей рукой, значок анимированный. Второй строчкой можно коротко рассказать о своей деятельности, чтобы посетителю сразу было ясно, с кем он имеет дело.

Оформляется все это дело вот такой нехитрой HTML-конструкцией:

<h1 align="center">Hi there, I'm <a href="https://daniilshat.ru/" target="_blank">Daniil</a> 
<img src="https://github.com/blackcater/blackcater/raw/main/images/Hi.gif" height="32"/></h1>
<h3 align="center">Computer science student, IT news writer from Russia 🇷🇺</h3>

Можно сделать с помощью Markdown, но тогда не получится выровнять текст по центру и будут сложности с гифкой — в Markdown не предусмотрены теги для указания размеров изображения:

# Hi there, I'm [Daniil](https://daniilshat.ru/) ![](https://github.com/blackcater/blackcater/raw/main/images/Hi.gif) 
### Computer science student, IT news writer from Russia 🇷🇺

Некоторые умельцы вовсе отказываются от текстовых заголовков и используют баннеры в их качестве. Баннер можно сделать самостоятельно в любом удобном редакторе изображений или использовать конструкторы, например, REHeader.

Картинку можно вставить как с помощью Markdown, так и с помощью HTML. Опять же, последний вариант позволяет контролировать расположение изображения и его размер:

![Описание](ссылка)

<img src="путь к файлу" alt="альтернативный текст">

Можно использовать необычные шрифты. К сожалению, нет возможности подключить CSS-стили и полноценно кастомизировать внешний вид текста, но можно найти подходящий шрифт, набрать необходимый текст и вставить в README.md. Для этих целей подойдут сервисы, излюбленные пользователями Twitter и Instagram. Все шрифты из подобных конвертеров включены в таблицу символов Unicode и корректно отображаются на всех современных платформах.

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

<!---Пример кода-->
[![Typing SVG](https://readme-typing-svg.herokuapp.com?color=%2336BCF7&lines=Computer+science+student)](https://git.io/typing-svg)

О себе

После заголовка принято рассказывать о себе, представлять свои навыки, возможности и давать ссылки для обратной связи. Это, конечно же, необязательное условие, можно расположить блоки в любой последовательности, но в этой части статьи рассмотрим именно те инструменты, которые помогут организовать блок «О себе».

• Simple Icons — огромная коллекция иконок популярных брендов, компаний, технологий и сервисов в svg-формате. У проекта есть сайт, на котором можно найти удобную иконку и скачать себе, а потом использовать в своем md-файле. Вставлять изображения лучше с помощью HTML — так удобнее задавать необходимый размер.

• Markdown Badges — библиотека бейджей с готовыми фрагментами md-кодов для вставки. Коллекция обширная, можно найти необходимые языки программирования, технологии и оформить блок, к примеру, навыков.

• Shields.io — инструмент для генерации кастомных бейджей. Можно выбрать из готовых шаблонов и подогнать под свой случай, а можно настроить полностью с нуля.

Статистика

В README-файл профиля можно добавлять различные виджеты со статистическими данными о себе и свой деятельности на GitHub. Данные автоматически обновляются с некоторой периодичностью и в профиле всегда отображается актуальная информация:

• GitHub Trophy — добавляет в профиль трофеи и ачивки. Награды показывают, насколько пользователь активно ведет свой профиль. Для выбора доступно более десяти различных цветовых схем, что позволяет настроить виджет под свой стиль оформления. Также можно выбрать различные варианты расположения наград и включить фильтрацию. Для добавления необходимо вставить следующий md-код в свой файл, параметр username= необходимо заменить на свой никнейм на платформе.

[![trophy](https://github-profile-trophy.vercel.app/?username=ryo-ma)](https://github.com/ryo-ma/github-profile-trophy)

• Longest streak stats — добавляет виджет, показывающий актуальную продолжительность ежедневных сессий на GitHub, самую длинную сессию за все время и суммарное количество вкладов в сообщество. Автор виджета предлагает подробную инструкцию по его настройке, но вместе с этим предоставляет и визуальный конструктор, позволяющий настроить необходимую цветовую схему. Кроме этого, в репозитории разработчика имеется руководство по развертыванию приложения на собственном сервере. Если вставлять код из примеров, то параметр user= надо заменить на свой никнейм, если создавать собственный дизайн в конструкторе, то система выдаст необходимый код для вставки.

[![GitHub Streak](https://github-readme-streak-stats.herokuapp.com/?user=DenverCoder1)](https://git.io/streak-stats)

• Top Languages Card — виджет, выводящий статистику по часто используемым языкам в репозиториях пользователя. Можно выводить информацию как по всем репозиториям в профиле, так и только по избранным. Есть возможность удалить некоторые языки и никогда не показывать их в поле активности. Также можно выбрать компактный и более подробный вид карточки. Есть поддержка разных цветовых схем. При вставке кода необходимо заменить параметр username= на свой никнейм.

<!---Для компактной версии-->
[![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra&layout=compact)](https://github.com/anuraghazra/github-readme-stats)

<!---Для подробной версии-->
[![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=anuraghazra)](https://github.com/anuraghazra/github-readme-stats)

• GitHub Stats Card — карточка от разработчика прошлого виджета. Виджет выводит основную информацию о деятельности пользователь на платформе — общее количество звезд, коммитов и вкладов в сообщество. Также карточка отображает оценку пользователя, сравнивая его деятельность с другими юзерами GitHub. Доступно около десятка уже готовых тем, но можно настроить и уникальную. Ненужные позиции в статистике можно скрыть. Для вставки все так же надо скопировать код, добавить в свой файл и заменить параметр username= на актуальный.

[![Anurag's GitHub stats](https://github-readme-stats.vercel.app/api?username=anuraghazra)](https://github.com/anuraghazra/github-readme-stats)

• GitHub Extra Pins — и уже третья карточка все от того же самого разработчика. GitHub позволяет закреплять на странице профиля не более 6 репозиториев, но если этого мало, то можно добавить их в README-файл в виде карточки и не ограничиваться только 6 проектами. Для вставки надо заменить параметры username= на актуальный никнейм, repo= на название необходимого репозитория, а в скобках указать ссылку на сам репозиторий.

[![Readme Card](https://github-readme-stats.vercel.app/api/pin/?username=anuraghazra&repo=github-readme-stats)](https://github.com/anuraghazra/github-readme-stats)

• Codewars — баннер со статистикой сервиса с задачами для программистов. Виджет показывает количество решенных задач и актуальный уровень пользователя на платформе. Ссылки на карточки можно найти в своем профиле, нажав на кнопку «View Profile Badges» под аватаркой. Цветовые схемы нельзя выбрать и нет широкой возможности кастомизации, но доступны три размера — большой, маленький и крошечный. Если сложно найти, то можно скопировать код для карточки необходимого размера, заменить оба поля username на актуальный никнейм на платформе Codewars и вставить в свой md-файл.

Большой (large):  
[![codewars](https://www.codewars.com/users/username/badges/large)](https://www.codewars.com/users/username)   

Маленький (small):  
[![codewars](https://www.codewars.com/users/username/badges/small)](https://www.codewars.com/users/username) 

Крошечный (micro):  
[![codewars](https://www.codewars.com/users/username/badges/micro)](https://www.codewars.com/users/username) 

• LeetCode Readme Stats — виджет будет полезен любителям порешать задачки на сервисе LeetCode. Карточка выводит данные о количестве решенных задач с распределением по уровню сложности. Есть две темы — светлая и темная. Также у автора имеется инструкция по настройке отслеживания статистики с помощью GitHub Actions. Параметр username= необходимо заменить на актуальный.

Светлая тема:  
[![KnlnKS's LeetCode stats](https://leetcode-stats-six.vercel.app/api?username=KnlnKS)](https://github.com/KnlnKS/leetcode-stats)


Темная тема:  
[![KnlnKS's LeetCode stats](https://leetcode-stats-six.vercel.app/api?username=KnlnKS&theme=dark)](https://github.com/KnlnKS/leetcode-stats)

• GitHub Profile Views Counter — небольшой бейдж, выводящий информацию о количестве посетителей профиля. В поиске GitHub можно найти несколько репозиториев с реализацией виджета, но устроены они приблизительно одинаково, поэтому рассмотрим на примере самого популярного. Бейдж можно персонализировать, выбрав цвет из готовых или указать необходимый в шестнадцатеричной системе, на выбор есть три разных дизайна и возможность изменить исходный текст бейджа. Для вставки надо заменить поле your-github-username на соответствующее своему никнейму.

![](https://komarev.com/ghpvc/?username=your-github-username)

• Github Readme Activity Graph — виджет с графиком активности на платформе за последний месяц. Для персонализации имеется более 10 готовых тем, поэтому можно спокойно подобрать что-то подходящее под свои нужды. Если ничего не понравится, то у разработчика есть подробная инструкция по кастомизации. Вставка производится уже привычным способом — копируем код, меняем параметр username= на нужный и вставляем в свой md-файл.

[![Ashutosh's github activity graph](https://activity-graph.herokuapp.com/graph?username=Ashutosh00710)](https://github.com/ashutosh00710/github-readme-activity-graph)

• GitHub Readme StackOverflow — виджет позволяет делиться статистикой вклада в сообщество StackOverflow. На выбор есть две темы и два размера карточки. Для вставки в свой README профиля надо скопировать код, заменить параметр userID= на свой. С помощью параметра theme= можно выбрать нужную тему — ligh и dark, а с помощью layout= размер — default и compact. Своего профиля на StackOverflow у меня нет, поэтому продемонстрирую все на примере аккаунта автора виджета.

Светлая большая:  
[![Omid Nikrah StackOverflow](https://github-readme-stackoverflow.vercel.app/?userID=6558042)](https://stackoverflow.com/users/6558042/omid-nikrah) 

Темная большая:   
[![Omid Nikrah StackOverflow](https://github-readme-stackoverflow.vercel.app/?userID=6558042&theme=dark)](https://stackoverflow.com/users/6558042/omid-nikrah)  

Светлая маленькая:   
[![Omid Nikrah StackOverflow](https://github-readme-stackoverflow.vercel.app/?userID=6558042&layout=compact)](https://stackoverflow.com/users/6558042/omid-nikrah)

Темная маленькая:   
[![Omid Nikrah StackOverflow](https://github-readme-stackoverflow.vercel.app/?userID=6558042&layout=compact&theme=dark)](https://stackoverflow.com/users/6558042/omid-nikrah)

• GitHub Profile Summary Cards — еще одна библиотека карточек, выводит основную информацию по популярным языкам, график активности и общие сведения об аккаунте. Встраивать можно как с помощью Markdown, так и с помощью GitHub Actions. Для выбора доступно ровно десять цветовых схем. В репозитории есть инструкция, но также имеется и веб-приложение для генерации необходимых ссылок. Код для вставки (username= меняем на свой ник, а theme= на название темы из списка):

Карточка профиля: 
![](https://github-profile-summary-cards.vercel.app/api/cards/profile-details?username=daniilshat&theme=solarized_dark)

Статистика языков в коммитах:
![](https://github-profile-summary-cards.vercel.app/api/cards/most-commit-language?username=daniilshat&theme=solarized_dark)

Статистика языков в репозиториях:
![](https://github-profile-summary-cards.vercel.app/api/cards/repos-per-language?username=daniilshat&theme=solarized_dark)

Статистика профиля:
![](https://github-profile-summary-cards.vercel.app/api/cards/stats?username=daniilshat&theme=solarized_dark)

Данные по коммитам за сутки:
![](https://github-profile-summary-cards.vercel.app/api/cards/productive-time?username=daniilshat&theme=solarized_dark)

GitHub Actions

GitHub Actions позволяет пользователям автоматизировать свои репозитории. Но можно приспособить технологию под динамический вывод информации в README.md профиля. Некоторые умельцы умудряются таким образом встраивать в свои профили мини-игры и виджеты с отображением информации в реальном времени.

• Waka Readme Stats — позволяет динамически выводить статистику из сервиса Wakatime в свой профиль GitHub. Можно выбрать, какую именно информацию надо выводить. Это может быть статистика по языкам программирования использованным за неделю, количество коммитов в разное время суток, статистика по часто используемым средам разработки и операционным системам. Сам сервис Wakatime собирает эти данные с помощью плагинов, которые доступны для большого количества популярных IDE, браузеров и редакторов кода. Он анализирует информацию и формирует из нее детальный дашборд в личном кабинете пользователя, а с помощью скрипта можно выводить избранные данные в профиль и настраивать периодичность обновления информации. У автора репозитория есть подробная инструкция по настройке GitHub Actions для взаимодействия с Wakatime.

• Blog post workflow — репозиторий рассказывает, как настроить вывод последних постов из блогов или социальных сообществ в md-файл. У автора репозитория есть подробные инструкции по интеграции с Dev.to, Medium, Stackoverflow, Reddit, YouTube и другими популярными платформами. Но можно воспользоваться RSS-ссылкой и выводить последние посты из собственного блога. В этой статье рассмотрим инструкцию о том, как выводить посты с Хабра в свой профиль GitHub. Во-первых, у нас уже должен быть создан md-файл профиля. Во-вторых, надо открыть этот файл и в необходимом месте вставить следующую конструкцию:

<!-- BLOG-POST-LIST:START -->
<!-- BLOG-POST-LIST:END -->

Затем в корне репозитория надо создать папку .github в ней папку workflows, а в ней файл blog-post-workflow.yml. Полный путь должен выглядеть следующим образом: username/.github/workflows/blog-post-workflow.yml.

Теперь переходим в созданный yml-файл и вставляем следующее, заменяя ссылку в поле feed-list: на вашу RSS-ссылку (можно скопировать в профиле Хабра в разделе «Публикации»):

name: Latest blog post workflow
on:
  schedule: # Run workflow automatically
    - cron: '0 * * * *' # Runs every hour, on the hour
  workflow_dispatch: # Run workflow manually (without waiting for the cron to be called), through the Github Actions Workflow page directly

jobs:
  update-readme-with-blog:
    name: Update this repo's README with latest blog posts
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Pull in dev.to posts
        uses: gautamkrishnar/blog-post-workflow@master
        with:
          feed_list: "https://habr.com/ru/rss/users/daniilshat/posts/?fl=ru"

Теперь только остается запись изменения и запустить действие. Для этого переходим во вкладку «Actions» в репозитории, с левого края в поле «All workflows» выбираем само действие и нажимаем «Run workflow». Ждем. Если все пройдет успешно, то увидим оповещение, если что-то пойдет не так, то все равно увидим, но уже ошибку. Если все прошло хорошо, то можно обновить страницу профиля и увидеть пять последних постов с Хабра. Часто возникают задержки, и содержимое блока при первом запуске появляется не сразу. В этом случае можно подождать несколько минут, и данные обязательно обновятся.

В yml-файле можно менять поля и их содержимое, кастомизируя выдачу. Если надо выводить последние посты сразу с нескольких сайтов, то можно указать ссылки через запятую.

• Metrics — обширная библиотека с динамической инфографикой. Репозиторий включает в себя более 30 различных плагинов с более чем 200 параметрами для настройки. Можно выводить статистику коммитов, популярные языки, последние обновления, статистику вкладов в сообщество по дням и многое другое. В репозитории есть подробные инструкции для подключения. Библиотека настолько большая, что бессмысленно описывать в этой статье способы интеграции (там на самом деле много всего).

• GitHub Stats Terminal Style — анимированное окно со статистикой в дизайне терминала. Информация также обновляется с помощью GitHub Actions, а на выбор есть около десяти цветовых схем. В репозитории имеется инструкция по настройке.

• Todoist Stats — интеграция с сервисом отслеживания задач Todoist. Выводит в профиль основную статистику о работе над задачами. Для подключения необходим API-токен из приложения. Само подключение осуществляется через GitHub Actions. Можно сделать все руками, а можно подключить уже готовое решение через маркетплейс GitHub.

snk — добавляет в md-файл еще одну сетку Contributions Graph, но только анимированную. По сетке перемещается змейка и съедает зеленые квадратики активности. Анимация зацикленная и начинается заново после того, как все квадратики будут съедены. Посмотреть демо можно на сайте проекта. За ежедневную генерацию нового поля отвечает GitHub Actions. Практической пользы от этого дополнения мало, но в грамотных руках может эффектно оживить профиль.

Забавы ради

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

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

Markdown:

![Jokes Card](https://readme-jokes.vercel.app/api)

HTML:

<img src="https://readme-jokes.vercel.app/api" alt="Jokes Card" />

• Github Readme Quotes — динамически выводит блок с цитатами. Размер ограничен двумя вариантами — вертикальный и горизонтальный, а цветовых схем четыре. В будущем автор проекта планирует расширить параметры кастомизации. Встроить в свой профиль можно с помощью следующего md-кода:

[![Readme Quotes](https://quotes-github-readme.vercel.app/api?type=horizontal&theme=dark)](https://github.com/piyushsuthar/github-readme-quotes)

А если совсем нет времени?

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

• Github Readme Generator by @arturssmirnovs — проект позволят сгенерировать шаблон README-профиля, добавить хедер, информацию о себе, блок социальных сетей и интегрировать метрики. Приложение доступно онлайн по ссылке.

• Github Readme Generator by @rahuldkjain — еще один генератор с чуть более широким выбором функций. Кроме основного набора, позволяет выбрать языки программирования, технологии, добавить кнопки для донатов через Ko-Fi и buymeacoffe и посмотреть превью сгенерированного файла.

• Awesome GitHub Profile README — репозиторий-библиотека «потрясающих» README-файлов, собранных в одном месте. Можно использовать ее в качестве источника вдохновения или же форкать интересующие проекты, если автор разрешает. Все README разбиты по тематическим категориям, что упрощает поиск.

Что дальше?

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

Перевод статьи
«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-файлов с
котами».

Следует учитывать, что чем длиннее
описание, тем больше риск умственной
перегрузки читателя.

Отредактируйте ваш текст. Используйте
заголовки, переносы строк, разбивку на
абзацы (два перевода строки, чтобы начать
новый абзац, и <br> для разрыва строки.
Шпаргалка.).
Не стесняйтесь использовать логотипы
продуктов и скриншоты. В отличие от
прочей технической документации, здесь
мультимедиа работает хорошо.

Если ваш репозиторий содержит что-то
интересное и веселое, это должно
отражаться в его описании! Безусловно,
изложение текста в соответствии с
правилами стилистики и композиции имеет
значение, однако интернет это место,
где классные программисты могут проявлять
свое творческое начало. Обратите внимание
на 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 с
большим количеством примеров кода.
Чтобы
увлечься проектом, я
должен видеть,
что мейнтейнерам он интересен по крайней
мере не меньше, чем мне.

Чтобы получить какое-то представление о стандартном оформлении, рекомендую исследовать тренды вашего языка программирования. А для вдохновения обратите внимание на два моих последних фаворита: Gatsyby и lax.js. Сделайте так, чтобы ваша документация стала просто песней!

When I was first introduced to GitHub, I had no idea what it was or what it could do. Between you and me, I created the account because I was told every developer should have one where they push their code.

For the longest time as a beginner I did nothing with my account. But then, becuase of my passion in tech, I started following other developers and checking out their work on GitHub. And I noticed something they had in common: they all had cool projects and contributed to open source, but their projects also had detailed README files.

So my interest in what a README was grew, and I decided to try and add one in my projects, too. I won’t lie – I did it in a hurry without any knowledge of how it should be done. And honestly it wasn’t great at all. Check it out HERE.

And that was how it stayed for a period of time. But with practice and continuous learning I was able to change to some better documentation like THIS, which improved engagement with the project and helped other devs get involved.

It is also important to note that a good README will help you stand out among the large crowd of developers who put their work on GitHub.

In this article, we’ll learn more about what a README file is and how to write one. First let’s understand what we mean by a README file.

What is a README File?

In simple words, we can describe a README file as a guide that gives users a detailed description of a project you have worked on.

It can also be described as documentation with guidelines on how to use a project. Usually it will have instructions on how to install and run the project.

It is essential for you as a developer to know how to document your project by writing a README because:

• It is the first file a person will see when they encounter your project, so it should be fairly brief but detailed.
• It will make your project standout from a bunch of others. Also be sure your project is good too.
• It will help you focus on what your project needs to deliver and how.
• It will improve your writing skills, just as Friedrich Nietzsche said:

A good writer possesses not only his own spirit but also the spirit of his friends.

While working on a project, keep in mind that you will need other developers to understand your code and what it does. So accompanying it with an extra guide will be really helpful.

For instance, my earlier shared example of my first project does not have a good README. And even though the project was amazing, it would’ve been hard for a beginner to understand exactly what was expected when they cloned my repo. Who knows maybe it could’ve even been a coded virus.

With a project like this on GitHub, no matter how amazing it is, other devs won’t be eager to work on it and try to figure it out without a good README.

Now, have a look at this project. Here, you are able to understand what the project does, what it entails, and how to get started if you need to use or want to contribute to the project.

You see, that’s how powerful a well written README is and how it can change you project.

So, let’s get started on how to write one for you too.

How to Write a Good README – a Step by Step Guide

A very important thing to note is that there’s not one right way to structure a good README. But there is one very wrong way, and that is to not include a README at all.

From research and studying various README files, for sure there are some best practices that I have found. And that’s what I will be sharing. As I usually tell my self:

Every day is a learning day.

So as you progress and advance in your career, you will develop your own ideas about what makes a good README and how to improve on it. Perhaps you’ll even come up with your own unique guide.

Before we get started, it is also important to note that when you’re writing your project’s README, it should be able to answer the what, why, and the how of the project.

Here are some guide questions that will help you out:

• What was your motivation?
• Why did you build this project?
• What problem does it solve?
• What did you learn?
• What makes your project stand out?
  If your project has a lot of features, consider adding a «Features» section and listing them here.

What to Include in your README

1. Project’s Title

This is the name of the project. It describes the whole project in one sentence, and helps people understand what the main goal and aim of the project is.

2. Project Description

This is an important component of your project that many new developers often overlook.

Your description is an extremely important aspect of your project. A well-crafted description allows you to show off your work to other developers as well as potential employers.

The quality of a README description often differentiates a good project from a bad project. A good one takes advantage of the opportunity to explain and showcase:

• What your application does,
• Why you used the technologies you used,
• Some of the challenges you faced and features you hope to implement in the future.

3. Table of Contents (Optional)

If your README is very long, you might want to add a table of contents to make it easy for users to navigate to different sections easily. It will make it easier for readers to move around the project with ease.

4. How to Install and Run the Project

If you are working on a project that a user needs to install or run locally in a machine like a «POS», you should include the steps required to install your project and also the required dependencies if any.

Provide a step-by-step description of how to get the development environment set and running.

5. How to Use the Project

Provide instructions and examples so users/contributors can use the project. This will make it easy for them in case they encounter a problem – they will always have a place to reference what is expected.

You can also make use of visual aids by including materials like screenshots to show examples of the running project and also the structure and design principles used in your project.

Also if your project will require authentication like passwords or usernames, this is a good section to include the credentials.

6. Include Credits

If you worked on the project as a team or an organization, list your collaborators/team members. You should also include links to their GitHub profiles and social media too.

Also, if you followed tutorials or referenced a certain material that might help the user to build that particular project, include links to those here as well.

This is just a way to show your appreciation and also to help others get a first hand copy of the project.

7. Add a License

For most README files, this is usually considered the last part. It lets other developers know what they can and cannot do with your project.

We have different types of licenses depending on the kind of project you are working on. Depending on the one you will choose it will determine the contributions your project gets.

The most common one is the GPL License which allows other to make modification to your code and use it for commercial purposes. If you need help choosing a license, use check out this link: https://choosealicense.com/

Up to this point what we have covered are the minimum requirements for a good README. But you might also want to consider adding the following sections to make it more eye catching and interactive.

Additional README Sections

8. Badges

Badges aren’t necessary, but using them is a simple way of letting other developers know that you know what you’re doing.

Having this section can also be helpful to help link to important tools and also show some simple stats about your project like the number of forks, contributors, open issues etc…

Below is a screenshot from one of my projects that shows how you can make use of badges:

The good thing about this section is that it automatically updates it self.

Don’t know where to get them from? Check out the badges hosted by shields.io. They have a ton of badges to help you get started. You may not understand what they all represent now, but you will in time.

9. How to Contribute to the Project

This mostly will be useful if you are developing an open-source project that you will need other developers to contribute to. You will want to add guidelines to let them know how they can contribute to your project.

Also it is important to make sure that the licence you choose for an open-source projects is correct to avoid future conflicts. And adding contribution guidelines will play a big role.

Some of the most common guidelines include the Contributor Covenant and the Contributing guide. Thes docs will give you the help you need when setting rules for your project.

10. Include Tests

Go the extra mile and write tests for your application. Then provide code examples and how to run them.

This will help show that you are certain and confident that your project will work without any challenges, which will give other people confidence in it, too

Here are a few extra points to note when you’re writing your README:

• Keep it up-to-date — It is a good practise to make sure your file is always up-to-date. In case there are changes make sure to update the file where necessary.
• Pick a language — We all come from different zones and we all speak different languages. But this does not mean you need to translate your code into vernacular. Writing your README in English will work since English is a globally accepted language. You might want to use a translator tool here if your target audience isn’t familiar with English.

Wrap Up

There you have it, everything you need to improve your README files, or even get you started with writing your first one.

At this point I am confident that you are in a position to add an interactive and inforamative guide to your next project or even an existing one and make your project standout.

There are many tools which you can also use to automatically generate a README for your project, but it’s always a good practice to try it on your own before moving to automation. In case you want to check them out, they include:

• Make a README
• README Generator
• README

If you have read this far I really appreciate it. If you enjoyed this article and found it helpful, please share it so you can help another developer improve their projects.

I would love to see your newly crafted README file. Be sure to share a link with me via any of the links below:

Connect With me at Twitter | YouTube | LinkedIn | GitHub

Do share your valuable opinion, I appreciate your honest feedback!

Enjoy Coding ❤

---

---

Learn to code for free. freeCodeCamp’s open source curriculum has helped more than 40,000 people get jobs as developers. Get started

When I was first introduced to GitHub, I had no idea what it was or what it could do. Between you and me, I created the account because I was told every developer should have one where they push their code.

For the longest time as a beginner I did nothing with my account. But then, becuase of my passion in tech, I started following other developers and checking out their work on GitHub. And I noticed something they had in common: they all had cool projects and contributed to open source, but their projects also had detailed README files.

So my interest in what a README was grew, and I decided to try and add one in my projects, too. I won’t lie – I did it in a hurry without any knowledge of how it should be done. And honestly it wasn’t great at all. Check it out HERE.

And that was how it stayed for a period of time. But with practice and continuous learning I was able to change to some better documentation like THIS, which improved engagement with the project and helped other devs get involved.

It is also important to note that a good README will help you stand out among the large crowd of developers who put their work on GitHub.

In this article, we’ll learn more about what a README file is and how to write one. First let’s understand what we mean by a README file.

What is a README File?

In simple words, we can describe a README file as a guide that gives users a detailed description of a project you have worked on.

It can also be described as documentation with guidelines on how to use a project. Usually it will have instructions on how to install and run the project.

It is essential for you as a developer to know how to document your project by writing a README because:

• It is the first file a person will see when they encounter your project, so it should be fairly brief but detailed.
• It will make your project standout from a bunch of others. Also be sure your project is good too.
• It will help you focus on what your project needs to deliver and how.
• It will improve your writing skills, just as Friedrich Nietzsche said:

A good writer possesses not only his own spirit but also the spirit of his friends.

While working on a project, keep in mind that you will need other developers to understand your code and what it does. So accompanying it with an extra guide will be really helpful.

For instance, my earlier shared example of my first project does not have a good README. And even though the project was amazing, it would’ve been hard for a beginner to understand exactly what was expected when they cloned my repo. Who knows maybe it could’ve even been a coded virus.

With a project like this on GitHub, no matter how amazing it is, other devs won’t be eager to work on it and try to figure it out without a good README.

Now, have a look at this project. Here, you are able to understand what the project does, what it entails, and how to get started if you need to use or want to contribute to the project.

You see, that’s how powerful a well written README is and how it can change you project.

So, let’s get started on how to write one for you too.

How to Write a Good README – a Step by Step Guide

A very important thing to note is that there’s not one right way to structure a good README. But there is one very wrong way, and that is to not include a README at all.

From research and studying various README files, for sure there are some best practices that I have found. And that’s what I will be sharing. As I usually tell my self:

Every day is a learning day.

So as you progress and advance in your career, you will develop your own ideas about what makes a good README and how to improve on it. Perhaps you’ll even come up with your own unique guide.

Before we get started, it is also important to note that when you’re writing your project’s README, it should be able to answer the what, why, and the how of the project.

Here are some guide questions that will help you out:

• What was your motivation?
• Why did you build this project?
• What problem does it solve?
• What did you learn?
• What makes your project stand out?
  If your project has a lot of features, consider adding a «Features» section and listing them here.

What to Include in your README

1. Project’s Title

This is the name of the project. It describes the whole project in one sentence, and helps people understand what the main goal and aim of the project is.

2. Project Description

This is an important component of your project that many new developers often overlook.

Your description is an extremely important aspect of your project. A well-crafted description allows you to show off your work to other developers as well as potential employers.

The quality of a README description often differentiates a good project from a bad project. A good one takes advantage of the opportunity to explain and showcase:

• What your application does,
• Why you used the technologies you used,
• Some of the challenges you faced and features you hope to implement in the future.

3. Table of Contents (Optional)

If your README is very long, you might want to add a table of contents to make it easy for users to navigate to different sections easily. It will make it easier for readers to move around the project with ease.

4. How to Install and Run the Project

If you are working on a project that a user needs to install or run locally in a machine like a «POS», you should include the steps required to install your project and also the required dependencies if any.

Provide a step-by-step description of how to get the development environment set and running.

5. How to Use the Project

Provide instructions and examples so users/contributors can use the project. This will make it easy for them in case they encounter a problem – they will always have a place to reference what is expected.

You can also make use of visual aids by including materials like screenshots to show examples of the running project and also the structure and design principles used in your project.

Also if your project will require authentication like passwords or usernames, this is a good section to include the credentials.

6. Include Credits

If you worked on the project as a team or an organization, list your collaborators/team members. You should also include links to their GitHub profiles and social media too.

Also, if you followed tutorials or referenced a certain material that might help the user to build that particular project, include links to those here as well.

This is just a way to show your appreciation and also to help others get a first hand copy of the project.

7. Add a License

For most README files, this is usually considered the last part. It lets other developers know what they can and cannot do with your project.

We have different types of licenses depending on the kind of project you are working on. Depending on the one you will choose it will determine the contributions your project gets.

The most common one is the GPL License which allows other to make modification to your code and use it for commercial purposes. If you need help choosing a license, use check out this link: https://choosealicense.com/

Up to this point what we have covered are the minimum requirements for a good README. But you might also want to consider adding the following sections to make it more eye catching and interactive.

Additional README Sections

8. Badges

Badges aren’t necessary, but using them is a simple way of letting other developers know that you know what you’re doing.

Having this section can also be helpful to help link to important tools and also show some simple stats about your project like the number of forks, contributors, open issues etc…

Below is a screenshot from one of my projects that shows how you can make use of badges:

The good thing about this section is that it automatically updates it self.

Don’t know where to get them from? Check out the badges hosted by shields.io. They have a ton of badges to help you get started. You may not understand what they all represent now, but you will in time.

9. How to Contribute to the Project

This mostly will be useful if you are developing an open-source project that you will need other developers to contribute to. You will want to add guidelines to let them know how they can contribute to your project.

Also it is important to make sure that the licence you choose for an open-source projects is correct to avoid future conflicts. And adding contribution guidelines will play a big role.

Some of the most common guidelines include the Contributor Covenant and the Contributing guide. Thes docs will give you the help you need when setting rules for your project.

10. Include Tests

Go the extra mile and write tests for your application. Then provide code examples and how to run them.

This will help show that you are certain and confident that your project will work without any challenges, which will give other people confidence in it, too

Here are a few extra points to note when you’re writing your README:

• Keep it up-to-date — It is a good practise to make sure your file is always up-to-date. In case there are changes make sure to update the file where necessary.
• Pick a language — We all come from different zones and we all speak different languages. But this does not mean you need to translate your code into vernacular. Writing your README in English will work since English is a globally accepted language. You might want to use a translator tool here if your target audience isn’t familiar with English.

Wrap Up

There you have it, everything you need to improve your README files, or even get you started with writing your first one.

At this point I am confident that you are in a position to add an interactive and inforamative guide to your next project or even an existing one and make your project standout.

There are many tools which you can also use to automatically generate a README for your project, but it’s always a good practice to try it on your own before moving to automation. In case you want to check them out, they include:

• Make a README
• README Generator
• README

If you have read this far I really appreciate it. If you enjoyed this article and found it helpful, please share it so you can help another developer improve their projects.

I would love to see your newly crafted README file. Be sure to share a link with me via any of the links below:

Connect With me at Twitter | YouTube | LinkedIn | GitHub

Do share your valuable opinion, I appreciate your honest feedback!

Enjoy Coding ❤

---

---

Learn to code for free. freeCodeCamp’s open source curriculum has helped more than 40,000 people get jobs as developers. Get started

Статья написана студентом Хекслета. Мнение автора может не совпадать с позицией редакции

Если вы читаете эту статью, это, вероятно, означает, что вы уже размещаете репозитории на GitHub и, возможно, даже вносите свой вклад в открытый исходный код. А если вы используете GitHub, то вам нужно писать хорошую документацию для своих проектов, чтобы помочь другим понять их.

Когда я впервые зашла на Github, честно говоря, я понятия не имела, что такое файл README (хотя я видела его в проектах других людей).

Во-первых, зачем мне хороший файл README?

Файл README — это руководство, которое дает пользователям подробное описание проекта, который вы разместили в своем репозитории.

Возможно, вам интересно, зачем тратить время на написание хорошего README. Вот несколько причин, которые помогут убедить вас в том, что это хорошая идея:

1. Хороший README поможет вашим проектам выделиться среди множества других проектов. Он должен быть не хуже самого проекта.
2. Это первый файл, который увидит человек, столкнувшись с вашим проектом, поэтому он должен быть достаточно кратким, но подробным.
3. Это поможет вам сосредоточиться на том, что и как нужно реализовать в вашем проекте.

README должен ответить на следующие вопросы: что, почему и как:

• Что было вашей мотивацией?
• Какую проблему это решает?
• Что вы узнали?
• Что отличает ваш проект от других?

Если в вашем проекте много функций, подумайте о том, чтобы добавить раздел «Возможности» и перечислить их здесь.

Как написать хороший файл README

Вот шаги, которые вы должны предпринять, чтобы написать README.

Включите название вашего проекта

Это название проекта. Он описывает весь проект одним предложением и помогает людям понять, какова основная цель и цель проекта.

Напишите описание

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

Как установить ваш проект

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

Как использовать ваш проект

Предоставьте инструкции и примеры, чтобы пользователи/участники могли использовать проект. Это упростит им задачу в случае, если они столкнутся с проблемой — у них всегда будет место для ссылки. Вы также можете вставить скриншоты, чтобы показать примеры работающего проекта.

Если вы работали над проектом как команда или организация, перечислите своих соавторов / членов команды. Вы также должны включить ссылки на их профили GitHub.

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

В этой статье мы разберём:

• что такое файл README.md и как им пользоваться;
• добавим информацию о себе и своих навыках;
• добавим GitHub-статистику;
• создадим рабочий поток GitHub для отображения постов из социальных сетей.

Чтобы всё получилось, вам нужны базовые знания HTML и Markdown.

Код из этой статьи доступен по ссылке.

Что же такое файл README.md в профиле на GitHub и для чего он нужен

Файл README.md в профиле на GitHub позволяет пользователям использовать Markdown-разметку, чтобы отображать детали о себе, о своём опыте, увлечениях, показывать GitHub-статистику и предоставлять эту информацию сообществу. Эти данные отображаются в верхней части вашей GitHub страницы над закрепленными репозиториями.

Так будем выглядеть профиль на GitHub по окончании этой статьи:

Мы разделим главную страницу на сектора и постепенно для каждого добавим содержимое. Цвет фона будет зависеть от цветовой темы, выбранной пользователем.

В следующем разделе мы поэтапно разберем шаги создания README-файла.

Создание README.md на GitHub

Файл README.md находится в репозитории на GitHub, название которого совпадает с именем пользователя в вашей учетной записи. Чтобы создать репозиторий:

1. Войдите на GitHub.

2. Нажмите + в правом верхнем углу и выберите New Repository.

3. Откроется страница создания нового репозитория. В названии укажите имя пользователя из вашего профиля. После того как вы введете имя пользователя, будет показана информация о том, что вы создаете особый репозиторий.

4. Под описанием репозитория не забудьте установить отметку Public, чтобы файл README.md был виден всем.

5. Обязательно установите отметку Add a README file. Это создаст файл README.md, в котором мы и будем работать. Сравните со скриншотом, у вас должно получиться также.

6. Далее нажимаем кнопку Create repository. Репозиторий успешно создан. Зайдите в только что созданный репозиторий и увидите, что в нем уже есть файл README.md.

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

Открываем файл README.md и вверху справа нажимаем Edit this file icon (иконка с карандашом). Также о редактировании файлов мы можем почитать в официальной документации.

Добавление GIF-изображений и значков

Ниже вы видите тот контент, который мы добавим в этой части статьи:

Есть множество бесплатных ресурсов, на которых вы можете взять GIF-изображения, например, для этой статьи я использовал Giphy.

Идем на страницу GIF изображения, нажимаем кнопку Share, а затем Copy GIF Link. Мы добавим эту скопированную ссылку в HTML-тег <img/>, чтобы отобразить ее в файле Markdown. Мы используем тег <img/> для упрощения настройки ширины изображения.

Замените содержимое файла README.md следующим кодом:

        <div id="header" align="center">
  <img src="https://media.giphy.com/media/M9gbBd9nbDrOTu1Mqx/giphy.gif" width="100"/>
</div>

    

В атрибуте src указываем ссылку, которую мы ранее скопировали. Поскольку весь контент в этой части будет выровнен по центру, мы поместили изображение в HTML-тег <div> с атрибутом align="center".

Перейдем в окно предпросмотра. Наша картинка появилась на странице:

Далее мы добавим значки для ссылок на социальные сети, при клике на которые будет открываться нужный сайт. Вы можете добавить значки для самых разных сайтов: Instagram, Facebook, Twitter и т. д. Мы добавим три значка: Twitter, YouTube и LinkedIn.

Для создания и редактирования необходимых нам значков будем использовать ресурс Shields.io. Используем URL-адрес https://img.shields.io/badge/ и передадим ему дополнительные параметры, чтобы получить нужные значки.

Первый параметр, который мы передадим, будет следующего формата: Label-Color

Здесь:

Label – название социальной сети, отображенное на значке.

Color – цвет самого значка.

Для трех социальных сетей значения будут следующие:

• LinkedIn: LinkedIn-blue
• Twitter: Twitter-blue
• YouTube: YouTube-red

Так должен выглядеть итоговый URL для LinkedIn:

        https://img.shields.io/badge/LinkedIn-blue
    

Если поместить этот URL в адресную строку браузера и перейти по нему, увидим следующее:

Обратите внимание, что пока на значке у нас только текст. Чтобы добавить логотип, нам нужно добавить в адрес еще 2 параметра:

• logo = {название иконки для социальной сети}
• logoColor = {цвет этой иконки}

Такой URL должен у нас получиться:

        https://img.shields.io/badge/LinkedIn-blue?logo=linkedin&logoColor=white
    

Также добавим параметр стиля к нашему URL-адресу. Существует множество вариантов стилей, подробнее можно ознакомиться на сайте Shields.io. Мы будем использовать элемент for-the-badge.

Итоговый URL для значка LinkedIn будет выглядеть так:

        https://img.shields.io/badge/LinkedIn-blue?logo=linkedin&logoColor=white&style=for-the-badge
    

Вставим этот адрес в браузер и посмотрим, что получилось:

По аналогии создадим URL-адреса для остальных значков:

        https://img.shields.io/badge/YouTube-red?style=for-the-badge&logo=youtube&logoColor=white
https://img.shields.io/badge/Twitter-blue?style=for-the-badge&logo=twitter&logoColor=white
    

Добавим каждый URL в тег <img/>:

        <div id="badges">
  <img src="https://img.shields.io/badge/LinkedIn-blue?style=for-the-badge&logo=linkedin&logoColor=white" alt="LinkedIn Badge"/>
  <img src="https://img.shields.io/badge/YouTube-red?style=for-the-badge&logo=youtube&logoColor=white" alt="Youtube Badge"/>
  <img src="https://img.shields.io/badge/Twitter-blue?style=for-the-badge&logo=twitter&logoColor=white" alt="Twitter Badge"/>
</div>

    

Мы поместили изображения внутрь тега <div>, чтобы все значки были расположены на одной строке. Код выше выведет только картинки из URL-адресов. Чтобы добавить ссылки на социальный сети, каждое изображение нужно поместить в тег <a>.

Добавьте код ниже внутрь тега <div> с id="badges" и тег <img> с нашим GIF-изображением. Также не забудьте добавить ссылки на свои социальные сети в атрибут href.

        <div id="badges">
  <a href="your-linkedin-URL">
    <img src="https://img.shields.io/badge/LinkedIn-blue?style=for-the-badge&logo=linkedin&logoColor=white" alt="LinkedIn Badge"/>
  </a>
  <a href="your-youtube-URL">
    <img src="https://img.shields.io/badge/YouTube-red?style=for-the-badge&logo=youtube&logoColor=white" alt="Youtube Badge"/>
  </a>
  <a href="your-twitter-URL">
    <img src="https://img.shields.io/badge/Twitter-blue?style=for-the-badge&logo=twitter&logoColor=white" alt="Twitter Badge"/>
  </a>
</div>

    

Вот что должно получиться:

Далее в этом же разделе мы добавим счетчик просмотров профиля. Он будет подсчитывать количество просмотров вашей страницы на GitHub. Для значка счетчика воспользуемся проектом с открытым исходным кодом. Документация по этому проекту находится в профиле Views Counter на GitHub. Механизм очень похож на добавление значков для социальных сетей. Используем параметры стилей и в итоге должен получиться следующий URL:

        https://komarev.com/ghpvc/?username=имя пользователя на GitHub
    

Добавьте следующий код после тега <div> с id="badges". Не забудьте указать верное имя пользователя.

        <img src="https://komarev.com/ghpvc/?username=your-github-username&style=flat-square&color=blue" alt=""/>
    

Ниже образец того, что должно получиться:

И в конце этого раздела добавим текст и эмодзи. GIF-изображение можно взять с сайта Giphy.

Добавьте этот код после тега <img> в котором мы написали счетчик просмотров профиля:

        <h1>
  hey there
  <img src="https://media.giphy.com/media/hvRJCLFzcasrR4ia7z/giphy.gif" width="30px"/>
</h1>

    

Так должно получиться:

Нажимаем кнопку Commit changes и тем самым сохраняем изменения. Итак, мы завершили первую часть по созданию файла README.md в нашем профиле на GitHub.

Добавление GIF-баннера и раздела «О себе»

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

Как вы уже, наверное, поняли, мы добавим GIF-картинку и несколько слов о себе. GIF можно найти по этой ссылке.

Чтобы добавить GIF, мы будем использовать тег <img>, установим высоту и ширину изображения, а также поместим его внутрь тега <div>, чтобы выровнять изображение по центру с помощью атрибута align="center". Добавьте в файл README.md следующий код:

        <div align="center">
  <img src="https://media.giphy.com/media/dWesBcTLavkZuG35MI/giphy.gif" width="600" height="300"/>
</div>

    

Результат:

Далее, добавим контент в раздел «О себе». Для оформления текста воспользуемся синтаксисом Markdown, так как нам не нужны никакие выравнивания. Добавьте этот код в ваш файл README.md:

        ### :woman_technologist: About Me :
    

Три дефиса --- используются для добавления горизонтальной линии перед каждым разделом. Перед и после горизонтальной линии в Markdown должны быть пустые строки.

:woman_technologist: используется для добавления эмодзи. Также есть мужская версия этого эмодзи :man_technologist:

Список эмодзи и их кодов вы можете найти в репозитории по ссылке.

Далее мы кратко представимся. Нам будет достаточно одной строки и в этой же строке добавляем эмодзи. Вставьте следующий код в наш файл:

        I am a Full Stack Developer <img src="https://media.giphy.com/media/WUlplcMpOCEmTGBtBW/giphy.gif" width="30"> from India.
    

Далее напишем список фактов о себе. Для этого используем синтаксис Markdown. В начале каждой строки добавим эмодзи. Добавьте следующий код и внесите соответствующие изменения. И не забудьте изменить your-linkedin-url на правильную ссылку.

        - :telescope: I’m working as a Software Engineer and contributing to frontend and backend for building web applications.

- :seedling: Exploring Technical Content Writing.

- :zap: In my free time, I solve problems on GeeksforGeeks and read tech articles.

- :mailbox:How to reach me: [![Linkedin Badge](https://img.shields.io/badge/-kakbar-blue?style=flat&logo=Linkedin&logoColor=white)](your-linkedin-url)

    

Обратите внимание на последнюю строку. Внутри мы использовали элементы синтаксиса Markdown ![]() чтобы отобразить значок LinkedIn.

Вот что у нас получилось.

Добавление языков программирования и инструментов

Вот результат того, что мы будем делать в этой части статьи.

Для начала добавим заголовок, вставьте следующий код в файл README.md:

        
---

### :hammer_and_wrench: Languages and Tools :

    

Мы добавим изображения, которые отражают какими технологиями и навыками вы обладаете. Бесплатные логотипы для разных языков программирования можно найти в репозитории DevIcons.

Перейдите в папку icons, найдите и откройте директорию react. Здесь вы найдете изображения в форматах SVG и EPS. Кликните на нужное изображение и скопируйте URL из адресной строки браузера.

Скопированный URL мы будем использовать в теге <img> и сразу установим атрибуты высоты и ширины. Точно таким же способом вы можете добавлять навыки в отдельные <img> теги.

Добавьте следующий код в файл. Откорректируйте список навыков, чтобы он соответствовал вашему опыту.

        <div>
  <img src="https://github.com/devicons/devicon/blob/master/icons/java/java-original-wordmark.svg" title="Java" alt="Java" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/react/react-original-wordmark.svg" title="React" alt="React" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/spring/spring-original-wordmark.svg" title="Spring" alt="Spring" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/materialui/materialui-original.svg" title="Material UI" alt="Material UI" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/flutter/flutter-original.svg" title="Flutter" alt="Flutter" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/redux/redux-original.svg" title="Redux" alt="Redux " width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/css3/css3-plain-wordmark.svg"  title="CSS3" alt="CSS" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/html5/html5-original.svg" title="HTML5" alt="HTML" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/javascript/javascript-original.svg" title="JavaScript" alt="JavaScript" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/firebase/firebase-plain-wordmark.svg" title="Firebase" alt="Firebase" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/gatsby/gatsby-original.svg" title="Gatsby"  alt="Gatsby" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/mysql/mysql-original-wordmark.svg" title="MySQL"  alt="MySQL" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/nodejs/nodejs-original-wordmark.svg" title="NodeJS" alt="NodeJS" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/amazonwebservices/amazonwebservices-plain-wordmark.svg" title="AWS" alt="AWS" width="40" height="40"/>&nbsp;
  <img src="https://github.com/devicons/devicon/blob/master/icons/git/git-original-wordmark.svg" title="Git" **alt="Git" width="40" height="40"/>
</div>

    

Вот результат того, что у нас получилось:

В этой части статьи у нас должно получиться следующее:

Для заголовка добавьте следующий код в README.md:

        ---

### :fire: My Stats :

    

Мы добавим в этот раздел немного статистики по вашей активности на GitHub, например: количество коммитов, количество пулл-реквестов (pull requests) и т. д. На GitHub есть много проектов с открытым кодом, которые предоставляют различные данные по статистике. В этой статье мы будем использовать два проекта.

Первый проект – это GitHub Streak Stats. Он предоставляет следующие три показателя:

1. Общее число контрибуций пользователя.
2. Самый продолжительный период контрибуций.
3. Статистика по текущему периоду.

Получим доступ к статистике по следующему URL:

        https://github-readme-streak-stats.herokuapp.com/?user=your-github-username
    

Мы можем немного кастомизировать вывод статистики (изменить тему, цвет фона и т. д.) добавлением параметров к URL. Добавьте следующий код в README.md. Замените your-github-username на своё имя пользователя.

        [![GitHub Streak](http://github-readme-streak-stats.herokuapp.com?user=your-github-username&theme=dark&background=000000)](https://git.io/streak-stats)
    

Вот пример того, что должно получиться, здесь в качестве имени пользователя было использовано itsZed0.

Также мы можем использовать ресурс Streak Stats Website для генерации URL:

1. Зайдите на сайт Streak Stats Website. В поле Username введите имя пользователя на GitHub и заполните остальные поля.
2. Далее нажмите Submit.

3. После того как Markdown сгенерировался, нажмите Copy To Clipboard и добавьте скопированную информацию в README.md.

Следующий проект, который мы будет использовать для статистики – это GitHub Readme Stats, разработанный Anurag Hazra. Данный продукт предоставляет всевозможную статистику, но в этой статье мы будем использовать только одну. Она отображает ТОП языков программирования, которыми вы пользуетесь. Если вы хотите более подробно ознакомиться с этим проектом, можете почитать документацию в репозитории.

Ниже пример Markdown для отображения языков программирования, которые вы используете:

        [![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=your-github-username)](https://github.com/anuraghazra/github-readme-stats)

    

Здесь также можно доработать внешний вид (изменить цвет, ограничить количество языков и т. д.). Более подробно с возможностями кастомизации можно ознакомиться здесь.

Добавьте следующий код в README.md. Замените your-github-username своими данными.

        [![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=your-github-username&layout=compact&theme=vision-friendly-dark)](https://github.com/anuraghazra/github-readme-stats)
    

Ниже пример того, что получилось:

Добавление блогов в наш README.md на GitHub

На изображении ниже показано, к чему мы будем стремиться в этом разделе:

Для заголовка добавьте следующий код в README.md:

        ---

### :writing_hand: Blog Posts :

    

В этом разделе мы отобразим недавние посты, опубликованные пользователем на различных платформах. Для этого мы создадим рабочий поток (workflow), который будет представлять собой автоматизированный процесс выполнения заданий. Каждое задание в потоке будет иметь одно или более возможных действий. Действие на GitHub – это набор исполняемых команд, объединенных в этапы. Мы также можем использовать собственное действие или использовать действие, созданное другим пользователем.

Чтобы получить сообщения в блоге, мы использует два уже существующих действия:

1. Checkout – используется для извлечения всех файлов из текущего репозитория в рабочий процесс Git для предоставления процессу доступа к ним.
2. Blog Post Workflow – используется для получения последних сообщений в блогах с других сайтов.

Рабочий процесс можно запускать в определенное время или при наличии триггера. В этом обучении, для получения последней записи в блоге, мы будем запускать рабочий процесс каждый час. Более подробно про действия (GitHub actions) можно почитать в официальной документации.

Чтобы создать рабочий поток GitHub, сделайте следующее:

• Добавьте следующий код в README.md. Рабочий поток заменит комментарии списком постов:

        <!-- BLOG-POST-LIST:START -->

<!-- BLOG-POST-LIST:END -->
    

• Сохраните изменения, нажав Commit change.

• Конфигурация рабочего потока GitHub определяется в файле с расширением .yml в котором используется синтаксис YAML. В вашем репозитории нажмите Add File, затем Create New file.

• В поле Name your file.. введите .github/workflows/blog-post-workflow.yml. Вся конфигурация рабочего потока GitHub располагается в директории .github/workflows.

• Добавьте следующий код в раздел Edit new file:

        name: Latest blog post workflow
on:
  schedule:
    # Runs every hour
    - cron: '0 * * * *'
  workflow_dispatch:

jobs:
  update-readme-with-blog:
    name: Update this repos README with latest blog posts
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: gautamkrishnar/blog-post-workflow@master
        with:
          max_post_count: "4"
          feed_list: "https://dev.to/feed/itszed0"

    

В этом коде мы определили рабочий поток с названием Latest blog post workflow, который запускается по графику (on: schedule:), заданному в поле cron. 0 * * * * – это POSIX cron синтаксис, и значение этого поля в том, что задача будет запускаться в ноль минут каждого часа.

• workflow_dispatch: позволяет пользователю отслеживать и запускать рабочий поток вручную.
• jobs позволяет нам определить одно или несколько заданий, которые будут выполняться во время работы потока. В нашем случае, у нас одна задача – update-readme-with-blog – которая запускается (runs-on) на машине с операционной системой Ubuntu, размещенной на GitHub.
• steps определяет набор действий или команд, которые должны быть исполнены. Мы создали два действия steps: actions/checkout@v2 и gautamkrishnar/blog-post-workflow@master. Последнее принимает два параметра, которые прописаны в поле with.
• max_post_count определяет максимальное количество постов для отображения в README.
• feed_list – это разделенный запятыми RSS-канал для URL-адресов различных блогинг-платформ.

В этой статье мы добавим блоги с платформы dev.to. Чтобы узнать, какие платформы поддерживаются данным функционалом, ознакомьтесь с документацией.

Если вы хотите узнать больше о синтаксисе для рабочих потоков GitHub, можете ознакомиться с документацией Workflow Syntax.

Замените значение в поле feed_list вашей ссылкой и нажмите Commit new file. Тем самым вы создадите рабочий поток. В результате поток будет каждый час проверять новые посты из вашего профиля на dev.to и добавлять их в README.md.

Чтобы запустить поток вручную, выполните следующее:

• В репозитории перейдите на вкладку Actions.
• Под надписью All workflows нажмите Latest blog post workflow.
• Нажмите Run workflow. Откроется выпадающий список и далее Run workflow. Рабочий поток начнет выполняться.
  

• Перейдите на страницу профиля в раздел Blog Posts. Вы увидите список всех постов с платформ, прописанных в файле blog-post-workflow.yml. На картинке ниже показан список постов по адресу https://dev.to/feed/itszed0, который мы прописали в feed_list.

Вы можете перейти по ссылке и убедиться в том, что у пользователя itsZed0 один пост с названием Test post: рабочий поток «увидел» эту запись и отобразил её в профиле на GitHub.

Вот что у нас получилось в итоге.

***

В этой статье мы:

1. Изучили, что такое файл README.md в профиле на GitHub.
   
2. Узнали, как создавать файл README.md.
3. Добавили GIF-изображения, информацию о себе и свои навыки в профиль.
4. Добавили статистические данные.
5. Создали рабочий поток для отображения постов из наших социальных сетей в профиле на GitHub.

Материалы по теме

• Вдарим по опенсорсу: как без страха прокачать свой аккаунт на Github
• GitLab или GitHub? Как выбрать ресурс под определённый тип репозитория
• Почему твой GitHub-репозиторий никому не нужен