Когда вы публикуете проект на GitHub, вы хотите разместить на сайте README.md, чтобы объяснить, чего вы пытаетесь достичь. На первый взгляд, формат для придания ему красивого вида ограничен. Это правда, он намеренно ограничен, чтобы сделать использование простым. Тем не менее, у вас есть хорошая свобода для вашего файла. Вы можете захотеть вставить картинки, скриншоты, сделать заголовки и изменить стиль текста. Это только самые основные вещи, которые вы можете делать, и все они являются стандартными для Markdown. GitHub Flavoured Markdown - это то же самое с некоторыми расширениями.
Стандарт Markdown
Markdown - это стандарт, разработанный Джоном Грубером. Основная цель Markdown - сделать так, чтобы файл можно было прочитать даже в чистом тексте. Если вы хотите посмотреть в редакторе, работающем только с текстом, вы должны легко прочитать его. Это очень полезно для пользователей vim и ему подобных. Обратите внимание и помните, что это стандарт для изменения текстовых файлов. Он не заменяет HTML. Наоборот, вы используете его для создания HTML там, где он полезен. В случае с GitHub, они будут форматировать файл Readme на сайте. Если вы следуете стандарту, вы можете быть уверены, что он будет выглядеть хорошо.
Поскольку GitHub добавил всего несколько расширений, вам следует начать с использования шпаргалки по Markdown и двигаться дальше. Вот список наиболее распространенных из них.
| Разметка | Расширения | Результат |
| # (1 на уровень) | Рубрики | |
| * | Курсив | |
| ** | Полужирный | |
| > | Блок-цитата | |
| 1. (и т.д.) | Упорядоченный список | |
| – | Неупорядоченный список | |
| `код` | Ваш код | |
| “` | Md-ext | Начало и конец блока кода |
| — | Горизонтальное правило | |
| [Описание](https://www.example.com) | Имя в квадратных и URL в обычных скобках | |
|  | То же, ссылка на изображение | |
| [1] | Md-ext | Сноска |
Списки могут быть вложенными с помощью отступов для всех элементов, которые вы хотите вложить.
Другими расширениями обычного Markdown являются расширения блоков кода, описанные выше. Они не всегда поддерживаются сервисами.
| Результат | Расширения | Результат |
| ### Заголовок {#custom-id} | Md-ext | Заголовок, к которому можно обратиться по его идентификатору |
| термин: определение | Md-ext | Список терминов с определениями |
| ~Ошибочный текст~ | Md-ext | Зачеркнутый текст |
| - [x] Задание для выполнения | Md-ext | Список задач, которые можно отметить галочкой |
Элемент таблицы очень простой, но для отображения необходимо несколько строк: Таблица:
| 1 2 3 | | Name| VALUE| | ----------- | ---------- | | Имя| 100 | |
Расширения GitHub.
GitHub добавил несколько расширений, чтобы упростить работу со ссылками на других людей и проекты. Некоторые из них - это таблицы, упомянутые ранее. Больше всего вам поможет расширение auto-link. Оно самостоятельно создает ссылку, когда вы используете его на GitHub.
Другие - это таблицы и элементы списка задач. Они удобны для отслеживания задач в проектах. Последнее, о котором стоит упомянуть, - это расширение Disallowed Raw HTML. С помощью этого расширения некоторые теги фильтруются при рендеринге HTML. Эти теги могут вызывать странные эффекты при рендеринге в GitHub.
Способы изучения GitHub Markdown
Если вы находите его запутанным, вы также можете перейти на страницу GitHub и воспользоваться встроенным редактором. Когда вы используете его, он будет автоматически заполнять некоторые функции. Это работает только для вопросов, но вы можете использовать это, чтобы понять некоторые вещи, например, эмодзи появляется в виде списка, когда вы набираете двоеточие (:).
Вы также можете найти проект на GitHub, который имеет красивый файл README, и клонировать его на свой локальный диск. Оттуда вы можете изучить файл с помощью любого редактора. В больших редакторах, Emacs и Vim, есть поддержка markdown с помощью расширений.
Если вы используете vim, вы можете установить расширение для подсветки синтаксиса с GitHub, vim-markdown. Это расширение покажет вам, что вы выполнили код правильно. Чтобы помочь вам увидеть, как он выглядит в готовом виде, вы также можете получить расширение live mark. С его помощью вы можете запустить веб-сервер, который будет показывать результат в реальном времени по мере набора текста.
В Emacs есть режим нетерпения, режим "живого спуска" и режим Realtime-preview. Все они показывают полученную страницу в браузере, пока вы набираете текст. Первый требует меньше библиотек, чем второй, но для его запуска необходим дополнительный фрагмент кода.
Заключение
Несмотря на то, что markdown - это небольшая и заведомо простая спецификация, она может быть немного запутанной для начала работы. Лучший способ научиться - использовать шпаргалку и написать свой документ Markdown. Вы можете обновить свой README.md на GitHub, а также получить большую поддержку от встроенных функций ваших редакторов. В качестве примечания, GitHub также поддерживает эмодзи, которые вы можете добавить в свой документ.