Скотт Чакон - Pro Git

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

Рисунок 21. Пример написания и отображения текста с разметкой.

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

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

Список задач можно добавить следующим образом:

- [X] Write the code

- [ ] Write all the tests

- [ ] Document the code

Если добавить этот список в описание запроса на слияние или проблемы, то он будет отображен следующим образом Отображение списка задач в коментарии.

Рисунок 22. Отображение списка задач в коментарии.

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

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

Рисунок 23. Статистика задач в списке запросов слияния.

Такая возможность невероятно полезна когда вы открываете запрос на слияние на раннем этапе реализации и отслеживаете прогресс с помощью него.

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

Для добавления отрывка кода следует обрамить его обратными кавычками.

```java

for(int i=0 ; i < 5 ; i++)

{

System.out.println("i is : " + i);

}

```

Если вы укажите название языка, как показано на примере, GitHub попробует применить к нему подсветку синтаксиса. Для приведенного примера код будет выглядеть как на Отображение обрамленного кода..

Рисунок 24. Отображение обрамленного кода.

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

Цитаты выглядят примерно так:

> Whether 'tis Nobler in the mind to suffer

> The Slings and Arrows of outrageous Fortune,

How big are these slings and in particular, these arrows?

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

Рисунок 25. Пример отображения цитаты.

Наконец, вы можете использовать смайлики. На GitHub вы можете часто встретить их в коментариях или запросах на слияние. Для них есть даже помощник. Когда вы пишите коментарий и начинаете слов с символа :, то вам будут предложены варианты автодополнения.

Рисунок 26. Автодополнение для смайлов в действии.

Смайлы имеют вид :: и могут располагаться в любом месте коментария. Например, вы можете написать что-нибудь вроде этого:

I :eyes: that :bug: and I :cold_sweat:.

:trophy: for :microscope: it.

:+1: and :sparkles: on this :ship:, it's :fire::poop:!

:clap::tada::panda_face:

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

Рисунок 27. Перегруженный смайликами коментарий.

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

На текущий момент существует много интернет сервисов, где используются смайлики. Отличную шпаргалку по поиску смайликов, которые выражают нужную вам эмоцию, можно нйти здесь:

http://www.emoji-cheat-sheet.com

Технически, картинки не относятся к разметке GitHub, но их использование очень полезно. В дополнение к ссылкам на картинки в коментариях, GitHub позволяет встраивать картинки в коментарии.

Рисунок 28. Перетаскивание картинки для загрузки и встраивания.

Если вернуться немного назад к Перекрестные ссылки в запросе слияния., то над областью редактирования вы увидите небольшую подсказку “Parsed as Markdown”. Нажав не неё, вы получите полную подсказку по использованию GitHub разметки.

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

Давайте создадим новый репозиторий для распространения кода нашего проекта. В панели управления справа нажмите кнопку “New repository” или воспользуйтесь кнопкой + на панели инструментов, рядом с вашим именем пользователя как показано на рисунке Выпадающее меню “New repository”..