Markdown

Доброго времени суток, коллеги! Всем хочется после долгого пути обучения показать работодателю свои плоды, да показать их только с лучшей, профессиональной стороны, не так ли? Я думаю да. Поэтому кроме правильно спроектированного и реализованного проекта нам нужно уметь оформлять его. Не будет же работодатель читать весь ваш код проекта что бы понять о чем он и что в него вложено? В этой статье мы окончательно подведем итог предыдущих двух, а именно: Continuous Integration и Code Coverage, дадим на "лицевом" листе open-source project'а понять, что мы юзали в своем проекте и что он собой представляет. Сегодня мы поговорим с вами об Markdown, зададимся нашими любимыми вопросами "Что это?" и "Зачем это?", разберемся где его используют и как с ним работать. Даже будет примерчик, мы внедрим его в наш open-source project. Итак, поехали!

Что такое "Markdown"?

Так как мы с вами программисты, сразу полезем в google и откроем первую же ссылочку Wiki в которой сказано: Markdown — облегчённый язык разметки, созданный с целью написания наиболее читаемого и удобного для правки текста, но пригодного для преобразования в языки для продвинутых публикаций (HTML, Rich Text и других). Здесь, мне, если честно, особо и нечего добавить, я считаю это почти идеальным объяснением.

Зачем нам этот "Markdown"?

Если честно, вообще-то и без него не плохо :D Но давайте вспомним нашу цель: написать грамотный шаблон проекта, который уже имеет Continuous Integration и имеет статистику Code Coverage на ресурсе Codecov. К чему я это упомянул? К тому, что Markdown позволит нам забрать данные из этих ресурсов, и предоставить и сами данные, или же бейджики, которые будут перенаправлять нас куда нужно, что бы получить эту информацию. Удобно иметь все на одном "титульном" листе, а не разбросанное по разным местам, не так ли?

Где его используют?

Все кто хотя бы раз загружал любой свой проект на GitHub, знает, что GitHub упорно хочет предложить вам создать файл README: А расширение этого файла какое? Правильно, болт его знает Markdown! Как мы уже знаем этот файл очень легко подстраивается под многие форматы, и преобразуется в нужный нам HTML. Но давайте не торопится, и не лететь его сразу добавлять прямо на GitHub'е.

Как с ним работать?

Во-первых, как вы могли заметить, мы можем добавить его прямо на GitHub, и это будет работать! Но ведь нам не всегда нужно его только в один проект, например, добавить. Или например мы хотим больше подумать над тем, как мы его создадим. И здесь нам уже GitHub не подойдет. Да и вообще мы можем создавать Markdown файлы не только в целях push'a их на GitHub. Во-вторых мы могли бы его создать напрямую через IDEA, что как-раз таки мы и будем делать, но не сразу, по той причине, что зачем нам нужна мощная среда разработки для написания одного маленького файлика? Здесь я и рекомендую просмотреть каталог легких, и не очень, редакторов Markdown файлов. Для себя я выбрал Haroopad, он очень простой, доступный, имеет мгновенное представление того, что вы пишете (IDEA также имеет), и имеет подсказку в виде синтаксиса. Вот так выглядит окно редактора: Здесь я открыл уже готовый README.md одного из моих проектов. Слева - шпаргалка, справа - отображение, по центру - текст. Все очень примитивно и просто. Также вы можете видеть бейджики, о который мы скоро поговорим. Те, кто выберут другой способ написания этих файлов - не пугайтесь, все что будет отличатся - это графический интерфейс. Текст, синтаксис и отображение останется неизменным. Пример Задача очень простая: написать README.md так, что бы он содержал в себе: информацию о проекте (в том числе и бейджики), информацию о импорте проекта, информацию о реализации проекта, информацию о контактах автора. Все очень просто и примитивно, как я уже сказал. Перейдем к делу.

1. Напишем заголовок - название нашего проекта.

   Основной и самый большой по размеру заголовок создается с помощью оператора решетка "#" и затем пишется название. В нашем случае:

   
   # ForJavaRushPublication
   

2. Затем напишем чуть меньший заголовок, и напишем "Project Information". Меньший заголовок ставится большим количеством "#":

   
   ## Information
   

   И затем напишем информацию о проекте.

3. Вставим ссылки на свои статьи. Это делается очень просто, а если вы используете Haroopad то достаточно пикнуть шпаргалку, и шаблон вставится сам. Синтаксис таков: "[text](url)";

4. Вставим бейджики. А вот тут остановимся поподробнее.

   Во-первых давайте оформим их в виде таблицы, для красоты. Будет 2 колонки и 2 столбца. Синтаксис выглядеть это будет примерно так:

   А результат будет таким:

   Дальше, вставим гиперссылки на наши бейджики, но где их взять? Я показывал в предыдущей статье где взять Codecov, но какой взять не упомянул. Так как у нас Markdown файл, то и надо нам тоже Markdown Badge:

   Просто копируем его и вставляем в колонку в нашем Markdown. Но не забываем, что Codecov появился в ветке JaCoCo, но не в master, поэтому придется подправить ручками. Travis CI Badge берем прямо напротив названия проекта, там где log билда:

   Пикаем на бейджик, и тут всплывает окно настроек:

   Выбираем однозначно Markdown, а ветку, какую вам нужно. Я буду делать README.md для двух веток, и они чуть будут отличатся, ведь в ветке master еще я не внедрял Codecov.




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




6. Наш Markdown готов. Осталось добавить его в наш проект и все готово. Но не все сразу! Откроем нашу IDEA, и в Plugins проверяем что бы у вас была поддержка Markdown Support:

   У меня Ultimate IDEA поэтому у меня все есть, у Вас плагин по умолчанию может не стоять, но при создании файла с расширением md должно вылезти предложение его скачать. Качайте, и перезапустите вашу IDEA.




7. После импортирования написанного нами Markdown, открываем его через IDEA, и редактируем если надо. Вот так это выглядит через IDEA:

   Делаем push. После мы видим что при открытии проекта сразу прогружается информация о нем, это и есть наш README.md:

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




8. Сделаю тоже самое для ветки JaCoCo, дабы продемонстрировать Codecov Badge, ведь в нем у нас нету еще README.md. В результате у нас теперь два бейджика:

   Codecov показывает процент покрытия кода, причем он также может перенаправлять нас на страницу Codecov и показывать детальный отчет о покрытии кода.

Полезные ссылки

• Что нам говорит Wiki об Markdown;
• Каталог редакторов Markdown;
• Haroopad который я рекомендую;
• Об Markdown на сайте JetBrains;
• Markdown Navigator на том же JetBrains;
• Бейджики и все о них. Здесь можно выбрать стиль любого бейджика и настроить его под себя;
• Как прокачать свой open-source project? Ответит также эта статья;
• Предыдущая статья

Подведем итоги за цикл моих статей

1. Мы разобрали что такое CI, для чего он нужен и как его использовать в первой статье об Continuous Integration;
2. Мы поигрались с CC и поняли что это такое и зачем он нужен во второй статье об Code Coverage;
3. И в этой статье мы разобрали что такое Markdown, зачем он нужен и как эфективно его использовать.

Всем спасибо что читали эти долгие три статьи, буду надеяться они были полезными. Могут быть ошибки, ОтЧиПяТкИ в тексте. Всем спасибо за внимание!