Markdown

Доброго часу доби, колеги! Всім хочеться після довгого шляху навчання показати роботодавцю свої плоди та показати їх тільки з кращого, професійного боку, чи не так? Я думаю так. Тому крім правильно спроектованого та реалізованого проекту нам потрібно вміти оформляти його. Не буде ж роботодавець читати весь ваш код проекту, щоб зрозуміти про що він і що в нього вкладено? У цій статті ми остаточно підіб'ємо підсумок попередніх двох, а саме: Continuous Integration і Code Coverage , дамо на "лицьовому" аркуші open-source project'а зрозуміти, що ми юзали у своєму проекті і що він є. Сьогодні ми поговоримо з вами про Markdown, поставимося нашими улюбленими питаннями "Що це?" і "Навіщо це?", Розберемося де його використовують і як з ним працювати. Навіть буде приклад,open-source project . Тож поїхали!

Що таке "Markdown"?

Так як ми з вами програмісти, відразу полезем у google і відкриємо першу ж посилання Wiki в якій сказано: Markdown - полегшена мова розмітки, створена з метою написання найбільш читаного і зручного для редагування тексту, але придатного для перетворення в мови для просунутих публікацій (HTML , Rich Text та інших). Тут, мені, якщо чесно, особливо й нема чого додати, я вважаю це майже ідеальним поясненням.

Навіщо нам цей "Markdown"?

Якщо чесно, взагалі-то і без нього не погано: Але давайте згадаємо нашу мету: написати грамотний шаблон проекту, який вже має 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. Напишемо заголовок – назву нашого проекту.

   Основний і найбільший за розміром заголовок створюється за допомогою оператора ґрат " # " і потім пишеться назва. У нашому випадку:

   # ForCodeGymPublication

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, навіщо він потрібен і як ефективно його використовувати.

Всім дякую що читали ці довгі три статті, сподіватимусь вони були корисними. Можуть бути помилки, ВІДЧИП'ЯТКИ в тексті. Всім дякую за увагу!